Revision of Compunet Software ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This revision of version 2.1 of the Amiga Compunet software supports the following additional features: - Support of ARexx amd Amiga Scripts as a 'macro language' - Use of ARP file requestors - Preservation of directory entries in the Editor - Extended menu items, supporting quick movement between frames on the shelf - A Shelf Directory window, giving a view of what is on the shelf, and an easy way to manipulate it - Audible warning of completion of uploads and downloads - Cursor positioning by mouse - Addition of filenotes to downloaded files - Extra Shelves, allowing the saving of frames to a temporary area, and the inspection of files without disturbing the working shelf - Addition of number of bytes transferred to the diagnostics window during download and upload of files. - Invocation of the Rexx command DoubleClick if the left mouse button is double clicked in the Editor Window. The above features are explained in detail in the following: ARexx/Amiga Script Interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Rexx is a scripting language, originally written by IBM (!). Its main purpose is to act as a macro language for other applications. The Amiga implementation is called ARexx, and is written by Bill Hawes (author of Conman etc). It is NOT public domain, and in the UK it retails at 30 - 40 pounds. ARexx, together with an amended version of the Amiga Compunet software, offers the ability to automate the operation of Compunet. It also offers a reasonably natural command language for Compunet, should you prefer that to using the mouse. It is possible to express command sequences such as: - logon to Compunet and download all mail, then logoff again - logon to Compunet and goto NEWS - wait until 18:00, logon, upload a set of files, and logoff again - etc, etc. All the above could be done entirely automatically. ARexx is usually used via command files (although it can be typed in directly). Conventially the files have a suffix that identifies the application they are intended for: the Compunet ARexx interface expects files intended for use with the editor to have a suffix of .cedit, and those for use with the terminal software to have a suffix of .cnet. The files are usually created using any standard editor (Ed will do !). The Editor and the terminal section of Compunet can have commands addressed to them seperately: an extra menu strip has been added to the menus concerned to enable this. Both new menu strips are headed ARexx, and contain: Send execute an ARexx command file Install install a new ARexx command in the menu strip F1 up to 10 commands of your choice .. .. "" "" F10 Save save the current menu strip The menu strips are automatically set to the last saved values when the terminal software is started up. Any ARexx process can direct its output to the Compunet ARexx interface by issuing the appropriate 'address' command: 'address CEDIT' for the editor, 'address CNET' for the terminal software. The ARexx interface can be used by other programs, providing that they adhere to the methods used by ARexx. This program supports non-ARexx programs interfacing with it as follows: If the ARexx library cannot be opened, then this version of the Compunet software will start off a background CLI process, which will execute a script of the name specified ( no .cnet or .cedit suffix will be added). The script may use any of the standard AmigaDOS commands (see S:Startup-Sequence for an example of a script). The script may communicate with the Compunet software using the 'Converse' command supplied as part of this package. The 'Converse' command has the following form: Converse application [command] To communicate with the Compunet software, the application must be either CNET or CEDIT (note upper case). The command may be any of the commands listed below, and must be enclosed in quotes if it contains embedded blanks. Any information returned as a result of issuing the command is written to stdout ( ie normally the console), and may be redirected if required, using standard AmigaDOS redirection. The 'Converse' command sets a return code which is the same as that passed to it by the application it is communicating with. If [command] is not specified, then 'Converse' reads commands from standard input (normally the console, but can again be redirected), until end of file is reached ( Ctrl-\ for the console). 'Converse' is "pure", and can therefore be made resident if you have AmigDOS 1.3 (or some other software supporting resident commands). For those writing in C, an object module ( converse.o ) is supplied. This has the prototype: /* Prototypes for functions defined in converse.c */ int Converse(char *PortName, char *Command, char *Result, int *ResultSize); where 'PortName' points to a string containing the name of the application (either "CNET" or "CEDIT" for the Compunet software), 'Command' is a pointer to a string containing the command, 'Result' is a pointer to a buffer large enough to receive the result, and ResultSize contains the length of the buffer - 1. If no result is wanted, then NULL can be passed instead of the address of a buffer. The function returns the return code from executing the command (NB a return of 20 can indicate that the command could not be sent). Whilst it is possible to write complex routines to control the Compunet software using scripts and 'Converse', use of ARexx is recommended for such purposes, as it is far easier to use ( NB I have no connection with Bill Hawes - I am just supporting what I think is a very good product). Command Descriptions ~~~~~~~~~~~~~~~~~~~~ In the following command descriptions, a working knowledge of Compunet and of ARexx is assumed. Commands appear in uppercase, parameters (for which you should substitute the value required) in lower case. Square brackets [] surrounding an item indicate that it is optional (the square brackets should NOT be entered). The | sign is used to indicated alternatives. Generally the commands can only be issued to one environment ( CNET or CEDIT ). However there are some commands ( eg STATUS and EDITOR) which can be issued to either environment. The valid environments are noted against each command. It should be noted that not all STATUS information can be requested from each environment - eg the status of the session is only known by the terminal software. The commands supported by the interface are: IDENTIFY [id] [password] {CNET} This sets up logon information. If the password is not specified, then the standard Compunet id/password requestor is displayed. CONNECT [id] [password] {CNET} This logs onto Compunet. If the password is not specified (either as a parameter, or in a previous IDENTIFY, then the usual id/password requestor is displayed once contact with Compunet is established. LEAVE {CNET} This leaves Compunet. QUIT {CNET} This quits the Compunet software. The standard Quit requestor is NOT displayed. MAIL {CNET} Enters Courier. MAILMORE {CNET} Obtains next directory of mail. MAILDONE {CNET} Terminates Courier. EDITOR {CNET or CEDIT} Invokes the Compunet Editor. This may be specified as a command to the terminal software ( CNET ), or to the Editor itself ( CEDIT ) ! The latter is especially useful if you have started a long process with the terminal software ( eg a download ), and suddenly realise you want to use the Editor, and you haven't already started it off. Entering '"address CEDIT editor' if you use ARexx or 'Converse CEDIT editor' from a CLI/Shell environment will recover the situation. GOTO page {CNET} Does a goto ! DIR {CNET} Fetches a directory. BACK {CNET} Goes to the next higher directory. DIRLINE {CNET} Selects a particular line of a directory. LAST {CNET or CEDIT} Goes to previous frame on shelf. NEXT {CNET or CEDIT} Goes to next frame on shelf. FRAME no | FIRST | LAST | key {CNET or CEDIT} Goes to particular frame on shelf. If the key option is used the FIRST frame on the shelf with that key is 'gone to'. UCAT {CNET} Does a UCAT (I must admit I haven`t been able to test this). VOTE n {CNET} Votes for the currently selected item. LIFE n {CNET} Extends the life of the currently selected item. ACCOUNT {CNET} Returns a string as produced by ACCNT. DOWNLOAD [name] {CNET} Downloads the currently selected item. The name must be specified if it is a P, F or S type item. MORE {CNET} Downloads another text frame. ALL {CNET} Downloads all remaining text frames. UPLOAD name type price life {CNET} Uploads an item. SEND {CNET} Sends a text frame. DONE {CNET} Concludes a text frame upload. STATUS n {CNET or CEDIT} Obtains information from the Compunet software, depending on the value of n: 1 returns status of session. Possible results for the terminal software are: "LOGGED_OFF", "LOGGING_ON", "LOGGED_ON", "FRAME_DNLD", "FRAME_UPLD", "MAIL", "MAIL_DNLD", "MAIL_UPLD", "FRAME_UPLD_DONE" Possible results for the editor are: "NOWINDOW" "NOFRAME" "NOTEDITING" "EDITING" 2 returns current line from the directory 3 returns complete current directory 4 returns number of current directory line 5 returns total number of lines in the current directory 6 returns the current frame, with case converted 7 returns the current frame, converted to printable format 8 returns the address of the current frame. NB This is intended for subsequent use with the FRAME command. It would be most inadvisable to use this to directly modify the frame. 9 returns the key of the current frame 10 returns the title of the current frame 11 returns the name of the current shelf 12 returns the name of the current save shelf 13 returns the cursor line in the editor window 14 returns the cursor column in the editor window 15 returns the foreground colour ('ink') 15 returns the background colour ('paper') OKREQ text {CNET or CEDIT} Displays an OK requestor, with the text specified. OKREQ2 text {CNET or CEDIT} Displays an OK requestor, with the text specified. Returns 'OK' or 'QUIT', according to which gadget was selected. VALREQ text {CNET or CEDIT} Obtains information from the user via a requestor containing the text specified as a prompt. ERROR text {CNET or CEDIT} Displays an error requestor, with the text specified. CURSOR line column {CEDIT} Positions the cursor when editing. EDIT {CEDIT} Starts editing a frame. ACCEPT {CEDIT} Accepts changes to a frame. CANCEL {CEDIT} Cancels changes to a frame. NEW {CEDIT} Creates a new frame. COPY {CEDIT} Copies a frame. ERASE {CEDIT} Deletes a frame. PRINT {CEDIT} Prints a frame in text mode. PRINTG {CEDIT} Prints a frame in graphics mode. GET name {CEDIT} Gets a file of textframe(s). PUTONE name {CEDIT} Puts a textframe to a file. PUTALL name {CEDIT} Puts all textframes to a file. TEXT text {CEDIT} Writes text into a frame being edited. SETUP [phone [id [modem]] | SAVE ] {CNET} If no parameters are specified, this brings up the setup requestor, and accepts input. If SAVE is specified, then the current configuration is saved to disk. For any other parameters, the configuration is updated (but NOT saved to disk). Care should be taken to surround any parameter containing embedded blanks with quotes. SHELF [name] {CEDIT} If no parameter is specified, this brings up a requestor which asks for the name of the Shelf to be made current. If a parameter is specified, then the Shelf of that name is made current. In either case, if there is no Shelf of that name, then it is created. SETSAVE [name] {CEDIT} If no parameter is specified, this brings up a requestor which asks for the name of the Shelf to be made the current save shelf. If a parameter is specified, then the Shelf of that name is made the current save Shelf . In either case, if there is no Shelf of that name, then it is created. SAVE {CEDIT} The current frame is copied to the current save shelf. RESTORE {CEDIT} The current frame is copied to the working shelf. Examples ~~~~~~~~ The following are example ARexx files: /* logon to Compunet and download all mail, then logoff again */ connect mail options results do until rc ~= 0 status 5 /* number of lines in the directory */ numberofitems = result do i = 1 to numberofitems download end mailmore end leave putall RecentMail /* let's save the mail as well ! */ /* **************** end of file *********************** */ /* logon to Compunet and goto NEWS */ connect goto NEWS /* **************** end of file *********************** */ /* wait until 18:00, logon, upload a set of files, and logoff again */ address command wait 18:00 /* use the Amiga wait command */ options results connect goto MYDIR do forever upload "An Upload" t 0 10 if rc = 0 then break dir if rc ~= 0 then do signal error exit end end options failat 10 /* give up if there is an error */ status 5 /* number of lines in directory */ dirline result upload "another file" s 0 10 upload "yet another" p 0 10 exit .error error "Sorry, couldn't upload" exit ;*********************************************** ;* Example script file ;*********************************************** Converse CNET connect Converse CNET goto NEWS Converse >RAM:NewsDir CNET "status 3" ;write directory to a file EndCLI ;Close the extra CLI /* Example C fragments using Converse */ if( retcode = Converse( "CNET", "Connect", NULL, NULL ) ) { printf( "Couldn't logon to Compunet\n" ); Converse( "CNET", "Quit", NULL, NULL ); exit( retcode ); } if( retcode = Converse( "CNET", "Mail", NULL, NULL ) ) { printf( "Couldn't access Mail\n" ); } if( retcode = Converse( "CNET", "Status 1", buffer, &buffsize ) ) { panic(); } else printf( "Status of Cnet is %s\n", buffer ); if( retcode = Converse( "CNET", "Status 6", buffer, &buffsize ) ) { printf( "Couldn't get frame\n"); } else printf( "Frame obtained, length %ld\n", buffsize ); ARP File Requestors ~~~~~~~~~~~~~~~~~~~ If you have the ARP library ( Public Domain ), then this revision of the Compunet software uses ARP file requestors instead of the built in ones. The ARP file requestors will fetch and display directories, and allow file selection by mouse. If the ARP library is not found, then the standard Compunet file requestors are used. Preservation of Directory Entries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Editor preserves the directory entry for each text frame downloaded, and displays it in the titlebar of the frame windows. This also permits use of the frame keys for named GoFrames (see Extended Menus below). Extended Menus ~~~~~~~~~~~~~~ Two extra menu items are added to the Editor Frame menu strip. 'GoFrame' has sub items of 'First', 'Last' and 'Named'.'First' and 'Last' allow immediate movement to the first and last frames on the shelf. 'Named' displays a requestor asking for a frame key, and moves directly to the first frame on the shelf having that key. 'Save' copies the current Editor frame to the current save Shelf. 'Restore' copies the current Editor frame to the working Shelf. An extra menu strip of 'Frame' is added to the terminal software menu. This menu strip has a single menu item of 'GoFrame', which has similar sub items to the ones described above for the Editor. An extra menu strip of 'Shelf' is added to the Editor Menu. This menu strip has menu items of 'Working', 'Save', 'Named' and 'SetSave': 'Working' selects the working shelf (ie the one that the terminal software uses). 'Save' selects the shelf named 'SAVE'. This is the default shelf for 'save' to copy frames to. 'Named' allows a named shelf to be selected. If the shelf does not already exist it is created. 'SetSave' selects the current save Shelf. If the shelf does not already exist it is created. An extra menu strip is also added for interface to ARexx and Scripts. This is detailed in the section on ARexx. Shelf Directory ~~~~~~~~~~~~~~~ This feature is controlled by a new option in the Setup Window. To enable it, select Setup from the Compunet menu strip, and click on the On button next to the legend Shelf Directory, then click on Use or Save. This option will take effect next time the Editor is started. If the Save option is selected, then the option will be also be selected in future sessions. An new window is opened by the Editor, containing a directory of the Shelf currently being used by the Editor. This directory is displayed in the same format as the existing directory window. It displays the key, title, and number of frames having that key. The window contains the following Buttons (mostly duplicating menu items in the 'Frame' menu strip): 'Copy' copies the current frame to the end of the shelf 'Erase' erases the current frame 'Goto' moves directly to the frame highlighted in the directory (This can also be done by double clicking on a directory line ). 'Print' produces a text print of the current frame. 'Save' saves the current frame to the Save Shelf. Audible Warnings ~~~~~~~~~~~~~~~~ The phrase 'Upload Complete' or 'Download Complete' is spoken, as appropriate at the end of uploads, and downloads other than text frames. Cursor Positioning ~~~~~~~~~~~~~~~~~~ When editing, the cursor can be positioned by moving the mouse pointer to the required place and clicking the lefthand button. Filenotes ~~~~~~~~~ This feature is controlled by a new option in the Setup Window. To enable it, select Setup from the Compunet menu strip, and click on the On button next to the legend File notes, then click on Use or Save. This option will take effect immediately. If the Save option is selected, then the option will be also be selected in future sessions. A file note, giving the key, title and author is added to downloaded files. File notes can be displayed using the AmigsDos List command. Extra Shelves ~~~~~~~~~~~~~ As many shelves as required can be set up. Two shelves are set up automatically: 'WORKING' - the default shelf used by the Editor and the terminal software. 'SAVE' - the default shelf used for the 'Save' function. More shelves can be setup using the 'Shelf' menu strip ( see extended menu functions above). Each shelf can be processed independantly - for example a 'FILE' shelf can be created and a file 'got' into it without disturbing the 'WORKING' Shelf. NB Frames are NOT automatically erased from shelves other than the 'WORKING' shelf. Bytes Transferred ~~~~~~~~~~~~~~~~~ During uploads and downloads the number of bytes transferred so far is displayed in the bottom line of the diagnostics window. Note that this line is also used for error messages. Editor DoubleClick ~~~~~~~~~~~~~~~~~~ The ARexx macro (or CLI file, if ARexx is not installed) DoubleClick is invoked if the left mouse button is double clicked whilst the pointer is in the Editor Window. This may be used, for example, to do an automatic Goto to the page whose key is under the pointer. Bugs Fixed (V2.14) ~~~~~~~~~~ 1. In the previous revision, if the Tty link were used, then the user logged off, then back on again without quitting the software, then on a further logoff the menu disappeared. This now works properly. 2. Status 2 provided the first line of the directory, no matter which line was current. It now provides the highlighted line. 3. The editor software used to cause a double release of memory, resulting in a non recoverable Guru, if an ARexx macro issued a command which did not return a result ( eg OKREQ ), whilst OPTIONS RESULTS was in effect, AND the previous command had returned a result. This now works properly. Bugs Fixed (V2.15) ~~~~~~~~~~ 1. The Frame menu strip was disabled when in Mail. It is now enabled. 2. In the previous revision, the Editor would often hang or cause a Guru if used without a Shelf Directory Window. This has now been fixed. 3. GOTO, DIR, BACK, etc now allowed via the AREXX interface whilst part way through downloading a series of Text frames.