Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 592b.lha / TermII / English / Documentation / XCMD.doc.pp / XCMD.doc

Wrap

Text File | 1992-01-02 | 15.8 KB | 422 lines

July 2nd 1991 Term II version 1.1 (c) 1990,1991 - Eric GONTIER XCMD.doc INTRODUCTION : Term II is able to communicate with some Amiga processes, getting commands from them, executing these commands and returning values to them. So, anyone which is a "programer" can create his own programs to add functionalities to Term II or programs which can use some Term II functionalities to perform their own work. The examples include here were written in C (with DICE, Matt Dillon's shareware C compiler), but other languages can be used. "The command panel" is a very simple example of such possibilities. This file will try to explain how to write your own "XCMDs" (eXternal CoMmanDs). LES XCMD : Really, XCMD are only messages exchanged between the Term II message port, and the message port of an other process. The name of the Term message port is XTERM. Processes can post message to this port and wait for the answer. When Term get a message in his XTERM port, it will try to interpret it, excute the command and return the result. Each process must have its very own port. In the "panel" example, the port is named PANEL. Don't forget that each message received must be returned to the sender. Term has two special commands that can be sent to its external processes. These commands are Exec messages with special values. They are called START and STOP : · With START, Term II can wake up a waiting process. It gives also locks on the current screen and the current directory. · STOP is used to stop an external process. These two commands are send by Term II to external processes. Term user decide when to send this command. These are the only two messages Term II can send to external process (and the external process must return the messages when they are processed). On the other side, the external process can send all the commands recognized by Term II. See the file COMMANDES.doc for a complete description of each command available. THE XCMD DATA TYPE : So an XCMD is an Exec message. Here is the C structure corresponding to an XCMD : struct XCMD { struct Message xcmd_Message; long xcmd_TermCmd; struct Screen *xcmd_TermScreen; BPTR xcmd_TermDir; char *xcmd_Command; void *xcmd_Args[16]; BOOL xcmd_TermError; }; And here is the signification of each fields : xcmd_Message : This is a standard Exec message xcmd_TermCmd : 0 if not used. Otherwise, START or STOP value in case of a message sent by Term II (see XCMD.h file) xcmd_TermScreen : A pointer to the current screen used by Term. It is also a lock on a public screen. This value is used only in case of START or STOP command. xcmd_TermDir : A lock on the current Term II directory. This field is only used in case of START or STOP command. xcmd_Cmd : This is where to put the command to be executed by Term II. It is a pointer to a string. The external process initialise this field with the command to be executed, send the message to the TERM port and wait for the answer. xcmd_Args : 16 pointers to exchange values with Term II. Can be used to send arguments with some Term commands, or to obtains some values from Term II xcmd_TermError : This boolean field is TRUE if an error occur when Term II try to execute the command. XCMD TOOLKIT : They are some files to look at to get informations : - XCMD.h defines the XCMD data type as well as START and STOP command. - XCMDTools.h : prototypes for functions to the XCMD toolkit (XCMDTools.c) - XCMDTools.c : XCMD toolkit, with simple and useful functions to deal with XCMD - Panel.c : XCMD example. Implementation of a panel command, with 25 buttons. The user can set a command to be executed by Term to each buttons. This is nearly the same version than the one that came with Term II. - XCMDLaser.c : an other XCMD example to download a postscript file to an Apple Laser Writer. XCMDTool is a set of functions to help to make your own XCMD. There are nothing "magic" about it : it is simple and useful. You are not even obliged to use it. Here are the functions define in the toolkit : struct XCMD *CreateXCMD(struct MsgPort *); This creates and XCMD. Return NULL if failed, or a pointer to an XCMD if succeeded. All fiels in the Message part are set properly. The MsgPort in argument is the port where the message will be returned by Term II. Once the XCMD has been created, the process has to put its command in the xmcd_Cmd field. void DeleteXCMD(struct XCMD *); Delete and free memory allocated to an XCMD BOOL SendXCMD(struct XCMD *); Send an XCMD to Term II. Return TRUE if succeded, FALSE otherwise. START/STOP : The Term II user can send a START (to wake up an external process sleeping in the background), or a STOP to stop running an external process. These commands can be sent by the following Term II commands (see the file COMMANDS.doc) xcmd_start "port_name" Term II will try to send a START command to a message port named "port_name" xcmd_stop "port_name" Term II will try to send a STOP command to a message port named "port_name" The programmer of an external process has only one charge : asnwer the messages send by Term II. However, when a START command is issued by Term II, Term will get a lock on the current directory, and a lock on the public screen the Term II window is opened on. The external process _will have to_ unlock these locks before quitting. The screen lock can be freed with UnlockPubScreen(), and the directory lock can be freed with UnLock(). Note that the some external processes might not need or use START and STOP. See the examples : the panel use the start and stop command, but the XCMDLaser does not. The START and STOP commands are the only messages Term can send. In all the other cases, it is always the external process that sends commands to Term II. Term II recognizes special commands in the case of XCMD. These commands can be used only from an external process. (Not an ARexx script, or directly from Term II). They have been added to make the writing of external processes simpler. These commands are described in the paragraph SPECIAL COMMANDS. SPECIAL COMMANDS : The external process can send any of the commands recognized by Term II as well as special commands defined for XCMD. Here is an example on how to send a command (sending the string "This is a test\n" on the serial device) : /* The message port MyPort must have been created */ struct XCMD *xcmd = CreateXCMD(MyPort); if(xcmd) { xcmd->xcmd_Cmd = "serial_send \"This is a test\n\""; if(SendXCMD(XCMD)) { /* The XCMD has been sent. We have to wait */ /* for the returned message */ WaitPort(MyPort); GetMsg(MyPort); /* We can test xcmd->xcmd_TermError to know */ /* if everything was all right */ } } The commands recognized by Term II are described in the file COMMANDS.doc. But here are the commands that can be used only in the case of XCMD : xcmd_delay This is the same as rexx_delay. It allows the external process to perform a delay. The value of the delay is given in seconds. xcmd_Args[0] is a pointer to a long which is the value of the delay. xcmd_lock_request This command allows the external process to ask for locks on the screen used by Term II, and on the directory used by Term II. This is useful if the external process is not waiting for a START. The external process must free the locks before quitting (see UnlockPubScreen() in intuition.library to unlock the screen and UnLock() in dos.library to unlock the directory). The lock values can be found in xcmd_TermScreen and xmcd_TermDir when the message is returned from Term. xcmd_memory_request Before using this command, the external process has to tell Term II to put its "memory" on. See the command xmcd_memory_on and xcmd_memory_off. Ask Term II to returned the last 80 characters received from the serial device. The external process has to provide a valid pointer to a string of 81 chars (80 chars + NULL) in which Term will copy the last 80 chars received. This pointer has to be placed in the xcmd_Args[0] field before the command is sent to Term by the external process. xcmd_memory_off This turn the "memory" of Term II off. When this command is executed, Term will stop to memorize the last 80 chars received from the serial device. xcmd_memory_on Turn the "memory" on. When the "memory" is on, Term II will always memorize the last 80 chars received from the serial.device. These characters can be read from the external process with a xcmd_memory_request command. xcmd_setserial This command allows the external process to change the parameters of the serial device. The mechanism used is the same as the one defined by Willy Langeveld in the XPR 2.0 standard. When the message is sent to Term, the xcmd_Args[0] field must contain a long with the new parameters. Term II return the old parameters in xmcd_Args[15], or -1 in case of error. If, when the message is sent by the external process, the value in xmcd_Args[0] is -1, then Term II will returned the current parameters without changing anything. A long to define the parameters of serial device made of : byte 0 : same as field SerFlags in IOExtSer bit 0 : parity ON if set bit 1 : parity odd if set bit 2 : 7-wire protocol if set bit 3 : queued break if set bit 4 : rad-boogie if set bit 5 : shared mode if set bit 6 : EOF mode if set bit 7 : protocol if set byte 1 : bit 0 : parity mark or space if set bit 1 : parity mark if set, space otherwise bit 2 : 2 stop bits if set, 1 otherwise bit 3 : read word length is 7 if set, 8 otherwise bit 4 : write word length is 7 if set, 8 otherwise bit 5 : not used bit 6 : not used bit 7 : not used byte 2 : speed, like in preferences.h - 110 baud = 0 - 300 baud = 1 - 1200 baud = 2 - 2400 baud = 3 - 4800 baud = 4 - 9600 baud = 5 - 19200 baud = 6 - midi = 7 - 38400 baud = 8 - 57600 baud = 9 - 76800 baud = 10 - 115200 baud = 11 byte 3 : not used xcmd_sflush flush serial device buffers xcmd_squery Return the number of chars waiting in the buffer of the serial device in xcmd_Args[15]. -1 in case of error xcmd_sread This command allows the external process to read characters from the serial device. xcmd_Args[0] is a pointer to buffer (provided by the external process), xcmd_Args[1] is the number of characters to read, and xcmd_Args[2] is a timeout given in micro-seconds. Term II will return the number of characters read in xcmd_Args[15], or -1 in case of error. If the time out value (in xcmd_Args[2]) is 0, Term will try to read as many characters as possible without waiting. Term return the message as soon as they are no characters waiting to be read from the serial device, or if the buffer is full (size of buffer is in xcmd_Args[1]) ATTENTION : when reading, be sure to be the only one to read the serial port. See the commands serial_on and serial_off in COMMANDS.doc xcmd_swrite This command allows the external process to write chars on the serial.device. xcmd_Args[0] is the address of a buffer and xcmd_Args[1] is the number of characters to write. xcmd_wait Like rexx_wait. This command can be used to perform a delay. xcmd_Args[0] is a pointer to a long which is the value of the delay in seconds.