============================= Chapter 7 USE OF THE FILE REQUESTER ============================= 7.1 Description The CygnusEd Professional file requester is a powerful, intuitive and friendly file requester that helps you to select a file name, without forcing you to wait for it to read in a complete directory list. The CygnusEd Professional file requester displays a list of all available devices in a box in the right half of the requester. First in the list are all the available disks (such as DF0: and RAM:). Next is a list of all of the logical assignments (such as S:, SYS:, L:, C: etc.). These are the names that are set with the CLI ASSIGN command. Next is a list of al of the volume names present in the system. These are the names of disks (like CopyOfWorkbench). The large box on the left side of the file requester is where the list of files in the current directory goes. These lists are printed in two colors, one for directories inside the directory and the other for files. When the file requester appears, the path name of the file you were editing is placed inthe file name and directory string gadgets. The file name directory gadget is automatically active. The file requester immediately begins reading in a list of all the files in the directory. You do not have to wait for the file requester to finish reading in the entire directory to be read in. Page 65 ---------------------------------------------------------------------------- (If you have a floppy disk based system (no hard disks or ram disks of appreciable size) you might consider purchasing the FaccII Floppy Accelerator from ASDG. FaccII will dramatically increase the speed of file requester operation). 7.2 Controlling the File Requester With the Keyboard When the cursor is visible in the file name gadget you can type in a file name and then press return. If you want to change the directories first, you can move the cursor to the directory name by pressing SHIFT-RETURN or by moving th mouse over the directory name gadget and depressing the left mouse button. When the cursor is on the directory name you can type in a new directory name and press RETURN to tell the file requester to start getting a list of files in that directory. This will also move the cursor back to the file name gadget. Alternately you can press SHIFT-RETURN to move the cursor back to the file name gadget without telling the directory gadget to start getting a list of files in that directory. When the cursor is on either the file name gadget or the directory name gadget there are a number of keyboard shortcuts you can use to help in editing the text. RIGHT-AMIGA-x will clear out the name. RIGHT-AMIGA-q will restore the name to what it was when the cursor first appeared there. SHIFT-LEFT-ARROW and SHIFT-RIGHT-ARROW will move the cursor to the beginning and end of the name respectively. The left and right arrows will move the cursor left and right one character. The delete and backspace keys delete the character to the left of the cursor and under the cursor respectively. If you change your mind an don't want to select a file, you can clear the file name gadget (with RIGHT-AMIGA-x or with the backspace and delete keys) and hit RETURN. This will return a null name to CygnusEd Professional which will cancel the operation that brought up the file requester (or select the "Forget It" gadget in the file requester). Page 66 ---------------------------------------------------------------------------- 7.3 With the Mouse If you want to get a list of all the files in the root directory of one of the disks, logicals or volumes listed in the box on the right, simply click on the name or icon with the mouse. If the file requester has finished reading in the list of files for the directory, you can move around the list with the slide bar gadget and arrow gadgets to the right of the box. Directories contained in the current directory (i.e., sub-directories of the current directory) will be listed in black. By clicking on a line containing the name of a directory, CygnusEd Professional will begin reading in the contents of the sub-directory. Files will be displayed in white. Clicking on a file name will cause it to be highlighted and copied into the file name gadget near the bottom of the file requester. If you double click on a file name, then the file requester will return with the selected name, causing the selected file to be loaded by CygnusEd Professional (bypassing the need to select the OK gadget). To see the contents of the parent directory of the currently displayed directory, click on the PARENT gadget. The GET DIR gadget is to force the file requester to re-read the directory from the disk. The CygnusEd Professional file requester "remembers" the last directory read in order to cut down on the number of times the same directory will be read. The GET DIR gadget forces the file requester to forget the remembered directory list and read in a new directory list from the disk. This should be used whenever the list of file names becomes out of date. Note that an empty directory string gadget will refer to the current directory as it was when CygnusEd Professional was first started up. The OK gadget can be used when you've selected the file name you want and wish it to be loaded by CygnusEd Professional. Clicking on this gadget with a file selected is the same as having double clicked upon the file name. The FORGET IT gadget is used when you change your mind and don't want to select a file. It will cancel the operation that brought up the file requester. This can also be accomplished by using AMIGA-l (for Leave) or entering a null (or empty) file name. Page 67 ---------------------------------------------------------------------------- Page 68 ---------------------------------------------------------------------------- ============================== Chapter 8 STORING PREFERRED SETTINGS ============================== You can store your environment settings in a file which will automatically be loaded by CED when you start the editor. This "default" file is useful once you have set up the environment configuration that best strikes your fancy. By saving the settings, you won't have to reset different attributes each time you start CED. A defaults file stores all the settings in the Environment Menus, including the Global, File, and View parameters. When you run CygnusEd Professional it looks to see if there is a default file it should load settings in from. If you specified a file when you ran the editor then it will try to load a defaults file for that type of file. It does this by taking the suffix of the file (the characters after the period in the file name) and prepending it to CEDDEFAULTS. It then looks in the current directory and then in the S: directory (which is normally on your WorkBench disk). By allowing different defaults files to be loaded based upon the file you wish to edit, several sets of defaults files can be maintained which will configure CygnusEd Professional in different ways for different applications. For example, one settings file can be maintained for C program editing, while a different settings file can be used for editing text documents. This adaptability can be carried a step further by also maintaining separate macro definition files for different uses of CygnusEd Professional. See the section of macro definitions. Page 69 ---------------------------------------------------------------------------- If you didn't specify a file to be loaded when you ran the editor, or if there isn't a defaults file for that type of file then CygnusEd Professional will try to load in the defaults file for that type of file then CygnusEd Professional will try to load in the "default" default file. This file is simply called CEDDEFAULTS and will be looked for in first the current directory and then the S: directory. To summarize where CygnusEd Professional will look for default files when you run it: (current directory) CEDDEFAULTS.sfx S:CEDDEFAULTS.sfx (current directory) CEDDEFAULTS S:CEDDEFAULTS where "sfx" is the suffix of the file being edited (if there is one). CED will use the first file in this list that it finds. If none of these files can be found, then the environment settings used will be the ones built in to the program (i.e., the default default default settings (sorry - couldn't resist)). To save your settings, select "SAVE ENVIRONMENT" in the Global Settings of Environment. CED will ask for a filename, defaulting to the S:CEDDEFAULTS.sfx version. To explicitly load your settings, you can select "LOAD ENVIRONMENT/DEFAULT" or "LOAD ENVIRONMENT/SPECIFY...". LOAD ENVIRONMENT/DEFAULT loads in the same default file that would be loaded if you ran the editor and specified the current file to be loaded. That is CygnusEd Professional tries to read in CEDDEFAULTS.sfx, then S:CEDDEFAULTS.sfx, then CEDDEFAULTS and then S:CEDDEFAULTS. If you select LOAD ENVIRONMENT/SPECIFY then CygnusEd Professional brings up the file requester and lets you specify which defaults file you would like to load. Example: If you run CED with a file called "README.TXT", then CED will try to find the file "CEDDEFAULTS.TXT", then "S:CEDDEFAULTS.TXT", then "CEDDEFAULTS", and last "S:CEDDEFAULTS". As soon as one of these files is found, CED will use it as the defaults file and will stop looking for others. Page 70 ---------------------------------------------------------------------------- ============================ Chapter 9 USING MACROS EFFECTIVELY ============================ The macro key definition functions in CED let you automate repetitive operation, create your own keyboard shortcuts for menu operations that lack them, or expand the utility of the editor. You can assign a macro to a single keystroke or to a string of keystrokes (ala MicroEmacs). Macros can be assigned to any key on the numeric keypad, to the function keys or to any key on the main keyboard, al long as you also press ALT or Control. Macros can be assigned to: -------------------------------------------------------------- | Key | Valid Qualifiers | |---------------|----------------------------------------------| | F1 to F10 | none, ALT, CTRL, SHIFT, or any combination | | Keypad keys | none, ALT, CTRL, SHIFT, or any combination | | Main Keyboard | ALT, CTRL or any combination | -------------------------------------------------------------- By using different combinations of ALT, CTRL and SHIFT you can assign many macros to the same key. If you are using a string of keystrokes to invoke a macro, the extra keys (past the first key) can be any key on the keyboard. Of course you can't assign a macro to a key such as ALT or CTRL itself, or to the arrow keys. Page 71 ---------------------------------------------------------------------------- To define a macro, you select BEGIN DEFINITION from the menu (or press AMIGA-M). You then enter the initial key to invoke the macro with. A requester now appears, asking if you would like to use more keystrokes to invoke the macro. Usually you will answer "no" to this requester. If you answer "yes" then you enter the subsequent keystrokes used to invoke the macro. For example to define CTRL-S to swap the letter the cursor is on for the character immediately following it (the equivalent of "xp" in VI), you would do the following: Press: AMIGA-M ;To start defining the macro. CTRL-S ;To specify what key to attach the macro to. N ;To specify only one key to invoke the macro. DEL ;Delete the character under the cursor. RIGHT ARROW ;Move the cursor over. CTRL-DEL ;Undelete the first character. LEFT ARROW ;Return to original position. AMIGA-M ;End the macro definition. From then on, pressing CTRL-S will swap the letter the cursor is on with its successor. Macro keys remain in memory for as long as CED is running, unless you select CLEAR DEFINITIONS or LOAD DEFINITIONS or replace a single macro invocation with something else. Macros are effective in all windows (or views). To store your macro keys so they will automatically be available whenever you start CED, select SAVE DEFINITIONS. This will store the macros in a file. By default, this file is called S:CEDMACROS. CygnusEd Professional looks for an S:CEDMACROS file if it doesn't find a CEDMACROS file in the current directory when you run CygnusEd Professional. To load a macro file explicitly (by specifying the file name), you can select LOAD DEFINITIONS. By maintaining several sets of macro files, you can custom tailor CygnusEd Professional for each type of file you might work upon. For example, a set of C programming language macros might be nice when programming. Or perhaps a set of macros tailored to your favorite document formatter. Page 72 ---------------------------------------------------------------------------- Here is an example that was used while writing this manual. A macro was written which was used to insert the string "CygnusEd Professional" with the touch of one key. It was set up as follows: AMIGA-M ;To start defining the macro. F10 ;To specify what key to attach the macro to. N ;Only one key to invoke this macro. CygnusEd Professional ;Text to be inserted into document. AMIGA-M ;End the macro definition. Page 73 ---------------------------------------------------------------------------- Page 74 ---------------------------------------------------------------------------- =================== Chapter 10 ADVANCED TOPICS =================== 10.1 HOT Keys And Dormancy When you are using CygnusEd Professional you may find that you are constantly entering and exiting out of the editor, only to start it up again moments later. If you have CygnusEd Professional on a floppy drive then this is inefficient because it takes a while to load CygnusEd Professional from floppy. If you have CygnusEd Professional on a ram disk then this is inefficient because when you are using CygnusEd Professional there are actually two copies in memory, one in the ram disk and the other being executed. The HOT-START function of CygnusEd Professional is designed to fix this problem. With this feature of CygnusEd Professional enabled you can make CygnusEd Professional stay in memory when you exit so that it can be revived with a hot key, a CLI program or a WorkBench program. CygnusEd Professional provides two "NOT KEYS" that CygnusEd Professional will hear from anywhere on the Amiga (CygnusEd Professional doesn't have to be the active window to hear them!). These two commands will tell a CygnusEd Professional that is already running somewhere on the system to become active or to kill itself off. The HOT-Start Enabled mode (set in the GLOBAL SETTINGS menu) will cause CygnusEd Professional to become dormant when you quit out of the last view CygnusEd Professional is displaying. This dormancy is a state where CygnusEd Professional is still in memory, but is waiting for one of the HOT keys or the ED activator program (provided with CygnusEd Professional, see also ED - THE CygnusEd Professional ACTIVATOR) to be executed. Page 75 ---------------------------------------------------------------------------- The reason you would want to leave CygnusEd Professional dormant in memory is because then you don't have to load it from the disk the next time you use it. In fact, you don't even have to type the command line, or click on any icons, if you don't want to. To allow CygnusEd Professional to become dormant after you are finished editing, you must first activate the HOT-Start Enabled option, otherwise CygnusEd Professional will exit completely. If the option is activated, then when you quit the last view, CygnusEd Professional will become dormant and wait for one of the following: 1. HOT-START Pressing RIGHT-ALT + RIGHT-SHIFT + RETURN together will cause CygnusEd Professional to start up with a clear file instantly. You can use this while CygnusEd Professional is open already; the CygnusEd Professional screen will pop to the front and become the active window. When CygnusEd Professional is dormant it does its best to reduce the amount of memory it consumes. 2. HOT-KILL RIGHT-ALT + RIGHT-SHIFT + CONTROL + RETURN together will cause a dormant CygnusEd Professional to kill itself off completely. This will free up the memory that a dormant CygnusEd Professional takes up (because a dormant CygnusEd Professional is still in memory). If CygnusEd Professional is open already then the CygnusEd Professional screen will pop to the front and become the active window (and NOT be killed off). 3. ED ACTIVATOR The ED program provided on the CygnusEd Professional distribution disk will pass file name(s) to CygnusEd Professional to edit. If CygnusEd Professional is dormant at the time, it will activate CygnusEd Professional much the same as HOT-START does. See Section 13 - ED - THE CygnusEd Professional ACTIVATOR for more information on ED. CygnusEd Professional can be started up initially in a dormant state without displaying a screen at all. Many people will find this very useful as they can then start up CygnusEd Professional in their S:Startup-Sequence script and then have CygnusEd Professional available on call with the HOT-START sequence. Page 76 ---------------------------------------------------------------------------- To start CygnusEd Professional up as dormant, you must use the CLI or modify your Startup-Sequence to contain the line: CED -r CygnusEd Professional will then load into memory and will become dormant, waiting for a signal via the HOT keys or ED. CygnusEd Professional is designed to detach itself from the invoking CLI so that the invoking CLI can itself be closed without waiting for CygnusEd Professional to terminate. Thus "CED -r" in a startup-sequence will not interfere with the initial CLI closing at the end of the startup-sequence with an "EndCLI". However, if CygnusEd Professional has been disconnected from its invoking CLI, then it will no longer be able to execute DOS commands (ARexx commands will still function however). To keep CygnusEd Professional from disconnecting itself from the invoking CLI, use the "-keepio" command line option. This will allow DOS commands to be launched from within CygnusEd Professional. If you elect to use -keepio then you should "run" CygnusEd Professional so that your CLI will continue to be available for your use while CygnusEd Professional is running. More information on this can be found in the "Executing DOS commands" section. 10.2 Starting CygnusEd Professional With Multiple Files When you start up CygnusEd Professional, you can specify more than one file (up to 10, in fact). When you do, all the files you have specified will be loaded in and displayed in seperate views. From the CLI, just enter: CED file1 file2 file3 From the WorkBench, you can use the extended-select feature of the WorkBench. This is done by clicking on the first file once with your left mouse button, then hold the SHIFT key down while clicking once on the next file(s). When you have selected all the files you want to edit, click twice on the CED icon - while still holding the SHIFT key down. If one of the files you want to edit has CygnusEd Professional as its "default tool" (program that gets run when you double click on it) then you can double click last on this file instead of on the CED icon. Page 77 ---------------------------------------------------------------------------- 10.3 Using the Columnar Block Effectively A feature which sets CygnusEd Professional apart from most editors is CygnusEd Professional's ability to operate on vertical as well as horizontal blocks. The common MARK BLOCK method (for horizontal blocks) is used most often, but a second method COLUMNAR BLOCK (for vertical blocks) is also supported. With this alternate method, you can select any rectangular area in the document to copy or cut, and then paste. You can use it to shift text horizontally, format your text into multiple columns, move diagrams around, etc. 10.3.1 Shifting Text Horizontally It is often helpful to move a piece of text to a different horizontal or vertical position. For example, say we want to move a diagram or a table to a different area on the screen. We would select one corner of the area to be moved (the diagram) using MARK COLUMNAR BLOCK and then move the cursor to the opposite corner of the rectangular section to be moved. We then CUT BLOCK to remove the area from its original location into the block buffer. Then we position our cursor to the corner of the area where we want to insert the area and use INSERT BLOCK to move it into place there. Note that vertical block operations are normally done with LAYOUT mode ON in the FILE SETTINGS menu. LAYOUT mode means that you can move the cursor anywhere on the screen, even beyond the EOL character (beyond the physical ends of lines). This allows you to go far enough over to the right to mark the columnar block, even though the line you are on may not extend that far. Having CygnusEd Professional in LAYOUT mode also ensures that the diagram will be padded on the left with spaces where necessary to keep all the lines of the block neatly lined up. If you are not in LAYOUT mode when you insert a columnar block then the individual lines will be tacked onto the ends of the lines already there. 10.3.2 Making Multi-Column Text Files You might want to format some text into multiple columns. This format, used in newspapers and most other printed media, is available in limited form in CygnusEd Professional by using the COLUMNAR BLOCK commands. Page 78 ---------------------------------------------------------------------------- For example, let us say that we have two paragraphs which we want side by side in columns, format-filled (left- and right- justified) to 36 characters wide each, with a four character space between the two columns. Here is the method to do this: First, make sure LAYOUT mode is on, then set the right border to column 36. Then use the FORMAT WITH FILL (AMIGA-f) command to reformat each paragraph. Now you have both paragraphs format-filled as 36 character-wide columns - but they are still end-to-end in the same column. Next, use the MARK COLUMNAR BLOCK to mark the beginning of the second paragraph and go to the end of the paragraph and select CUT BLOCK. Be sure that you go far enough to the right to mark the entire paragraph. This will move the block out of the document and into CygnusEd Professional's buffer. Lastly, move the cursor to the first line of the first paragraph, but go to column 40. This is the corner at which you want to paste the other column, so select PASTE BLOCK. You now have two paragraphs side by side in 36 character columns, format-filled with a four character gap between them! Note: As you can see, this method is useful only when the text you have written is not likely to require changing later, since CygnusEd Professional does not think of columnar text as such. Moving the text this way should be the last change you make to your document. 10.4 Converting Tabs And Spaces With Print Functions CygnusEd Professional provides the ability to convert tabs to spaces and vice versa. To convert a file or a paste block, you use the Print commands in the PROJECT menu. When you have specified where the output will go (i.e., the printer PRT: device, or a file name), CygnusEd Professional will ask you if you want to convert from TABS to SPACES or from SPACES to TABS. For example, you are working on an assembly language program and use irregular tabs stops ( a tab stop for instruction, parameter, comments). If you "type" this file to the printer device then it will not be printed properly, since the printer device and your printer think of tabstops as being placed at regular intervals. If you want to print this file out to your printer, select TABS to SPACES after selecting print file an deselecting the output file (or PRT:). This will automatically replace all existing tab characters with the appropriate number of spaces - so your printer doesn't need to be programmed with your peculiar tab settings. Page 79 ---------------------------------------------------------------------------- Another important use of this function is if you have a file with tabs of one size or setting and want to convert it to tabs of another size or setting, without affecting the position of the text, you can use the TABS to SPACES output with the old format in effect, then read in the output file (containing now tabs) and change to the new TAB settings. YOU can then PRINT the file again with the SPACES to TABS option - your file looks the same as it did before, but has the new tab sizes or settings. For another example, a use who has written a document with the ED screen editor (provided with WorkBench) wants to convert to actual tabs of length 3. He would use the SPACES to TABS setting on the PRINT options to automatically entab the file. Page 80 ---------------------------------------------------------------------------- =========================== Chapter 11 THE DOS/ARexx INTERFACE =========================== 11.1 Description ARexx is an interpreted language for the Amiga with the built in ability to send commands to and receive commands from other programs. ARexx programs can be written to control the operation of other programs that have an ARexx interface built in. CygnusEd Professional has an extremely powerful ARexx interface built into it. ARexx is a commercial product, available in computer stores or direct from it's author, William Hawes. For those who don't wish to purchase ARexx, it is possible to control CygnusEd Professional using ARexx style commands from any language on the Amiga. It will usually not be as simple as doing it from ARexx, since ARexx is specifically designed for that purpose, but powerful controlling functions can be built into other programs to allow them to smoothly interface with CygnusEd Professional. A parallel feature is the ability to execute DOS commands from CygnusEd Professional. This allows two way communications with non-ARexx programs as well as ARexx programs. Page 81 ---------------------------------------------------------------------------- The best way to explain the benefits of having an ARexx interface is with an example. Having an integrated programming environment can make software development much easier. Typically the compiler is built into the editor and you can compile, link and run the program with a single keypress. This in itself is no big advantage, the real advantage comes when some errors are encountered in the compilation. Then because the editor is integrated with the compiler, a single keystroke can position the cursor over the first error while a description of the error appears at the bottom of the screen. After correcting that error another keystroke takes you to the next error, or a different keystroke takes you back to the previous error. The main disadvantage of an integrated environment is that if you want it's benefits, you are forced to use their editor, even if you don't particularly like it. An ARexx interface will allow you to set up your favorite ARexx equipped text editor (CygnusEd Professional) to behave like an integrated editor, with single key compile, link and run and single keystroke next/prev error commands. 11.2 Sending Commands to ARexx In the SPECIAL menu there is an entry called 'DOS/ARexx interface'. There is a subitem list attached to this entry which contains the following entries: Send DOS/ARexx command Install DOS/ARexx command Load DOS/ARexx commands Save DOS/ARexx commands command #1 - F1 command #2 - F2 command #3 - F3 and so on... To send a command to ARexx, simply select the "Send DOS/ARexx command' menu item. A requester will pop up, asking for the command. Type in the command you wish to run followed by a carriage return. You send any command to ARexx, but typically you'll send the name of an ARexx program that you have written. ARexx will look for the program in the current directory and in the REXX: directory. If you don't put a file extension on the file, CygnusEd Professional will also try looking for the file name with ".ced" appended to it. You may also store ARexx commands for use with the function keys using the 'Install DOS/ARexx command' menu option. When you select "Install DOS/ARexx command, CygnusEd Professional will prompt you for which slot (corresponding to the ten function keys) you want the command put into. Then CygnusEd Professional will prompt you for the command itself. Page 82 ---------------------------------------------------------------------------- Now that you have installed a command, it can be sent to ARexx simply by selecting it's menu entry with the mouse. Alternatively it can be sent by pressing the corresponding function key, as long as no macro has been assigned to that key. The ARexx commands can also be assigned to any key, using the macro functions documented elsewhere in the manual. Simply assign a macro consisting of the menu selection to the key you want to invoke it with. After you've installed a number of ARexx commands you can save them to a file so that they will be automatically loaded the next time you run CygnusEd Professional. The "Save ARexx commands" command is used for this purpose. The default file name is "S:RexxCommands". If yo9u save the file there, it will automatically be loaded and the commands installed when you run the editor. The RexxCommands file is looked for first in the current directory, then in the S: directory. The "Load ARexx commands" command can be used to load in any secondary command files you may create. Note that new commands loaded in will overwrite ALL of the old commands. 11.3 Executing DOS commands from CygnusEd Professional DOS commands may be executed from CygnusEd Professional if four conditions are met. Those conditions are: 1) CygnusEd Professional must be started up from a CLI window, 2) CygnusEd Professional must be "run" with the AmigaDOS run command, 3) the -keepio option must be specified when CygnusEd Professional is run, and 4) the AmigaDOS "run" command is present in your C: directory. If these conditions are not met, only ARexx commands can be run from CygnusEd Professional. The proper startup command looks like this: run ced -keepio The CLI window is used to allow DOS commands performed from CygnusEd Professional to have an input/output window. The editor must be "run" to keep the CLI window active. The -keepio option tells CygnusEd Professional to remain attached to the CLI window it was called from. Without the -keepio option enabled, CygnusEd Professional disconnects itself from the CLI window, allowing the window to be closed (using EndCLI) while CygnusEd Professional is still running. Page 83 ---------------------------------------------------------------------------- Assuming you have started CygnusEd Professional from a CLI window, using "run ced -keepio", you can execute DOS commands by first selecting Install DOS/ARexx Command or using Send DOS/ARexx Command. Rather than entering an ARexx command, enter the DOS command you wish to execute. You can execute this command as you would one of the ARexx commands (described above). CygnusEd Professional will attempt to send the command to ARexx. If ARexx is not present in your system or indicates, if it is present, that it doesn't make sense of the command, CygnusEd Professional submits the command for execution by the CLI. CygnusEd Professional "run"s the program, so the AmigaDOS run command must be in your C: directory. Since CygnusEd Professional runs the program, control returns to the editor immediately so that you can continue editing while the program executes. Unfortunately there is no way to tell whether the program was successfully run from the editor. If the program prints a completion message to the CLI screen, you can jump back to that screen and see if it completed properly. Remember that you can use the output redirection capability of the CLI to send the output of your DOS commands to a file which can then be loaded into CygnusEd Professional. Please consult your AmigaDos manual for more information about output redirection. When CygnusEd Professional runs a program it resets as many things as possible to the way they were when CygnusEd Professional was first run. This means that the new program will be running at the priority CygnusEd Professional started at and on the same screen for DOS requester to appear on. Note: A limitation of the DOS command execution facility is that CygnusEd Professional will be unaware of any directories which may have been added to your "PATH". That is, CygnusEd Professional will only be able to execute programs which are located in C: or in the current directory. 11.3.1 Using Change Current Directory With DOS Commands By Default, the current directory from which any DOS command execution will be based, is the directory you were in when you started CygnusEd Professional. To change the current directory to another location, use the "Change Current Directory" command located in the PROJECT menu. For example, if df0: was your current directory when you started CygnusEd Professional from the CLI, executing a "Dir" from inside the editor will produce a directory of df0:. If you wished to view the df1: directory you can either execute "Dir Df1:" from inside the editor or Change Current Directory to Df1: and execute "Dir". Page 84 ---------------------------------------------------------------------------- 11.4 Receiving Commands From ARexx If you want to send commands from an ARexx program to CygnusEd Professional, you first have to tell ARexx of your desire. This is done with the ARexx "ADDRESS" command, like this: ADDRESS 'rexx_ced' This is not necessary if the ARexx program will be invoked from within CygnusEd Professional as this is done automatically in that case. 11.4.1 Menu Commands You now have access to over a hundred CygnusEd Professional commands from ARexx. Most of these commands are from the menus. These commands can be executed simply by typing their name, from the menus, into the ARexx program. For instance, if you want to move the cursor to the top of the current file, you an use the "beg of file" command from the "Move" menu, like this: beg of file The complete command name must be used, complete with spaces. The commands are not case sensitive, and any periods or question marks at the end of the command can be left off if desired. Therefore, the "search for..." command can be entered in any of these ways: search for... search for SEARCH FOR sEARCH fOR The only menu selections that can not be easily accessed this way are some whose text changes (like the ARexx commands in the ARexx interface menu) or those like the tab sizes which are only a single number. These menu selections can be accessed from ARexx programs with the "menu" command. The "menu" command takes two or three parameters. The first is the menu number, from 0 (for the PROJECT menu) to 7 (for the MOVE menu). The second parameter is the item number, which is a number from 0 to the number of items minus 1. If there are any subitems then the third parameter is needed. It specifies the subitem number, from 0 to the number of items minus 1. For example, if you want to set the tab size to eight you can use the menu command like this: Page 85 ---------------------------------------------------------------------------- menu 2 1 7 Or you can set the screen width to 640 like this: menu 1 2 0 Menu commands with an elipsis (three periods in a row) expect additional parameters. Examples are "Open...", which wants a file name, and "Jump to line...", which wants a line number. If you just put he command's name in the ARexx program then the usual requester will be brought up. However you can also put the parameter right in the ARexx program. For instance: open sys:s/startup-sequence jump to line 150 If a command normally brings up one of the information requesters (like the "All macro definitions cleared" message after using the "clear definitions" command) or one of the yes/no requesters (like the "156 changes have been make to manual. They will be lost. Ok to continue" that shows up if you try to exit without saving), you can get ARexx to respond to the requester for you, without it even showing up. If you put a 1 (for yes) or a 0 (for no) after the command that will normally bring up the requester. The 1 or 0 will make the requester not appear, and CygnusEd Professional will act as if you hit the corresponding gadget. The requesters that just bring up information and have only one requester gadget, can be made to not appear with either a 0 or a 1. Therefore, if you want to clear the current file and you don't care if you lose any changes, go like this: clear 1 Any time that one of these text message requesters comes up, the text from the requester is returned in the variable 'result' if 'options result' has been set in ARexx. This can be used to detect when a search fails by checking for the string "something not found". There are several extra CygnusEd Professional commands that are only accessible from the ARexx interface. All of the ARexx commands are listed below, in alphabetical order. Page 86 ---------------------------------------------------------------------------- 11.4.2 Special ARexx Functions BACKSPACE: This command is the same as pressing the backspace key. CEDTOFRONT: This command brings the CygnusEd Professional screen and window to the front and activates the window. DELETE: This command is the same as pressing the delete key. DOWN: This command is the same as pressing the down arrow key. GETFILENAME: This command allows you to use the CygnusEd Professional file requester. It brings up the CygnusEd Professional file requester and lets the user select a file name. If you put a file name after the command name then that file name will be the default, it will appear in the file requester when it first pops up. Note: CygnusEd Professional will not return any results unless you first turn on "results". This is done with the ARexx command 'options results'. After this command has been executed, any results returned by CygnusEd Professional will be in the 'result' variable. Example: options results getfilename 'sys:s/startup-sequence' say 'File name selected was' result GETNUMBER: This command allows you to use the CygnusEd Professional getnumber requester. It brings up the CygnusEd Professional getnumber requester and lets the user enter a number. If you put a number after the command name then that number will be the default, it will appear in the getnumber requester when it first pops up. Note: CygnusEd Professional will not return any results unless you first turn on "results". This is done with the ARexx command 'options results'. After this command has been executed, any results returned by CygnusEd Professional will be in the result variable. Example: options results getnumber 25 say 'The number the user selected was' result Page 87 ---------------------------------------------------------------------------- GETSTRING: This command allows you to use the CygnusEd Professional getstring requester. It brings up the CygnusEd Professional getstring requester and lets the user enter some text. If you put some text after the command name then that text will be the default text, it will appear in the getstring requester when it first pops up. Note: CygnusEd Professional will not return any results unless you first turn on "results". This is done with the ARexx command 'options results'. After this command has been executed, any results returned by CygnusEd Professional will be in the result variable. Example: options results getstring 'Default string' say 'The string selected was' result JUMPTO: This command is an extension to the "jump to line" command in the menus. The jumpto command lets you specify a column number as well as a line number. For instance: jumpto 15 233 This command moves the cursor to column 15, line 233. LEFT: This command is the same as pressing the left arrow key. MENU: This command lets you execute specific menu commands by specifying the menu, item and subitem number of the command. All numbers go from 0 to the number of items. This command is described more fully above. The example below will set the tab size to four. menu 2 1 3 OKAY1: This command lets you use the CygnusEd Professional information requester, called okay1 because it brings up a requester with just one gadget. You must specify the text you want printed in the requester. If you want the text to appear on multiple lines, separate the lines with line feeds (ascii value 10). For example: okay 1 'Testing the okay1 function' '0A'X 'Note the line feed' Page 88 ---------------------------------------------------------------------------- OKAY2: This command is very similar to the okay1 command. The only difference is that the requester brought up by this command has two gadgets on it. The user can then respond to this requester with either a yes or a no. If results have been turned on (see the getnumber command) then a 1 or a zero will be returned, for yes and no. options results okay2 'Do you want anything more?' say 'This users answer was' result RAWKEY: This command allows you to simulate the typing of any key on the keyboard. This command takes two parameters. The first one is the rawkey code of the key to be pressed, the second one is the qualifier. For a list of the values to be used for the code and qualifier, please consult the AmigaDos manual or the Rom Kernel Manual. Note that this command should not actually be needed, since all CygnusEd Professional commands can be accessed without it. The example below is equivalent to pressing the down arrow key, and can be accessed more easily with the "down" command. rawkey 77 0 STATUS: This command is the most complex of all the ARexx/CygnusEd Professional commands. This command allows you to find out the value of over seventy of CygnusEd Professional's internal variables. Before using this command it is important to turn on results with the command "option results". After this command has been executed, any results returned by CygnusEd Professional will be in the result variable. "Status" takes one parameter, the number of the variable you want information on. Valid numbers currently range from 1 to 67. A list of what is returned for various numbers is presented below. Some of the variables whose values are returned hold a true or false value. For instance, in the screen height menu, interlace can be either on or off, true or false. This is returned by the status command as 1 (true) or 0 (false). Those that return true or false values have a question mark after them in the table below. Page 89 ---------------------------------------------------------------------------- Some of the numbers returned, such as cursor position, range from zero upwards, instead of from one upwards as they are displayed in the status line. Some of the values returned are global. That is, they are the same no matter which file is active. The screen height and width are global. Some of the values are specific to a particular file. The size and location of the file are file specific. Some of the values are specific to a particular view. The cursor position is specific to a particular view. The file and view specific variables returned are those that apply to the currently active view. 1 Interlace? 2 Hot start enabled? 3 Force custom screen? 4 Icon creation? 5 Custom height? 6 Custom width? 7 This returns a string which shows the actual positions of all of the tab stops. A capital 'T' is put where the tab stops are and '-'s are placed where tab stops are not. 8 Tab size. 9 Word wrap? 10 Scroll jump? 11 Layout mode? 12 Insert mode? 13 Tabs = spaces? 14 Right border. 15 This returns the actual address of the file in memory. Do not abuse this information. Directly modifying the file in memory is definitely not safe. 16 This returns the current size of the active file. 17 The number of lines in the active file. 18 The number of changes made to the active file. Page 90 ---------------------------------------------------------------------------- 19 The complete path name and file name of the active file. 20 The directory name of the current file. 21 The file name, and directory, of the current file. 22 The number of windows onto the current file. 23-25 These three values contain the line number stored in the three marks, settable with the 'mark location' command. 26 This variable holds the line number of the automark. For information on when this mark is set, please see the commands summary portion of the manual. 27-29 These three values contain the column number stored in the three marks, settable with the 'mark location' command. 30 This variable holds the column number of the auto-mark. 31 Tabs visible? 32 Spaces visible? 33 EOL's visible? 34 Escape codes visible? 35 Status line on? 36 This is how many columns from the left edge of the screen the left scroll border is. 37 This is how many columns from the right edge of the screen the right scroll border is. 38 This is how many rows from the top edge of the window the top scroll border is. 39 This is how many rows from the bottom edge of the window the bottom scroll border is. 40 Left scroll bar? 41 Status line type. This is 0 or 1. 42 Column number of leftmost displayed column (usually zero). 43 Line number of topmost displayed line. Page 91 ---------------------------------------------------------------------------- 44 Cursor x postion relative to first displayed character. 45 Cursor y position relative to first displayed character. 46 Cursor x position relative to the beginning of the line. 47 Cursor y position relative to the beginning of the file. 48 Pixel x location of the left edge of current window. 49 Pixel y location of the top edge of current window. 50 Number of columns displayable. 51 Number of lines displayable in the current window. 52 This is the column the cursor wants to be in, but may not actually be in if the current line is too short or if the middle of a tab character is in that column. 53 Width of the entire CygnusEd Professional window in pixels. 54 Height of the entire CygnusEd Professional window in pixels. 55 The contents of the line the cursor is on. This is a string whose length varies, depending on how long a line the cursor is on. 56 This returns the offset, in bytes, of the start of the current line from the beginning of the file. 57 Current line number. 58 Length of current line in memory. 59 Length of current line on screen. This may be different than the length of the current line in memory because tabs may take up extra space and escape codes may be hidden. Page 92 ---------------------------------------------------------------------------- The next six status numbers return the contents of various cut and paste buffers. Every time you cut a block, backspace delete a word (ALT backspace), delete a word (ALT delete), delete a line, backspace a character or delete a character, the deleted text is put into a buffer - a different buffer for each type of deletion. The block buffer can be huge. Beware of asking for the contents of this. You may get more than you asked for. 60 Contents of the block buffer. 61 Contents of the backspace word buffer. 62 Contents of the delete word buffer. 63 Contents of the delete line buffer. 64 Contents of the backspace buffer. 65 Contents of the delete buffer. 66 Total number of CygnusEd Professional window open. 67 Total number of CygnusEd Professional file open. 68 Right scroll bar? RIGHT: This command is the same as pressing the right arrow key. TEXT: This command takes as a parameter some text which will be inserted into the current file, just as if you typed it in. For example: text 'This is some text to be inserted in.' '0A'X The text is put in quotes to prevent ARexx from turning it all to capitals and the '0A'X at the end is ARexx's way of representing a line feed (end of line) character in hex. The line feed character can not simply be typed in like other characters because it as a control character and gets special treatment from ARexx. UP: This command is the same as pressing the up arrow key. 11.5 What Do The Error Numbers Mean? Most status information from CygnusEd Professional is returned inthe result variable. This includes such as information as "Not found" after a search command fails. However some errors are serious enough to warrant returning an error code. This error code is put into the rc variable and results do not have to be enabled for it to be printed. Page 93 ---------------------------------------------------------------------------- Error code 3: This error happens if you specify an invalid number to the status command. Any number smaller than one or larger than 68 will cause this error. Error code 5: This means that the command you specified could not be found. I.e., it was not a CygnusEd Professional ARexx command. Check the spelling, make sure the entire menus string was entered (if it was a menu command) and make sure you have used the ADDRESS command to let ARexx know where to look for the commands. If you try to send a command to ARexx from CygnusEd Professional and a message comes up saying "ARexx could not find the program you specified. This could mean the file doesn't exist, isn't in the current or REXX: directory, has the wrong file extension (.ced is the default) or doesn't have a comment in the first line. Error code 10: This error happens if you are executing an ARexx program from the editor and you close the last window and then try to execute more commands. Once the final window is closed, no more commands may be executed. Note that the CygnusEd Professional window doesn't actually close until the ARexx program has finished executing. 11.6 Sending Commands to CED From Other Languages Commands can be sent to CygnusEd Professional from other languages besides ARexx. Since the ARexx interface is implemented by passing messages and forth, all other languages should have no problems communicating. To send a message to CygnusEd Professional you should first allocate a CedMsg structure. The C language declaration for this structure is: struct CedMsg { struct Message cm_Node; LONG RFU1; LONG RFU2; LONG rm_Action; Page 94 ---------------------------------------------------------------------------- LONG rm_Result1; LONG rm_Result2; char *cm_Args[16]; LONG RFU7; LONG RFU8; LONG RFU9; LONG RFU10; LONG RFU11; LONG RFU12; }: Only some of these fields are needed. The others are for use with ARexx only. The most important field is the cm_Args field or, to be more precise, cm_Args[0]. All commands to CygnusEd Professional are null terminated strings and a pointer to those strings is always put into cm_Args[0]. If you are merely interested in sending commands to CygnusEd Professional and don't care about getting results back you can ignore all of the other fields. The rm_Action field is a flag field. The only flag we are interested in is the RXFB_RESULT flag, which is bit 17 (counting from zero). When this bit is set, CygnusEd Professional will return results if appropriate. The commands that can cause CygnusEd Professional to return results (if this bit is set) are the status command, the okay1 command, the okay2 command, the getstring command, the getfilename command and any commands that cause an information requester (with one or two gadgets) to appear. The rm_Result1 field is used to return any error numbers to the driver program. The error numbers and their meanings are documented above. The rm_Result2 field is used to return results from CygnusEd Professional when the RXFB_RESULT flag is set in the rm_Action field and a result returning command is sent to CygnusEd Professional. If the result is a number (such as would be returned if you asked for the status of a flag such as the word wrap flag) then the number itself is in the rm_Result2 field. If the result is a string (such as the current line or the tab stops) then rm_Result2 is a pointer to a string, usually null terminated (if the contents of a block buffer is returned there may be other zeroes in the string). The length of the string is returned in the previous long word. It is your responsibility to free up the memory. The following routine will do that for you quite handily. FreeMyString(location) char *location; { long *RealLocation; if (!location) return; RealLocation = (long *)location; RealLocation--; FreeMem(RealLocation, *RealLocation); } Page 95 ---------------------------------------------------------------------------- To send a message to CygnusEd Professional you need to follow these steps. Put a pointer to your command string (all ascii, including any numbers) in cm_Args[0]. The cm_Node.mn_Node.ln_Type field should be filled with NT_MESSAGE, an Amiga constant. The cm_Node.mn_Length field should be filled with sizeof(struct CedMsg). The rm_Result2 field should be zeroed to make sure you don't mistakenly think that CygnusEd Professional has returned a result when it hasn't. If you want results then the rm_Action field should be set to 1 shifted left by RXFB_RESULT bits and should be zeroed otherwise. Now you need to do a FindPort() on "rexx_ced" to find out where to send the message to. You also need to do a CreatePort("MyPort", 0L) so you will have a return port. The address of this return port should be put into cm_Node.mn_ReplyPort. Now you can send the message. You then need to wait for a reply and then delete your reply port. The code below does all of this for you. Note this assumes that you want results and that you will delete any strings that are returned to you. #define RXFB_RESULT 17 BOOL SendCygnusEdMessageGetReply(thecommand) char *thecommand; { TheMessage.cm_Args[0] = thecommand; TheMessage.cm_Node.mn_Node.ln_Type = NT_MESSAGE; TheMessage.cm_Node.mn_Length = sizeof(struct CedMsg); TheMessage.rm_Action = 1L << RXFB_RESULT; /* We do want results. */ TheMessage.rm_Result2 = 0; /* clear out the last result. */ if (!(CedPort = FindPort("rexx_ced"))) return((BOOL)FALSE); if (!(MyPort = CreatePort("MyPort", 0L))) return((BOOL)FALSE); TheMessage.cm_Node.mn_ReplyPort = MyPort; PutMsg(CedPort, &TheMessage); WaitPort(MyPort); DeletePort(MyPort); return((BOOL)TRUE); } Page 96 ---------------------------------------------------------------------------- Page 97 ---------------------------------------------------------------------------- Page 98 ----------------------------------------------------------------------------