Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 324.lha / ArexxInterfaceLibrary_v1.0 / Functions.doc.pp / Functions.doc

Wrap

Text File | 1989-12-13 | 21.1 KB | 1,032 lines

ARexx Interface Library (Rxil) Function Documentation Release X1.0 Copyright © 1989 by Donald T. Meyer, Stormgate Software All Rights Reserved The following is an alphabetical listing of the function documentation which has been extracted from the .c source files. ---------------------------------------------------------------------- NAME RxilCancel SYNOPSIS RxilCancel(); FUNCTION Sets the abort condition for ARexx macros. This is accomplished by setting the Abort flag in the RxilDef structure. All ARexx messages received at the ARexx ports while this flag is set will be returned with an error code. Unless the RXIL_NO_CLEAR_ABORT flag is set, the Abort flag will be cleared automaticly when the last ARexx program launched by this application has finished. INPUTS None RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO ---------------------------------------------------------------------- NAME RxilCheckCancel SYNOPSIS flag = RxilCheckCancel(); BOOL flag; FUNCTION Checks to see if the button on the cancel macro requester has been clicked by the user or not. This will return FALSE if the cancel requester is not posted. INPUTS None RESULT A boolean TRUE if the cancel requester has been clicked. SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilPostCancel(), RxilEndCancel() ---------------------------------------------------------------------- NAME RxilCheckPort SYNOPSIS RxilCheckPort(); FUNCTION Called by the client program's eventloop upon recieving a message at one of the ports. This handles the dispatching ( via RxilDispatch() ) of ARexx commands, the launching of "looped back" macros, and receiving the replys to macro invocation messages which we have sent to Rexxmaster. This is a "safe" call in that if the ARexx library was unopened or the port opening failed, nothing will go boom! INPUTS None RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilInit(), RxilDispatch() ---------------------------------------------------------------------- NAME RxilCheckResult SYNOPSIS RxilCheckResult( rexxmsg ); struct RexxMsg *rexxmsg; FUNCTION Verify that the secondary result field in a RexxMsg is appropriatly set. This should be called for a RexxMsg just prior to replying it. This will deal with the case of a result string being set when the calling program did not request it. It will be freed, and an error code set to indicate to the calling program that it should be requesting a result for this command. INPUTS rexxmsg = pointer to the RexxMsg structure to be checked. RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO ---------------------------------------------------------------------- NAME RxilCleanup SYNOPSIS RxilCleanup( rdef ) struct RxilDef *rdef; FUNCTION Cleanup the entire ARexx port. This will set the Abort flag, then wait till all ARexx program invocations which we have made are completed. At this time, all ARexx message ports will be closed. Any remaining RxilInvocation structures which were allocated via RxilCreateRxi() and not yet deleted via RxilDeleteRxi() will be cleaned up and freed. The ARexx library will be closed. Finally, the RexxDef structure itself will be freed. INPUTS rdef = pointer to the RxilDef structure returned by a call to RxilInit(). RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilInit(), RxilPending() ---------------------------------------------------------------------- NAME RxilCleanupReturn SYNOPSIS RxilCleanupReturn( rxi ); struct RxilInvovcation *rxi; FUNCTION This will take a pointer to a RxilInvocation structure and free what needs to be freed. The RexxMsg pointer is then NULL'ed and the structure's state set to AVAILABLE. This should be called by the main program to cleanup after a function or command has returned and after the main program has done whatever it wanted to with the result. This will close the extension filehandles for Stdin and Stdout. INPUTS rxi = pointer to the RxilInvocation structure to be cleaned up. RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilCreateRxi(), RxilDeleteRxi(), RxilGetReturn() ---------------------------------------------------------------------- NAME RxilCloseConsole SYNOPSIS RxilCloseConsole( rexxmsg ) struct RexxMsg *rexxmsg; FUNCTION This will close the AmigaDOS file handles contained in the rm_Stdin and rm_Stdout fields of the RexxMsg. If the handles are the same, only one close is performed. This clears the fields. If the fields are NULL, then no action is taken. This function supports the rm_Stdin and rm_Stdout being seperate handles, even though it's complimentary function, RxilOpenConsole() does not do this. INPUTS rexxmsg = pointer to the RexxMsg whose IO streams are to be closed. RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilOpenConsole() ---------------------------------------------------------------------- NAME RxilCmdLock SYNOPSIS RxilCmdLock( rexxmsg ); struct RexxMsg *rexxmsg; FUNCTION This is a "command" which would be called from the dispatch function. This would handle the "LOCK" command that an ARexx program could send to the application requesting access to the private port. INPUTS rexxmsg A pointer to a RexxMsg structure. RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilCmdUnlock() ---------------------------------------------------------------------- NAME RxilCmdPending SYNOPSIS flag = RxilCmdPending(); FUNCTION If any ARexx commands have been launched via a call to RxilLaunch(), and have not yet terminated, this will return TRUE. INPUTS None RESULT A boolean flag which indicates if any launches are in progress. SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilLaunch(), RxilPending(), RxilFuncPending() ---------------------------------------------------------------------- NAME RxilCmdUnlock SYNOPSIS RxilCmdUnlock( rexxmsg ); struct RexxMsg *rexxmsg; FUNCTION This is a "command" which would be called from the dispatch function. This would handle the "UNLOCK" command that an ARexx program could send to the application requesting access to the private port. Note: The privilege level for this command should be "secret", since anyone who locked us will be able to meet that level, and those who have not locked us can't slip the lock out from under those who did (so to speak). INPUTS rexxmsg A pointer to a RexxMsg structure. RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilCmdLock() ---------------------------------------------------------------------- NAME RxilCreateRxi SYNOPSIS rxi = RxilCreateRxi( name, type ); struct RxilInvocation *rxi; char *name; ULONG type; FUNCTION Allocate a RxilInvocation structure and initialize it to the defaults which are contained in the global RxilDef structure. INPUTS name = character string containing the name of the ARexx program that will be launched with the structure. type = determines wether this will be used to launch commands or functions. Must be set to either RXCOMM or RXFUNC. RESULT A pointer to a newly allocated and initialized RxilInvocation structure, or NULL if one could not be allocated. SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilDeleteRxi() ---------------------------------------------------------------------- NAME RxilDeletePort SYNOPSIS RxilDeletePort( port ); struct MsgPort *port; FUNCTION This will safely delete a message port used to receive commands from ARexx. This is acomplished by setting a failure return code and replying the message if it is from ARexx. If the message is not from ARexx, it is merely replied. WARNING: If the port was/is used to receive replys, there must be no chance of a reply being pending when this function is called! INPUTS port = pointer to a MsgPort. Normally one that was opened for receiving ARexx commands. RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO ---------------------------------------------------------------------- NAME RxilDeleteRxi SYNOPSIS RxilDeleteRxi( rxi ); struct RxilInvocation *rxi; FUNCTION Remove the structure allocated by a call to RxilCreateRxi() from the linked list, and then frees it's memory. INPUTS rxi = a pointer to the RxilInvocation structure to delete. This must have been allocated by a call to RxilCreateRxi(). RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilCreateRxi() ---------------------------------------------------------------------- NAME RxilDispatch SYNOPSIS RxilDispatch( rexxmsg, cmd ); struct RexxMsg *rexxmsg; char *cmd; FUNCTION This is really an "internal" function which is used by the RxilCheckPort() function to dispatch commands. It is not static, since it may be usefull by itself, or it may desireable to replace it with a custom version in some applications. This can be done simply by overriding it, rather than editing the library itself. This is NOT a "safe" call, since it should never be called directly from client code. It is however safe if the client fails to initialize the command table pointer. INPUTS rexxmsg = pointer to the RexxMsg structure for the command we are dispatching. cmd = the command name string. RESULT None SIDES HISTORY 01-Aug-89 Creation. 26-Sep-89 Changed to use maximum and minimum argcounts. BUGS SEE ALSO RxilCheckPort() ---------------------------------------------------------------------- NAME RxilDumpRdef SYNOPSIS RxilDumpRdef( rdef, flags ); struct RxilDef *rdef; ULONG flags; FUNCTION This function is for debug and testing purposes. It will dump information about the current ARexx environment to the CLI. INPUTS rdef = pointer to the global RxilDef structure. flags = an unsigned long whose bits control just what information about the RxilDef structure is displayed. RESULT None SIDES HISTORY 01-Aug-89 Creation. 25-Sep-89 Added display of library version string. 01-Oct-89 Added "flags" argument to control just what is displayed, and ability to display the commands. 10-Nov-89 Changed format of command info display slightly. BUGS SEE ALSO ---------------------------------------------------------------------- NAME RxilEndCancel SYNOPSIS RxilEndCancel(); FUNCTION Removes the cancel requester. INPUTS None RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilPostCancel(), RxilCheckCancel() ---------------------------------------------------------------------- NAME RxilFuncPending SYNOPSIS flag = RxilFuncPending(); FUNCTION If any ARexx functions have been launched via a call to RxilLaunch(), and have not yet terminated, this will return TRUE. INPUTS None RESULT A boolean flag which indicates if any launches are in progress. SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilLaunch(), RxilPending(), RxilCmdPending() ---------------------------------------------------------------------- NAME RxilGetReturn SYNOPSIS rxi = RxilGetReturn(); struct RxilInvocation *rxi; FUNCTION This will return a pointer to any RxilInvocation message that has been replyed (but not yet cleaned up and available). NULL will be returned if all RxilInvocation structures which have been allocated are available or pending. INPUTS None RESULT A pointer to a RxilInvocation structure. If none have been replied and are available to be handled, this will return a NULL. SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO ---------------------------------------------------------------------- NAME RxilHandleReturn SYNOPSIS RxilHandleReturn( rxi ); struct RxilInvocation *rxi; FUNCTION Take appropriate action (i.e., notify user) for the return from an ARexx macro program. The method of notification will be an Intuition Autorequester if the Intuition library has been opened. If it is not, the message will be sent to the CLI (if possible) by opening "*". If this fails, no action is taken. Output is via AmigaDOS functions such as Write(), as opposed to using 'C' standard I/O such as printf(). INPUTS rxi = pointer to a RxilInvocation structure that has been replyed by the RexxMaster. RESULT None SIDES HISTORY 01-Aug-89 Creation. 10-Nov-89 Added Autorequester feature. Changed to use AmigaDOS I/O rather than 'C' stdio. BUGS SEE ALSO ---------------------------------------------------------------------- NAME RxilInit SYNOPSIS rdef = RxilInit( flags, portname ); struct RxilDef *rdef; ULONG flags; char *portname; FUNCTION Open the ARexx library and setup our message ports. Then allocate a RxilDef structure and do some default initialization of it. The portname will have a unique "instance" number appended to it in the format "<name>_#<n>" where <name> is the string as specified in the portname argument, and <n> is a decimal number from 1-99 inclusive. This feature may be inhibited by setting the RXIL_AS_IS flag. Even though this may fail, that should probably not be fatal since the ARexx functionality is optional. The RxilCheckPort() function is smart enough to just return if the rexx initialization was not successsfull. Not to mention that RxilCheckPort() should never get called since the rexx_sig_bit mask should be zero. INPUTS flags These are various defined constants which control which ports get opened and other various aspects of port initialization. portname This is the name to use for the public ARexx port that commands will be received at. It is suggested that this be in uppercase and contain no spaces. Maximum length is 40 characters, as set by the defined constant RXIL_MAX_PORTNAME_LEN. See discussion above about instance numbers. RESULT A pointer to a RxilDef structure. Return is NULL for failure to initialize the ARexx ports. SIDES HISTORY 01-Aug-89 Creation. 23-Sep-89 Changed "flags" arg from int to ULONG 26-Sep-89 Sets the (new) version string pointer. 01-Oct-89 Changed PublicPort name storage from a pointer to a character array. Added "instance" numbering. Added check on portname length. BUGS This should probably share one signal bit between both ports to avoid "hogging" signal bits. SEE ALSO RxilCleanup(), RXIL_AS_IS, RXIL_MAX_PORTNAME_LEN ---------------------------------------------------------------------- NAME RxilLaunch SYNOPSIS result = RxilLaunch( rxi ) LONG result; struct RxilInvocation *rxi; FUNCTION Launch an ARexx program by sending an invocation message to the RexxMaster process. The RxilInvocation structure which is allocated prior to this call via RxilCreateRxi() contains the information neccessary to launch the program. INPUTS rxi A pointer to an initialized RxilInvocation structure. RESULT Zero if the launch was successful, non-zero otherwise. SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilCreateRxi(), RxilDeleteRxi() ---------------------------------------------------------------------- NAME RxilOpenConsole SYNOPSIS RxilOpenConsole( console, rexxmsg ); char *console; struct RexxMsg *rexxmsg; FUNCTION This will open an AmigaDOS stream as specified by the console string. The filehandle is then placed in the rm_Stdin and rm_Stdout fields of the RexxMsg. INPUTS console = a string which defines the console stream to be opened. This will normally be something like "CON:0/0/400/100/". rexxmsg = pointer to the RexxMsg that the AmigaDOS file handles are to be set into. RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilCloseConsole() ---------------------------------------------------------------------- NAME RxilPending SYNOPSIS flag = RxilPending(); FUNCTION If any ARexx functions or commands have been launched via a call to RxilLaunch(), and have not yet terminated, this will return TRUE. INPUTS None RESULT A boolean flag which indicates if any launches are in progress. SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilLaunch(), RxilCmdPending(), RxilFuncPending() ---------------------------------------------------------------------- NAME RxilPostCancel SYNOPSIS RxilPostCancel(); FUNCTION This will post a cancel requester to allow the user to halt macro execution by clicking a button on the requester. The CancelWindow member of the RxilDef structure controls where the requester is posted. In the current version, the cancel requester always opens it's own window on the same screen as the Window whose pointer is in CancelWindow. If CancelWindow is NULL, the window will open on the WorkBench. INPUTS None RESULT None SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO RxilCheckCancel(), RxilEndCancel() ---------------------------------------------------------------------- NAME RxilSetResult SYNOPSIS RxilSetResult( rexxmsg, string ); struct RexxMsg *rexxmsg; char *string; FUNCTION This can be called to handle the details of placing a result string into the rexx message packet as the result Argstring. If the string pointer is NULL, a general failure code will be set. This will deal with inability to allocate the Argstring by setting a failure code in the RexxMsg. INPUTS rexxmsg = pointer to the RexxMsg that the reply is being set into. string = pointer to a null terminated text string which will be converted to an Argstring and returned. RESULT SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO ---------------------------------------------------------------------- NAME RxilToRexx SYNOPSIS result = RxilToRexx( cmd, arg0, arg1, arg2, arg3 ); LONG result ULONG cmd STRPTR arg0 STRPTR arg1 STRPTR arg2 STRPTR arg3 FUNCTION Send a command packet to the Rexx Master. This is an asynchronous send, no success or failure will be observed. INPUTS cmd = the command to send. arg0 = a null-terminated string to convert into an Argstring. arg1 = a null-terminated string to convert into an Argstring. arg2 = a null-terminated string to convert into an Argstring. arg3 = a null-terminated string to convert into an Argstring. RESULT Zero for success, non-zero to indicate failure. SIDES HISTORY 01-Aug-89 Creation. BUGS SEE ALSO ----------------------------------------------------------------------