=========================== 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 ----------------------------------------------------------------------------