============================================================================ $VER: CNet Amiga ARexx Commands, v2.1 (10-Dec-94) by Dotoran ============================================================================ Notes: This is a NEW VERSION of this file. There have been many changes : made to the content of this file, including many new note segments : which should prove invaluable for ALL CNet ARexx Programmers! : : In a few places throughout this document, you will see references to : the files "GU30_Longs" and "GU30_Shorts". These files are located in : a separate release by me concerning the GETUSERS and CNet. Use the : FIND command, either on Future World or my BBS, Frontiers, to search : for the name "GU30" (minus quotes). This will allow you to locate the : archive that contains these files(and others) which you may also find : to be a valuable asset when programming for CNet Amiga BBS! : : At the END of this document are 5 "Info Packets", which will give you : some tips and pointers on using some of the commands talked about in : this document. It is my hope that you will get some ideas on using : the commands discussed herein. Files written in ARexx for the Amiga CNet Software package have numerous additional commands at their disposal that allow communication with CNet's environments much easier. This file is intended as a guide to ALL EXISTING AREXX COMMANDS, as of CNet, v3.05c. Any ARexx pfile or modification file written for CNet must start with a "Comment Tag". This can be any text of the authors choosing, so long as it is enclosed with the /* and */ Comment Tags. The text doesn't have to appear on one line, but may extend numerous lines into the file. Just remember to END the comment with the */ tag. After this comment, the command "options results" should be used if your file plans on extracting information from either the user or CNet. In other words, if your file will be handling any kind of data stored in variables, this command is needed to initialize the "RESULT" variable. CNet was written to accept and understand all commands included within the main "REXXMAST" module, as well as any additional libraries, like the "rexxsupport.library" that came with your REXXMAST. In addition to these commands, you may also use any of the following CNET ONLY commands. By CNET ONLY, I mean any file written using any of these commands may NOT work under any other ARexx Environments(bbs programs, terms, paint programs, etc.) In the descriptions that follow, the commands should use the format given in the first line of the description, unless otherwise noted. Also, RESULT= refers to what contents will be placed in the "RESULT" variable after using this command. Those commands noted by the phrase "[ An ABBEREXX Standard ]" are ARexx commands which follow the ABBEREXX ARexx Standard. Many BBS Packages made for the Amiga support this standard. If you're writing a file for multiple BBS Programs, try to use these commands if at all possible to insure they run properly on whichever BBS Program that may wish to run them. The ABBEREXX standard also supports 3 variables: TIMEONLINE, CARRIER, and TIMELEFT. At this time, Ken Pletzer has not been able to locate the correct procedure for adding external variables to an AREXX command file. The following is a list of ALL 61 CNet ARexx Commands available for your use, as of CNet Amiga, v3.05c. To skip directly to the start of discussion for a specfic command, search out one of the following keywords, making sure to also specify the "* " (minus quotes) at the START of a word: * ADDKEYS * ADDPOINTS * ADDTIME * BAUD * BBSCOMMAND * BBSIDENTIFY * BUFFERFLUSH * CALLEDITOR * CHANGEWHAT * CHANGEWHERE * CHECKABORT * CHECKIO * CLEAREDITOR * CLOSEDISPLAY * CLS * DROPCARRIER * FEEDBACK * FINDACCOUNT * GETCARRIER * GETCHAR * GETPORTID * GETSCRATCH * GETUSER * GETWHERE * HANGUP * IREADY * LOADEDITOR * LOADSCRATCH * LOGENTRY * MAYGETCHAR * MODEM * NEWLINE * OPENDISPLAY * PRINT * PROMPT * PUTSCRATCH * PUTUSER * QUERY * RECEIVE * RESETMODEM * SAVEEDITOR * SAVESCRATCH * SCREENOUT * SELECTFILE * SEND * SENDFILE * SENDMODEM * SENDSTRING * SETMAILSUBJ * SETMINFREE * SETNODELOCATION * SETOBJECT * SETPROTOCOL * SHUTDOWN * SPAWN * SYSOPLOG * TRANSMIT * VERSION * WRITEMAIL * XDN * XUP Search out JUST the text "* " (again, minus quotes) to hop from one command to the next, in case you're not quite sure which command you want to use. This will allow you to scan the "Info" section of each command, so that you can hopefully fine the command you are looking for. - Dotoran ---------------------------------------------------------------------------- * ADDKEYS ("data") ~~~~~~~~~~~~~~~~ Info: This command has the same affect as if the user typed the data : themselves. This command may be used to supply a DEFAULT value : for a command like QUERY, RECEIVE, etc. You can use the special : symbol ` (back apostrophe) to represent a cursor return. RESULT variable is NOT used for this command. Usage: ADDKEYS ("Hi, I'm just visiting this bbs...") : : Perhaps a possible DEFAULT WHO BANNER... * ADDPOINTS points ~~~~~~~~~~~~~~~~ Info: This command is used to alter the current users Game Points, : which might also be referred to as PFile Points. I've found the : need to enclose the given number with ( ) if the value is : negative. RESULT variable is NOT used for this command. Usage: ADDPOINTS 2000 : : Adds 2000 points to current users Game Point Balance. : : ADDPOINTS (-5000) : : Deducts 5000 points from users Game Point Balance. : Note value is NEGATIVE, so is enclosed in parenthesis. * ADDTIME minutes ~~~~~~~~~~~~~~~ Info: This command is used to alter the number of minutes the current : user has left online. This affects both the number of minutes : THIS call, as well as the number of minutes TODAY. Again, use : ( ) if the number will be negative. RESULT variable is NOT used for this command. Usage: ADDTIME 20 : : Adds 20 minutes to current users Time Remaining. : : ADDTIME (-10) : : Deducts 10 minutes from current users Time Remaining. : Note value is NEGATIVE, so is enclosed in parenthesis. * BAUD baudrate ~~~~~~~~~~~~~ Info: This will set the current Baud Rate to baudrate. RESULT variable is NOT used for this command. Usage: BAUD 9600 : : Set current user's Baud Rate to 9600 Baud. * BBSCOMMAND data ~~~~~~~~~~~~~~~ Info: Allows an external CNet command to be used. This command should : be one of the "Available Everywhere" commands found in Menu # 2 : of the "bbsmenu" file, although if the user has System Operator : access, commands from Menu # 1 may also be used. data may also be : a valid variable name, whereas the contents of supplied variable : will be passed to BBSCOMMAND. A cursor return will be appended to : data. RESULT variable is NOT used for this command. Usage: BBSCOMMAND wh : : Allows use of the WHO command : : BBSCOMMAND ea2! : : If "System Operator", enter VDE using Account ID # 2's info. * BBSIDENTIFY argument [ An ABBEREXX Standard ] ~~~~~~~~~~~~~~~~~~~~ Info: Depending on which argument is specified, the RESULT variable : will house different data, as shown below: Argument: : ABBEREXX RESULT = 1.0 : BBS RESULT = Current CNet Version String : EMULATION RESULT = ASCII or ANSI : NAME RESULT = BBS Name defined in "bbsconfig3" : SYSOP RESULT = SysOp Name found in "bbsconfig3" : TERM RESULT = baud columns rows port : USER RESULT = "handle" "city, st" access : : access = GUEST - New Users : MEMBER - Other Users : SYSOP - Account ID # 1 : CO-SYSOP - System Operators Usage: BBSIDENTIFY bbs : : RESULT = CNet $VER: CNet PRO 3.05c : : BBSIDENTIFY user : : RESULT = "Dotoran" "Buffalo, NY" SYSOP : : BBSIDENTIFY term : : RESULT = 57600 80 25 0 Notes: TERM gives 4 numbers parsed by spaces. : USER gives 3 items, first two delimited using double quotes. Notes: It was discovered that you should NOT use a VARIABLE name the : same as one of the above arguments BEFORE using this command, : else the command will return "RESULT" in the RESULT variable. : The following usage will NOT give the correct results: : : GETUSER 1 ; SYSOP=RESULT : BBSIDENTIFY SYSOP ; SYSOP=RESULT : TRANSMIT SYSOP * BUFFERFLUSH ~~~~~~~~~~~ Info: This command allows you to clear the contents of the serial and : keyboard buffers. This will effectively cancel any commands that : may have been entered ahead of the command queue. RESULT variable is NOT used for this command. Usage: BUFFERFLUSH : : Cancel any previously entered commands. Notes: It's a good idea to use this command right before exiting your : ARexx script, and especially as part of any error-checking sub- : routines you may be using. * CALLEDITOR lines ~~~~~~~~~~~~~~~~ Info: Opens the users default editor. If used after a LOADEDITOR : command, the editor will contain the contents previously loaded, : otherwise the editor will be entered empty. If lines is specified, : the editor will be set to a maximum of stated lines, not EXCEEDING : the users predefined max editor lines. If lines=0, the editor will : use the users default editor lines setting. RESULT = 1 - if editor contains data. RESULT = 0 - if editor contains NO data. Usage: CALLEDITOR 20 : : Enter the user's default editor with no more than 20 lines. : : CALLEDITOR 0 : : Enter user's default editor using user's default editor lines. Notes: If LOADEDITOR is used to pre-load the editor, make sure the VALUE : you use in the CALLEDITOR command is EQUAL or GREATER THAN the : number of lines in the file that was pre-loaded, else any extra : lines in the pre-loaded file will be chopped off. Notes: If the editor is ABORTED, the RESULT variable SHOULD be set to 0, : however due to a bug in the system, it will return a 1 instead. : Use GETUSER 1109865 to check for aborting. It will return a 1 and : 0 as specified above, but will return a -1 if the editor was : aborted instead. Notes: If RESULT returns a 0 value, you should then go one step farther : and check for the existence of the file(using EXISTS() command), : because it's possible the editor was entered having data, then : the user cleared the editor and SAVED an empty editor. In this : event, you should then either automatically delete the file, or : ask the user if they want the file deleted. * CHANGEWHAT ~~~~~~~~~~ Info: Supposedly, this command is synonomous to the CHANGEWHERE command, : however repeated tests of this command have proven that NOTHING is : displayed in the Control Panel, Status Window or WHO Display when : using this command. I believe this command was added to make CNet : compatible with older SkyLine/TransAmiga files that may have used : this command. Notes: Being as this command does NOTHING, it would probably be a good : idea to DELETE this command from any files you may see it in. : Again, you may see this in older SkyLine/TransAmiga files. * CHANGEWHERE "text" ~~~~~~~~~~~~~~~~~~ Info: This command is used to inform others of what the current user is : doing on the bbs. The text string(enclosed in double quotes) is : sent to the CONTROL Window, users Status Window & WHO Displays. : The maximum viewable length(for use in Control Window) is no : more than 15 characters. RESULT = The OLD value of this field. Usage: CHANGEWHERE "Global War" : : Sets the "Where" column under WHO to: Global War : : CHANGEWHERE "Dating" : : Sets the "Action" column in Control Window to: Dating Notes: As the RESULT variable IS being used, it's a good idea to notate : the previous contents of the WHERE column, and then reset it when : your file exits, like this: : : CHANGEWHERE "My File" ; oldwh=result : [ Your Code Here ] : CHANGEWHERE oldwh ; exit * CHECKABORT [ An ABBEREXX Standard ] ~~~~~~~~~~ Info: This command returns a value based on whether or not the user : used the SPACEBAR, / Key or CONTROL-C key to abort a message. RESULT = 0 - If user viewed entire message. RESULT = 1 - If user aborted message via SPACE,/,CONTROL-C. Usage: CHECKABORT : : RESULT is cleared each time new output is sent. * CHECKIO ~~~~~~~ Info: This command returns a value based on whether or not there is : data waiting to be input, using either QUERY, GETCHAR, RECEIVE. RESULT = 0 - If NO data is waiting to be input. RESULT = 1 - If there IS data waiting to be input. Usage: CHECKIO : : Must be continually reissued, so as not to miss any incoming : data through the datastream. * CLEAREDITOR ~~~~~~~~~~~ Info: This command ERASES the contents of the "Editor Temp Buffer". You : should use this command before you LOADEDITOR, or CALLEDITOR, if : you will not be using the LOADEDITOR command first. RESULT variable is NOT used for this command. Usage: CLEAREDITOR : : Deletes the "_edbuff" file. Notes: It is a good idea to use this command AFTER using the SAVEEDITOR : command to insure the "_edbuff" file is deleted, so as not to : interfere with other programs using CNet Editors. You should also : issue this command after CALLEDITOR uses, in the event the user : was to ABORT the editor. * CLOSEDISPLAY ~~~~~~~~~~~~ Info: This command is used to CLOSE the current CNet window, the same : way the RAMIGA-I key combination does. RESULT variable is NOT used for this command. Usage: CLOSEDISPLAY : : Will also close a "CNet Workbench" type screen. Notes: This command was meant to be used tandomly with the OPENDISPLAY : command, but the OPENDISPLAY command presently does not work, you : may NOT wish to use this command. * CLS [ An ABBEREXX Standard ] ~~~ Info: This command will Clear the screen and place the cursor in the : upper left hand corner of the screen, the same way \f1 does. RESULT variable is NOT used for this command. Usage: CLS : : Use this command instead of: transmit "\f1" Notes: I've had some problems getting this command to work on some Amiga : 4000 systems. If you're running an A=4000 setup, you may wish to : check to make sure this command works ok, before releasing it to : the general public. You can choose to use \f1 or ~[2J instead, : where the \ is a CONTROL-Y and the ~ is an ESCape Code character. * DROPCARRIER ~~~~~~~~~~~ Info: This command will effectively drop the carrier of the currently : online user. Be careful in your placement of this command, as it : does not perform any other reset commands. Try to follow this : command with an EXIT command to insure a proper exit is made to : CNET, which will then follow through with other reset commands. RESULT variable is NOT used for this command. Usage: DROPCARRIER : : Will disconnect the current user from your bbs. Notes: You may wish to use ADDTIME (-9999) right BEFORE this command to : insure users with INFINITE time will also be disconnected, as : I've found it only worked half the time with my INFINITE Time : users. * FEEDBACK ~~~~~~~~ Info: This command will ask the user if they wish to leave feedback. It : has the same affect as if they used the "F" command from anywhere : in your system. RESULT variable is NOT used for this command. Usage: FEEDBACK : : User will be asked if they wish to leave feedback. * FINDACCOUNT argument ~~~~~~~~~~~~~~~~~~~~ Info: This command is used to find the Account Number of a user on your : bbs. The specified argument can be either an ID Number, Handle, : or Real Name. Additionally, if a partial Handle or Real Name is : used, you will be given the Handle Search procedure. If an ID : Number is used, you will be asked if the right Handle is being : used, unless ID Number is suffixed with an exclamation point (!). RESULT = 0 - If that ID #, Handle, or Real Name does not exist. RESULT = ID # - If the ID #, Handle, or Real Name exists on your bbs. Usage: FINDACCOUNT 1 : : Is Dotoran (David Weeks) correct [Yes]? : : FINDACCOUNT 1! : : RESULT = 1 - The ID Number of Account # 1. : : FINDACCOUNT Dotoran : : RESULT = 1 - The ID Number of Dotoran's Account. : : FINDACCOUNT David Weeks : : RESULT = 1 - The ID Number of David Weeks' Account. : : FINDACCOUNT Dot : : 1. Don : 2. Dogg : 3. Dotoran - Etc. Handle Search Routine. Notes: You will be given the "Invalid ID#" message if you use an ID : Number that is HIGHER than your Total Number of Users. This text : is PRINTED to the SCREEN, NOT saved to the RESULT variable. Notes: If you wish to make your code as "clean" looking as possible by : NOT having that "Is such-and-such correct" line printed, yet you : also would like to give the user the option of typing a textual : value instead, use the DATATYPE() command to use the ! point: : : QUERY "Enter ID#, Handle or Real Name: " ; NA=RESULT : IF DATATYPE(NA,"N")=1 THEN NA=NA"!" ; FINDACCOUNT NA : ID=RESULT ; TRANSMIT "This User's ID Number is: "ID Notes: There is presently NO way to suppress the Handle Search Routine, : so if a user specifies an unknown textual value, they WILL be : shown the Search list. Keep this in mind when creating programs, : as you may wish to include a "REDRAW" feature for this reason. * GETCARRIER ~~~~~~~~~~ Info: This command returns either TRUE or FALSE, based on whether there : is a carrier present on the current port. RESULT = TRUE - If carrier is present. RESULT = FALSE - If no carrier is present. Usage: GETCARRIER : : Returns either TRUE or FALSE. Notes: Local Ports, or Local Logons will pass TRUE for this command. : This is one way to check for Loss of Carrier in your files, : although not the BEST way. See "INFO PACKET 2" below. Notes: Here's a "down and dirty" loss-of-carrier check using GETCARRIER: : : CHECK:;GETCARRIER;IF RESULT="FALSE" THEN EXIT * GETCHAR [ An ABBEREXX Standard ] ~~~~~~~ Info: This command will wait for ONE character to come over the serial : port. This character will be placed in the RESULT variable. If : the character is a LETTER, it will be CAPITALIZED automatically. RESULT = Character entered. (UPPERCASE if a LETTER) Usage: GETCHAR : : Uppercase value of character entered. Notes: c2d(result)=13 to check for Cursor Returns, : c2d(result)=27 to check for ESC press, : c2d(result)=8 to check for BACKSPACE, : c2d(result)=127 to check for DELETE. Notes: Use the INDEX() and ~ operators to quickly check the validity of : user input, as shown in this example: : : MENUBAR: : SENDSTRING "Enter N, S, E, W, U, D, Q, or ESC: " : GETCHAR ; COM=RESULT : IF INDEX("NSEWUDQ",COM)=0 & C2D(COM)~=27 THEN DO : TRANSMIT "Bad Input" ; SIGNAL MENUBAR ; END * GETPORTID port ~~~~~~~~~~~~~~ Info: This command is used to get the ID Number of the user signed onto : the specified port. RESULT = ID Number - If a user is signed onto that port. RESULT = -1 - If either the port was empty or not loaded. Usage: GETPORTID 1 : : Return the ID Number of user signed on to Port # 1. Notes: Use the GETWHERE command to determine if a port is EMPTY, or NOT : LOADED. LOADSCRATCH RESULT, GETSCRATCH 1, SAVESCRATCH (-RESULT) : commands will get you the HANDLE of the user on this port. * GETSCRATCH number ~~~~~~~~~~~~~~~~~ Info: This command is used similarly to the GETUSER command, but the : data gotten by this command comes from the SCRATCH Buffer. You : must first use the LOADSCRATCH command to fill the SCRATCH Buffer : with needed information. The specified number value can be any of : the valid GETUSER values, including 5-digit LONG Offset values. RESULT = Data contained in given Scratch Location. Usage: GETSCRATCH 1 : : RESULT = Handle located in Scratch Buffer. Notes: Remember, you must first use LOADSCRATCH before you use this : command. The Scratch Buffer is loaded with the currently signed : on user's account info when they first logon. Notes: Not all of the SHORT GETUSER commands will work with GETSCRATCH. : You should refer to the file "GU30_Shorts" for more information : as to WHICH values WILL work. Use values between 1400740 and : 1201410 if you'd like to use one of the LONG, 7-Digit GETUSERS, : as these are the values that point to the SCRATCH Buffer. Refer : to the "GU30_Longs" file for more specific information. * GETUSER number ~~~~~~~~~~~~~~ Info: This command reads the specified data from the users account and : places the contents in the RESULT variable. The number parameter : can either be a decimal number between 1 and 99, or a 7-digit : OFFSET value taken right from one of CNet's "C" structures. RESULT = Data contained in given location of current user. Usage: GETUSER 9 : : RESULT = Voice Phone Number of current user online. Notes: Keep in mind that you may also use ANY of the LONG 7-digit OFFSET : values with this command as well. The CNet Amiga Manual is WRONG : in telling you these values cannot be used. This was true with : the pre-v2.63 versions, but NOT true with latter versions. They : just forgot to update their manual on this point! * GETWHERE port ~~~~~~~~~~~~~ Info: This command tells you what the user on the given port is doing. RESULT = What user on port is doing. (From WHERE column on WHO display!) RESULT = Idle (if port is loaded, but no user is online!) RESULT = (offline) (if port is NOT loaded) Usage: GETWHERE 1 : : RESULT = Same data as shown in WHERE column of WHO display : for user signed onto port # 1. Notes: Line 107 in BBSTEXT contains the value that will be used if the : port is loaded, but with no user online. Keep this in mind if you : happened to modify this line in BBSTEXT, as you will have to check : for this value, instead of "Idle" to see which ports are empty. : The "(offline)" text is hard-coded into the "bbs" file, so is NOT : easily modifiable. * HANGUP [ An ABBEREXX Standard ] ~~~~~~ Info: This command is used exactly like the DROPCARRIER command talked : about above. Please refer to that command for more information. * IREADY [ An ABBEREXX Standard ] ~~~~~~ Info: This command is used exactly like the CHECKIO command discussed : above. Please refer to that command for more information. * LOADEDITOR path/file ~~~~~~~~~~~~~~~~~~~~ Info: This command will load the file located at path into the Editor's : Temporary Buffer. This command should be used before CALLEDITOR : if you wish to edit an existing file. RESULT variable is NOT used for this command. Usage: LOADEDITOR systext:menu/main : : Load CNet's Main Menu into the Editor Temp Buffer. * LOADSCRATCH id ~~~~~~~~~~~~~~ Info: This command will load the user with Account # id's data into the : User Scratch Buffer. This data can then be manipulated using the : GETSCRATCH and/or PUTSCRATCH commands. RESULT = 1 - If all data was loaded successfully. RESULT = 0 - If account was deleted or account is invalid. Usage: LOADSCRATCH 15 : : Load Account # 15's data into the User Scratch Buffer. Notes: You MUST follow the LOADSCRATCH command with an accompanying : SAVESCRATCH command, even if all you'll be doing is READING the : accounts data. This is due to a "lock" that CNet places on that : user account whenever it's data is LOADSCRATCH'ed. This "lock" : stops the actual user from doing something that might modify : their data while it is being used by the ARexx program. The : SAVESCRATCH command MUST be followed by the NEGATIVE id value : if all you'll be doing is READING from the account. For instance, : to "unlock" the example above, use: SAVESCRATCH (-15) : : You can tell the difference between an empty(deleted) account and : an invalid account(ex: higher than your highest ID Number) by : getting the HANDLE of this account. If RESULT = 0 and the HANDLE : is equal to ! (exclamation mark), that account was DELETED, but : if RESULT = 0 and HANDLE is ANYTHING else, Account is Invalid. * LOGENTRY "text" ~~~~~~~~~~~~~~~ Info: This command is used to write text directly to the "calls" log. RESULT variable is NOT used for this command. Usage: LOGENTRY "Played Assassin Today" : : Writes: Played Assassin Today to the "calls" log. Notes: It is not necessary to include a cursor return or linefeed code : to the end of your text, as CNet will place one there for you. Notes: If you set the "ARexxSays" log as being ACTIVE, then ALL USES of : this command will be written to THAT log, instead of "calls". * MAYGETCHAR [ An ABBEREXX Standard ] ~~~~~~~~~~ Info: This command works similarly to the GETCHAR command, but with ONE : IMPORTANT difference. It doesn't WAIT for a character to be sent. RESULT = NOCHAR - If no character was entered. RESULT = character - If a character was entered. Usage: MAYGETCHAR : : Immediately fills RESULT with either "NOCHAR" or character. Notes: This command is especially useful for files where you wish things : to continually happen WHILE waiting for the user to hit a key. For : instance, a timer that continually runs down while waiting for the : input from the user. Notes: Another difference between MAYGETCHAR and GETCHAR is when using : letters. The MAYGETCHAR command will capture the EXACT LETTER : that was entered, meaning if an "a" was entered, then "a" is : placed in the RESULT variable. In other words, the letters are : NOT immediately changed to UPPERCASE, as is done with GETCHAR. * MODEM number ~~~~~~~~~~~~ Info: This command affects the condition of the serial device. RESULT variable is NOT used for this command. The number can be one of the following: 0 - Close the Serial Device. 1 - ReOpen Serial Device for Normal Operation. 2 - Don't Close Serial Device, but Disable Modem I/O. Usage: MODEM 2 : : Affects the modem similar to the ATH0 Hayes command. Notes: This command does NOT work on SOME modems, depending on which : Hayes commands your modem supports. You should play around with : this command first, to insure it DOES work on YOUR specific modem. * NEWLINE [ An ABBEREXX Standard ] ~~~~~~~ Info: This command will send a NewLine(or LineFeed) command over the : Serial Port. RESULT variable is NOT used for this command. Usage: NEWLINE : : Does the same thing as: TRANSMIT * OPENDISPLAY ~~~~~~~~~~~ Info: This command will attempt to OPEN the CNet Port Screen from which : this command was run from. This is similar to double-clicking the : port row in the Control Window. RESULT variable is NOT used for this command. Usage: OPENDISPLAY : : Attempt to OPEN CNet Console Window if given enough memory. Notes: We've discovered that this command does NOT WORK AS ADVERTISED! : Until Ken fixes the bugs in this command, it is suggested that : you stay away from this command, as well as the CLOSEDISPLAY : command(as you'll then have no way of re-opening the window). * PRINT "text" [ An ABBEREXX Standard ] ~~~~~~~~~~~~ Info: This command is used exactly like the TRANSMIT command discussed : below. Please refer to that command for more information. * PROMPT length argument '"text"' [ An ABBEREXX Standard ] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Info: This command allows data to be entered by the user which conforms : to set parameters: : : length - The maximum characters allowed for input. : : argument - Can be one of the following: : : NORMAL - Any characters can be input. : HIDE - Do not show actual characters(Passwords). : YESNO - Used for Yes/No input (YES as DEFAULT). : NOYES - Used for Yes/No input (NO as DEFAULT). : : text - This is the text that will be printed as the prompt. : It MUST be surrounded by double quotes, THEN it must : additionally be enclosed in single quotes. RESULT = Data entered by the user. Usage: PROMPT 15 normal '"What is your Handle? "' : : Asks user to enter Handle (up to 15 characters MAX). : : PROMPT 1 yesno '"Want to Play Again? (Y/n): "' : : Ask user to play again. Pressing RETURN answers YES. : : PROMPT 10 hide '"Enter Password: "' : : Enters up to a 10 character password (prints periods : instead of the actual entered data) Notes: Although you can specify a value as high as 255 for "length", it : is suggested that you not exceed a value of 78, because if the : value is TOO high, the user will have no way to EDIT the data if : it should wrap to the next line. Also keep this "length" value in : mind when coming up with your "text" string, as this will also : affect the maximum "length" you would want to use. Notes: It was discovered that you should NOT use a VARIABLE name the : same as one of the above arguments BEFORE using this command, : else the command will return "RESULT" in the RESULT variable. : The following usage will NOT give the correct results: : : YESNO=1 : PROMPT 1 YESNO '"Want to Quit now? [Yes]: "' : ANSWER=RESULT ; TRANSMIT ANSWER Notes: When using the YESNO and NOYES arguments, the answer used(Yes or : No) will be both printed to Screen, as well as being placed in : the RESULT variable. Notes: I was playing around with the need to use BOTH sets of quote : marks when using this command, and I have discovered that although : the docs state you need to use BOTH, I had no problems with just : using ONE or the OTHER, however you DO need to use at least ONE : set of them. The following three commands work IDENTICALLY: : : PROMPT 20 NORMAL '"Enter Your Handle? "' (Single/Double) : PROMPT 20 NORMAL 'Enter Your Handle? ' (Single Only) : PROMPT 20 NORMAL "Enter Your Handle? " (Double Only) : : These two, however, either resulted in unwanted text output, or : an error message being printed: : : PROMPT 20 NORMAL "'Enter Your Handle? '" (Double/Single) : PROMPT 20 NORMAL Enter Your Handle? (Neither) : : The only problem I've run across using ANY of the above formats : is when your text string contains an apostrophe. I've found the : need to DOUBLE the apostrophe, while using the SUGGESTED format : in order to get it to work correctly, as shown here: : : PROMPT 20 NORMAL '"What''s Your Handle? "' (Single/Double) : : Forgetting this 2nd apostrophe will result in your file exiting : for no apparent reason. No error messages will be sent to you. * PUTSCRATCH number ~~~~~~~~~~~~~~~~~ Info: This command will take the contents of the SETOBJECT Buffer and : place it in the User Scratch Buffer at the GETUSER location : stated by "number". The SAVESCRATCH command must then be used to : actually SAVE this new information into the user's account. This : number can be any valid DECIMAL GETUSER value (between 1 and 99), : or one of the 7-Digit OFFSET values in the range 1x00740 thru : 1x01410. See the "GU30_Longs" file for more specific information : on these LONG OFFSET values. RESULT variable is NOT used for this command. Usage: PUTSCRATCH 1 : : Takes whatever is in the SETOBJECT Buffer and places it in : the Scratch Buffer location designating the user's Handle. : : PUTSCRATCH 1201410 : : Takes the value in the SETOBJECT Buffer and places it in : the Scratch Buffer location for "# of Dictionary Entries". Notes: Remember, you must use SETOBJECT before this command, then use : SAVESCRATCH after this command. Also, it is assumed you used the : LOADSCRATCH command to initially load that users data INTO the : Scratch Buffer. Notes: When using the SAVESCRATCH command with the PUTSCRATCH command, : make sure the numeric value following the SAVESCRATCH command is : NOT a NEGATIVE value, else the change will NOT be saved. * PUTUSER number ~~~~~~~~~~~~~~ Info: This command is used similarly to the PUTSCRATCH command, except : this command places the SETOBJECT Buffer data directly into the : current memory of the user online. This information will not be : SAVED until that user logs OFF the system. This is an EXTREMELY : powerful command, and should NOT be used lightly, as using this : command indiscriminately may result in a system wide guru. RESULT variable is NOT used for this command. Usage: PUTUSER 38 : : Take the contents of the SETOBJECT Buffer and place them : in memory of the current user where their WHO BANNER is : currently stored. When this user signs off, this data will : BECOME that users WHO BANNER. Notes: You must use the SETOBJECT command BEFORE using PUTUSER. Notes: Even though this info is not SAVED until the user logs off, it : WILL be made "active" data immediately. For instance, if the user : signed on, then used the above PUTUSER 38 command, THEN used the : EP;14 command to edit their Who Banner, it will be this NEW Who : Banner they will see, instead of the old one they had before they : logged on. Notes: It is also safe to use the LONG 7-Digit GETUSER OffSet Values with : this command, however you need to be VERY SURE the value you use : points to a piece of USER DATA. Refer to "GU30_Longs" for more : specific information. * QUERY "text" ~~~~~~~~~~~~ Info: This command is similar to the PROMPT command, except this is a : much SIMPLER convention. The text, if given, will be used as the : prompt for the user. This command accepts any characters up to a : length of 256 characters. RESULT = Data entered by the user. Usage: QUERY "What do you wish to do now? " : : The users input is placed in the RESULT variable. : : QUERY : : The users input is placed in the RESULT variable. * RECEIVE ~~~~~~~ Info: This command is used IDENTICALLY to the QUERY example above that : uses NO Text. See QUERY for more information. Notes: Use this command in conjunction with SENDSTRING below for the : best results. * RESETMODEM ~~~~~~~~~~ Info: This command is used to reinitialize the modem on the port this : command was called from. The init strings and baud rate settings : of the current "bbsport" file are used in the reinitialization. RESULT variable is NOT used for this command. Usage: RESETMODEM : : ReInitializes the modem connected to this port. * SAVEEDITOR path/file ~~~~~~~~~~~~~~~~~~~~ Info: This command will take the current contents of the Editor Temp : Buffer and SAVE them to the file at given path. If the file : exists at said path, it will be overwritten. RESULT = 1 - The SAVE was successful. RESULT = 0 - Something went wrong with the SAVE. Could be anything from DISK FULL to UNKNOWN PATH to BAD FILENAME. Usage: SAVEEDITOR gfiles:last10 : : Saves the contents of the Editor Temp Buffer to the filename : "last10", located in the "gfiles:" path. Notes: If you were editing an existing file loaded via the LOADEDITOR : command, it would be a good idea to use the same "path/file" in : your LOADEDITOR command for the SAVEEDITOR command. * SAVESCRATCH id ~~~~~~~~~~~~~~ Info: This command will take the ENTIRE Contents(NOT just those items : that changed) of the Scratch Buffer and SAVE them to the supplied : Account id. Be CAREFUL with this command, as it's QUITE Powerful. RESULT = 1 - If the SAVE went ok. RESULT = 0 - If the SAVE failed. (Perhaps an invalid id number) Usage: SAVESCRATCH 10 : : Take User Scratch Buffer contents and SAVE them as ID # 10. : : SAVESCRATCH (-25) : : Unlock Account ID # 25, but do NOT save any information. Notes: Use a NEGATIVE id value to "unlock" an account that may have : been "locked" earlier, due to a LOADSCRATCH command, if you do : not wish to SAVE the contents of this account. Remember, negative : values need to be enclosed in ( ). : : It is NOT a good idea to use the SAVESCRATCH command to save the : contents of the currently signed on user. Use the PUTUSER command : if that is your intention. * SCREENOUT "text" ~~~~~~~~~~~~~~~~ Info: This command is similar to the TRANSMIT command, accept with this : command, the supplied text is ONLY sent to the SCREEN and NOT out : the modem port. RESULT variable is NOT used for this command. Usage: SCREENOUT "Does the SysOp wish to Chat?" : : Sends to the LOCAL SCREEN: Does the SysOp wish to Chat? Notes: See also the SENDMODEM command, which is this commands opposite. * SELECTFILE path/file ~~~~~~~~~~~~~~~~~~~~ Info: This command will take the file located at path and add it to the : user's Download Select Buffer. RESULT = 1 - If the select was a success. RESULT = 0 - Something went wrong. Probably a nonexistent file, or bad path designation. Usage: SELECTFILE gfiles:bbsnums/sysoplist : : Will take the "sysoplist" file located in "gfiles:bbsnums/" : and ADD it to the users Select List. Notes: This command makes use of the lines 486 thru 489 in BBSTEXT that : deal with informing the user the results of the Select action. Notes: This command also conforms to CNet's "Max Selected Files" as set : in your CNet "Limits..." section of CONFIG, meaning that this : value, minus the number of files already in the user's Select : List is the MAXIMUM number of files that can successfully be : added to their Select List. The user will be told they have "Too : Many Selections" otherwise. Notes: If you SELECTFILE a file that already exists in the user's Select : List, then that file will be REMOVED from their Select List. In : this manner, you can think of this command as a "toggle" command. * SEND "text" [ An ABBEREXX Standard ] ~~~~~~~~~~~ Info: This command will send the given text through the modem with NO : MCI translation. Any embedded MCI Codes will be printed to the : screen. ANSI Codes, however, WILL be interpreted. RESULT variable is NOT used for this command. Usage: SEND "\c7You have \cb12 \c7minutes left." : : Prints: \c7You have \cb12 \c7minutes left. Notes: The only real use I've found for this command is in debugging : runabout MCI codes. I have also used it in certain programs that : allow MCI colored text to be edited by the user. This allows you : to show the user what the MCI coding looks like. : : This command is an alternative to using the \@1 MCI command, which : effectively disables ALL MCI Codes until the file exits. Using the : SEND command allows you only to disable certain portions of coding. * SENDFILE path/file [ An ABBEREXX Standard ] ~~~~~~~~~~~~~~~~~~ Info: This command will send the file found at path through the modem : port(and on screen) interpreting all MCI and ANSI codes as it : goes along. RESULT variable is NOT used for this command. Usage: SENDFILE systext:sys.start : : Display the "sys.start" file, found in "systext:" to the : user showing all color/graphics embedded within it. * SENDMODEM "text" ~~~~~~~~~~~~~~~~ Info: This command is similar to the TRANSMIT command, except this will : only send the text through the modem, NOT on a LOCAL screen. RESULT variable is NOT used for this command. Usage: SENDMODEM "Do you wish to Chat with SysOp? " : : Sends to modem: Do you wish to Chat with SysOp? Notes: See also the SCREENOUT command, which is this commands opposite. * SENDSTRING "text" ~~~~~~~~~~~~~~~~~ Info: This command used IDENTICALLY to the TRANSMIT command discussed : below, except this command doesn't append a cursor return d2c(13) : to the end of the line. Sending a second SENDSTRING after a first : will append the second text string right after the last character : of the first. RESULT variable is NOT used for this command. Usage: SENDSTRING "Your Total Downloads: " : : Prints: Your Total Downloads: #<--Leaving the cursor : right here. * SETMAILSUBJ "text" ~~~~~~~~~~~~~~~~~~ Info: This command should be used BEFORE you use the WRITEMAIL command. : It allows you to create the Title of the Mail Item you will be : sending using the WRITEMAIL command. RESULT variable is NOT used for this command. Usage: SETMAILSUBJ "Hey, A Party!" : : Creates a Mail Title of: Hey, A Party! * SETMINFREE bytes ~~~~~~~~~~~~~~~~ Info: This command allows you to tell the UPLOAD process when it must : CANCEL an Upload, due to a "Not Enough Space" situtation. RESULT variable is NOT used for this command. Usage: SETMINFREE 10000 : : Tells the program to ABORT any UPLOAD if the free disk space : in the upload path goes BELOW 10,000 bytes (10K). Notes: Use this command in conjunction with the XUP command below. * SETNODELOCATION "text" [ An ABBEREXX Standard ] ~~~~~~~~~~~~~~~~~~~~~~ Info: This command is used IDENTICALLY to the CHANGEWHERE command that : was discussed above. See that command for more information. * SETOBJECT string ~~~~~~~~~~~~~~~~ Info: This command places the given string, which may also be any valid : variable name, into the SETOBJECT Buffer. This Buffer is used by : the PUTUSER and PUTSCRATCH commands, discussed above. RESULT variable is NOT used for this command. Usage: SETOBJECT "33 Harrington Place" : : Places the string: 33 Harrington Place into the : SETOBJECT Buffer for use with either the PUTUSER or : PUTSCRATCH command. : : SETOBJECT handle : : Places the contents of the "handle" variable into the : SETOBJECT Buffer for use with PUTUSER/PUTSCRATCH commands. * SETPROTOCOL "x" ~~~~~~~~~~~~~~~ Info: This command is used to specify which protocol will be used with : the XUP and/or XDN command to follow. The x should be the one : character code representing each Protocol, like Z=Zmodem, A=Ascii, : Y=Ymodem, etc. By using a NULL String (""), the user will be : ASKED which Protocol they wish to use. RESULT variable is NOT used for this command. Usage: SETPROTOCOL "Z" : : Sets the current protocol to Zmodem. : : SETPROTOCOL "" : : A) Ascii : X) Xmodem : Y) Ymodem, etc. Asks the User to Pick. * SHUTDOWN ~~~~~~~~ Info: This command is NOT used by CNet. I believe this command was : added to make CNet compatible with older SkyLine/TransAmiga files : that may have used this command. I have experimented with many : formats for this command, which all have the same affect: NOTHING. Notes: Being as this command does NOTHING, it would probably be a good : idea to DELETE this command from any files you may see it in. : Again, you may see this in older SkyLine/TransAmiga files. * SPAWN path/file ~~~~~~~~~~~~~~~ Info: This command is used to automatically launch another program from : WITHIN your ARexx program. This second program MUST be another : ARexx program or this command will ABORT. RESULT variable is NOT used for this command. Usage: SPAWN "pfiles:Emp/emp.help" : : Automatically runs the file "emp.help" located at the path : "pfiles:Emp/". Notes: Be careful with this command, as the first time it is used, you : will have TWO pfiles in memory. If the second pfile SPAWNS yet : another ARexx file, you'll have THREE pfiles in memory. This may : cause problems if your "Max pfiles running at once" setting on : CONFIG's "Limits..." screen is not set high enough. * SYSOPLOG "text" [ An ABBEREXX Standard ] ~~~~~~~~~~~~~~~ Info: This command is used IDENTICALLY to the LOGENTRY command that : was discussed above. See that command for more information. * TRANSMIT "text" ~~~~~~~~~~~~~~~ Info: This command will take the given text line and send it to both : the screen and the modem, appending a carriage return d2c(13) to : the end of each line. RESULT variable is NOT used for this command. Usage: TRANSMIT "Here's how you play this game..." : : Sends: Here's how you play this game... to both the : screen and the modem port. * VERSION ~~~~~~~ Info: This command sends the current CNet Amiga Version number to the : RESULT variable. RESULT = Current CNet Version String. Usage: VERSION : : RESULT = $VER: CNet PRO 3.05c Notes: The output of this command is similar to the BBSIDENTIFY BBS : command, accept the VERSION output lacks the initial "CNet" : before the "$VER:" section. * WRITEMAIL id ~~~~~~~~~~~~ Info: This command takes the contents of the Editor Temp Buffer and : will SAVE it as a piece of personal mail sent to Account id. You : should first use the SETMAILSUBJ command to create a Title for : your Mail. RESULT = 1 - If the Save went ok. RESULT = 0 - If the Save failed. (Perhaps a bad id number) Usage: WRITEMAIL 26 : : Send the Editor Temp Buffer as MAIL to Account # 26. Notes: Another reason a save might fail is if the id in question has its : mail-box CLOSED. Also, keep in mind that if a user has their mail : box sent to FORWARD mail, any mail sent using this command will : ALSO be forwarded to the forward account number. There is presently : no way of using this command to send a piece of URGENT mail. * XDN path/file ~~~~~~~~~~~~~ Info: Using the protocol specified by SETPROTOCOL, this command will : send the file located at path to the user immediately. RESULT variable is NOT used for this command. Usage: XDN gfiles:contest : : Will start a download using previously selected protocol : of the "contest" file, located in "gfiles:". * XUP path/file ~~~~~~~~~~~~~ Info: This command works similarly to the XDN command, but for UPLOADS. : If the selected protocol is a BATCH Proto, like Zmodem or Ymodem, : then only the path need be given, while the file should be given : if a single file proto(Xmodem,Ascii, etc) is to be used. RESULT variable is NOT used for this command. Usage: XUP uploads: : : Start an UPLOAD process to the "uploads:" assign. Since no : filename is given, a batch protocol is expected. : : XUP ram:numbers : : Start an UPLOAD process to be stored in "ram:" using the : filename "numbers". ---------------------------------------------------------------------------- INFO PACKET 1 ~~~~~~~~~~~~~ It is also possible to talk directly to one of CNet's Ports through ARexx. Each screen is designated "CNETREXX#", where # is the port number 0 thru 99. The command: ADDRESS CNETREXX0 can be used to talk to Port 0's CNet Screen(or Environment). There is, however, something you need to keep in mind. If Port "A" addresses Port "B", then Port "B"'s user will be locked out, until Port "A" has finished doing what it started out to do. What this means, simply, is that if Port 1 tells port 0 to view a certain text file, both port 1 and port 0 will be tied up, or unable to accept user input, until port 0 has completely viewed the text file, upon which both ports will be handed back to their respective users for control. Sometimes you may wish to use a VARIABLE containing a Port Number, instead of specifying it verbatim, as shown above. In this event, you should use the ADDRESS command in a slightly different manner: port = 2 ADDRESS VALUE "CNETREXX"port Note the addition of the sub-keyword VALUE, which tells the ADDRESS command to evaluate the following expression and use IT as the name to ADDRESS. We could even build the string into a single variable, like this: port=2 pname="CNETREXX"port ADDRESS VALUE pname When you're finished addressing the other port, use the ADDRESS command by itself to return control back to your port: ADDRESS If the ARexx file that initially addresses the other port was to EXIT, control would also be passed back to the originating port. If what you wish to do with the other port deals with MCI Codes, as in if you were to send a file to that port that had MCI's in it, or used the BBSCOMMAND command to issue a command to that port that had MCI's in it, you need to also RESET the MCI Environment for that port, BEFORE issuing any commands containing MCI codes, as shown in this last example: ADDRESS CNETREXX2 SETOBJECT "0" ; PUTUSER 1109830 /* This is the required code. */ SENDFILE "SYSTEXT:MENU/MAIN" ADDRESS If you neglect to include this line, any text containing MCI-Codes will be printed with NO MCI-Interpretion, meaning the user will SEE each and every MCI-Code printed to screen, instead of being correctly interpreted. Here's a "freebie" program using the above technique. This program could be used by SysOps of Multi-Line boards to create a SysOp-Only command that will display a text file saying "GoodNight" to each user on each port: /* Say Good Night! */ OPTIONS RESULTS DO I=1 to 10 ADDRESS VALUE "CNETREXX"I SETOBJECT "0";PUTUSER 1109830 SENDFILE "SYSTEXT:GOODNIGHT" ADDKEYS ("`") END I ADDRESS EXIT Note how I also used the ADDKEYS ("`") command to get back to the user's prompt, instead of the user being presented with that blank line that just sits there, until THEY choose to hit ENTER/RETURN. Cleans it up a bit. Keep in mind, though, that if a user is doing something like Up/Downloading, or playing MUD or some other activity which "locks" their port, that the above script will seem to "freeze up", because it will wait until the lock on the port has been removed, before continuing with it's display loop. A slight modification could be made to the above program, so as to make it accept an argument as to WHICH port you wished to say Good Night to: /* Say Good Night! */ OPTIONS RESULTS GETUSER 1302307;PORT=RESULT ADDRESS VALUE "CNETREXX"PORT SETOBJECT "0";PUTUSER 1109830 SENDFILE "SYSTEXT:GOODNIGHT" ADDKEYS ("`") ADDRESS EXIT INFO PACKET 2 ~~~~~~~~~~~~~ There are numerous ways you can check for a Loss of Carrier in one of your files, but one of the BEST ways is to keep an eye out for this text: ###PANIC This text will be placed in the RESULT variable the instant the Loss of Carrier is detected by the CNet Host environment, and will continue to be sent until a proper logoff has been initiated. This string can be captured using any of the following commands: QUERY, RECEIVE, GETCHAR, MAYGETCHAR, and the PROMPT command. One good way to check for ###PANIC is to create a small routine near the end of your ARexx program that you can CALL from time to time. It might look something like this: CHECKPANIC: if result~='###PANIC' then return logentry 'Loss of Carrier' bufferflush exit Now just "CALL CHECKPANIC" after a well used GETCHAR, QUERY, etc, and your files will be busting along with the other BIG ONES! You can also create a similar routine using the GETCARRIER command: CHECKPANIC: getcarrier ; if result="TRUE" then return logentry "Loss of Carrier" bufferflush exit The main difference between this routine and the first one is that you can "CALL CHECKPANIC" with this one from ANYWHERE in your program, and not just in places where you're accepting input from the user. By placing CALLs to this routine, every 20 or 30 lines of code, you'll make your file exits quickly and efficiently if loss of carrier should ever present itself to your file, which is BOUND to happen sometime! :-( INFO PACKET 3 ~~~~~~~~~~~~~ It can be a HUGE time saver if you abbreviate some of your most used ARexx commands to two letters or so. Here's how I start most of MY ARexx creations: Line 1: /* Here's my Program */ Line 2: options results;signal on SYNTAX;signal on ERROR;signal on IOERR Line 3: tr=transmit ; gc=getchar ; qu=query ; se=sendstring ; gu=getuser Line 3 contains my abbreviations. Now, whenever a TRANSMIT command is needed, all I have to type is TR instead. If you've seen the size of SOME of the files I've put out, you can begin to see how much time was saved by using these abbreviations. Another nice trick to using abbreviations is in finding MCI Code Errors. Remember the SEND command above? The one that SENDS the MCI codes AS THEY ARE? Well, simply changing the tr, qu, and se commands, like this: tr=send ; qu=send ; se=send And I can now view ALL the MCI codes as they are, WITHOUT them being interpreted, or I can REASSIGN the variables right at the start of the routine I think the problem is located in. INFO PACKET 4 ~~~~~~~~~~~~~ It is possible to use a Single Quote wherever a Double Quote is used. The only exception to this rule is the PROMPT command that needs BOTH. Since it takes longer to create a Double Quote, using the Single Quote is another Time Saver. Something to be careful of when using Single Quotes is trying to avoid the dreaded RUN-TIME-SCAN error. Before the first line of code is executed by your Amiga, a scan of the code is performed by RexxMast to insure the proper Syntax has been used. Sometimes, if a bad enough error is found, your file will simply EXIT, no questions asked, NO error messages printed. One of the LARGEST causes of this error is when missing the use of a Single Quote. If you use many contractions in your files, like this: tr 'There is no way you're going to beat me!' you're just ASKING for a RUN-TIME-SCAN error, because your single quotes don't match up. It takes a bit of practice, but after awhile, you learn where to look for the "silly" R-T-S errors. By the way, to get around the above problem, use this line of code: tr "There is no way you're going to beat me!" or, if you wish to NOT use the double quotes, try it this way: tr 'There is no way you''re going to beat me!' Note how I used TWO single quotes to produce ONE when it prints... INFO PACKET 5 ~~~~~~~~~~~~~ Lastly, never use a CALL statement, when a SIGNAL statement will do the same thing. Think of a SIGNAL statement as the equivalent to the GOTO command in BASIC, whereas the CALL statement equates to the GOSUB statement. In fact, the CALL statement is still terminated using the RETURN command. Multiple uses of the CALL statement to routines that do not terminate themselves using the RETURN command is one way to choke your ARexx file into doing(and showing) some very strange results. It could be anything from odd Error 0's you can't locate, to the file seeming to DRAG along, to the file all of a sudden simply STOP running(lock up), or worse yet, simply exit itself without telling you what happened. Dotoran ============================================================================