home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d576 / termii.lha / TermII / English / Documentation / XCMD.doc < prev    next >
Text File  |  1991-12-22  |  16KB  |  422 lines
  1. July 2nd 1991
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                     Term II
  16.  
  17.                                   version 1.1
  18.  
  19.                         (c) 1990,1991 - Eric GONTIER
  20.  
  21.                                     XCMD.doc
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.         INTRODUCTION :
  33.  
  34.             Term II is able to communicate with some Amiga processes,
  35.             getting commands from them, executing these commands and
  36.             returning values to them. So, anyone which is a "programer" can
  37.             create his own programs to add functionalities to Term II or
  38.             programs which can use some Term II functionalities to perform
  39.             their own work. The examples include here were written in C
  40.             (with DICE, Matt Dillon's shareware C compiler), but other
  41.             languages can be used.
  42.  
  43.             "The command panel" is a very simple example of such
  44.             possibilities.
  45.  
  46.             This file will try to explain how to write your own "XCMDs"
  47.             (eXternal CoMmanDs).
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.         LES XCMD :
  55.  
  56.             Really, XCMD are only messages exchanged between the Term II
  57.             message port, and the message port of an other process. The
  58.             name of the Term message port is XTERM. Processes can post
  59.             message to this port and wait for the answer. When Term get a
  60.             message in his XTERM port, it will try to interpret it, excute
  61.             the command and return the result.
  62.  
  63.             Each process must have its very own port. In the "panel"
  64.             example, the port is named PANEL.
  65.  
  66.             Don't forget that each message received must be returned to the
  67.             sender.
  68.  
  69.             Term has two special commands that can be sent to its external
  70.             processes. These commands are Exec messages with special
  71.             values. They are called START and STOP :
  72.  
  73.                 · With START, Term II can wake up a waiting process. It
  74.                 gives also locks on the current screen and the current
  75.                 directory.
  76.  
  77.                 · STOP is used to stop an external process.
  78.  
  79.             These two commands are send by Term II to external processes.
  80.             Term user decide when to send this command. These are the only
  81.             two messages Term II can send to external process (and the
  82.             external process must return the messages when they are
  83.             processed).
  84.  
  85.             On the other side, the external process can send all the
  86.             commands recognized by Term II. See the file COMMANDES.doc for
  87.             a complete description of each command available.
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.         THE XCMD DATA TYPE :
  95.  
  96.             So an XCMD is an Exec message. Here is the C structure
  97.             corresponding to an XCMD :
  98.  
  99.                 struct XCMD
  100.                   {
  101.                   struct Message xcmd_Message;
  102.                   long           xcmd_TermCmd;
  103.                   struct Screen *xcmd_TermScreen;
  104.                   BPTR           xcmd_TermDir;
  105.                   char          *xcmd_Command;
  106.                   void          *xcmd_Args[16];
  107.                   BOOL           xcmd_TermError;
  108.                   };
  109.  
  110.             And here is the signification of each fields :
  111.  
  112.                 xcmd_Message :
  113.  
  114.                     This is a standard Exec message
  115.  
  116.                 xcmd_TermCmd :
  117.  
  118.                     0 if not used. Otherwise, START or STOP value in case
  119.                     of a message sent by Term II (see XCMD.h file)
  120.  
  121.                 xcmd_TermScreen :
  122.  
  123.                     A pointer to the current screen used by Term. It is
  124.                     also a lock on a public screen. This value is used only
  125.                     in case of START or STOP command.
  126.  
  127.                 xcmd_TermDir :
  128.  
  129.                     A lock on the current Term II directory. This field is
  130.                     only used in case of START or STOP command.
  131.  
  132.                 xcmd_Cmd :
  133.  
  134.                     This is where to put the command to be executed by Term
  135.                     II. It is a pointer to a string. The external process
  136.                     initialise this field with the command to be executed,
  137.                     send the message to the TERM port and wait for the
  138.                     answer.
  139.  
  140.                 xcmd_Args :
  141.  
  142.                     16 pointers to exchange values with Term II. Can be
  143.                     used to send arguments with some Term commands, or to
  144.                     obtains some values from Term II
  145.  
  146.                 xcmd_TermError :
  147.  
  148.                     This boolean field is TRUE if an error occur when Term
  149.                     II try to execute the command.
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.         XCMD TOOLKIT :
  160.  
  161.             They are some files to look at to get informations :
  162.  
  163.                 - XCMD.h defines the XCMD data type as well as START and
  164.                 STOP command.
  165.  
  166.                 - XCMDTools.h : prototypes for functions to the XCMD
  167.                 toolkit (XCMDTools.c)
  168.  
  169.                 - XCMDTools.c : XCMD toolkit, with simple and useful
  170.                 functions to deal with XCMD
  171.  
  172.                 - Panel.c : XCMD example. Implementation of a panel
  173.                 command, with 25 buttons. The user can set a command to be
  174.                 executed by Term to each buttons. This is nearly the same
  175.                 version than the one that came with Term II.
  176.  
  177.                 - XCMDLaser.c : an other XCMD example to download a
  178.                 postscript file to an Apple Laser Writer.
  179.  
  180.             XCMDTool is a set of functions to help to make your own XCMD.
  181.             There are nothing "magic" about it : it is simple and useful.
  182.             You are not even obliged to use it. Here are the functions
  183.             define in the toolkit :
  184.  
  185.                 struct XCMD *CreateXCMD(struct MsgPort *);
  186.  
  187.                     This creates and XCMD. Return NULL if failed, or a
  188.                     pointer to an XCMD if succeeded. All fiels in the
  189.                     Message part are set properly. The MsgPort in argument
  190.                     is the port where the message will be returned by Term
  191.                     II. Once the XCMD has been created, the process has to
  192.                     put its command in the xmcd_Cmd field.
  193.  
  194.                 void DeleteXCMD(struct XCMD *);
  195.  
  196.                     Delete and free memory allocated to an XCMD
  197.  
  198.  
  199.                 BOOL SendXCMD(struct XCMD *);
  200.  
  201.                     Send an XCMD to Term II. Return TRUE if succeded, FALSE
  202.                     otherwise.
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.         START/STOP :
  210.  
  211.             The Term II user can send a START (to wake up an external
  212.             process sleeping in the background), or a STOP to stop running
  213.             an external process. These commands can be sent by the
  214.             following Term II commands (see the file COMMANDS.doc)
  215.  
  216.                 xcmd_start "port_name"
  217.  
  218.                     Term II will try to send a START command to a message
  219.                     port named "port_name"
  220.  
  221.                 xcmd_stop "port_name"
  222.  
  223.                     Term II will try to send a STOP command to a message
  224.                     port named "port_name"
  225.  
  226.             The programmer of an external process has only one charge :
  227.             asnwer the messages send by Term II.
  228.  
  229.             However, when a START command is issued by Term II, Term will
  230.             get a lock on the current directory, and a lock on the public
  231.             screen the Term II window is opened on. The external process
  232.             _will have to_ unlock these locks before quitting. The screen
  233.             lock can be freed with UnlockPubScreen(), and the directory
  234.             lock can be freed with UnLock().
  235.  
  236.             Note that the some external processes might not need or use
  237.             START and STOP. See the examples : the panel use the start and
  238.             stop command, but the XCMDLaser does not.
  239.  
  240.             The START and STOP commands are the only messages Term can
  241.             send. In all the other cases, it is always the external process
  242.             that sends commands to Term II.
  243.  
  244.             Term II recognizes special commands in the case of XCMD. These
  245.             commands can be used only from an external process. (Not an
  246.             ARexx script, or directly from Term II). They have been added
  247.             to make the writing of external processes simpler. These
  248.             commands are described in the paragraph SPECIAL COMMANDS.
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.         SPECIAL COMMANDS :
  257.  
  258.             The external process can send any of the commands recognized by
  259.             Term II as well as special commands defined for XCMD.
  260.  
  261.             Here is an example on how to send a command (sending the string
  262.             "This is a test\n" on the serial device) :
  263.  
  264.                 /* The message port MyPort must have been created   */
  265.                     struct XCMD *xcmd = CreateXCMD(MyPort);
  266.                     if(xcmd) {
  267.                     xcmd->xcmd_Cmd = "serial_send \"This is a test\n\"";
  268.                     if(SendXCMD(XCMD))
  269.                       {
  270.                       /* The XCMD has been sent. We have to wait    */
  271.                       /* for the returned message                   */
  272.                       WaitPort(MyPort);
  273.                       GetMsg(MyPort);
  274.                       /* We can test xcmd->xcmd_TermError to know   */
  275.                       /* if everything was all right                */
  276.                       }
  277.                     }
  278.  
  279.             The commands recognized by Term II are described in the file
  280.             COMMANDS.doc. But here are the commands that can be used only
  281.             in the case of XCMD :
  282.  
  283.  
  284.                 xcmd_delay
  285.  
  286.                     This is the same as rexx_delay. It allows the external
  287.                     process to perform a delay. The value of the delay is
  288.                     given in seconds. xcmd_Args[0] is a pointer to a long
  289.                     which is the value of the delay.
  290.  
  291.                 xcmd_lock_request
  292.  
  293.                     This command allows the external process to ask for
  294.                     locks on the screen used by Term II, and on the
  295.                     directory used by Term II. This is useful if the
  296.                     external process is not waiting for a START. The
  297.                     external process must free the locks before quitting
  298.                     (see UnlockPubScreen() in intuition.library to unlock
  299.                     the screen and UnLock() in dos.library to unlock the
  300.                     directory). The lock values can be found in
  301.                     xcmd_TermScreen and xmcd_TermDir when the message is
  302.                     returned from Term.
  303.  
  304.                 xcmd_memory_request
  305.  
  306.                     Before using this command, the external process has to
  307.                     tell Term II to put its "memory" on. See the command
  308.                     xmcd_memory_on and xcmd_memory_off.
  309.  
  310.                     Ask Term II to returned the last 80 characters received
  311.                     from the serial device. The external process has to
  312.                     provide a valid pointer to a string of 81 chars (80
  313.                     chars + NULL) in which Term will copy the last 80 chars
  314.                     received. This pointer has to be placed in the
  315.                     xcmd_Args[0] field before the command is sent to Term
  316.                     by the external process.
  317.  
  318.                 xcmd_memory_off
  319.  
  320.                     This turn the "memory" of Term II off. When this
  321.                     command is executed, Term will stop to memorize the
  322.                     last 80 chars received from the serial device.
  323.  
  324.                 xcmd_memory_on
  325.  
  326.                     Turn the "memory" on. When the "memory" is on, Term II
  327.                     will always memorize the last 80 chars received from
  328.                     the serial.device. These characters can be read from
  329.                     the external process with a xcmd_memory_request
  330.                     command.
  331.  
  332.                 xcmd_setserial
  333.  
  334.                     This command allows the external process to change the
  335.                     parameters of the serial device. The mechanism used is
  336.                     the same as the one defined by Willy Langeveld in the
  337.                     XPR 2.0 standard. When the message is sent to Term, the
  338.                     xcmd_Args[0] field must contain a long with the new
  339.                     parameters. Term II return the old parameters in
  340.                     xmcd_Args[15], or -1 in case of error. If, when the
  341.                     message is sent by the external process, the value in
  342.                     xmcd_Args[0] is -1, then Term II will returned the
  343.                     current parameters without changing anything. A long to
  344.                     define the parameters of serial device made of :
  345.  
  346.                     byte 0 : same as field SerFlags in IOExtSer
  347.                         bit 0 : parity ON if set
  348.                         bit 1 : parity odd if set
  349.                         bit 2 : 7-wire protocol if set
  350.                         bit 3 : queued break if set
  351.                         bit 4 : rad-boogie if set
  352.                         bit 5 : shared mode if set
  353.                         bit 6 : EOF mode if set
  354.                         bit 7 : protocol if set
  355.  
  356.                     byte 1 :
  357.                         bit 0 : parity mark or space if set
  358.                         bit 1 : parity mark if set, space otherwise
  359.                         bit 2 : 2 stop bits if set, 1 otherwise
  360.                         bit 3 : read word length is 7 if set, 8 otherwise
  361.                         bit 4 : write word length is 7 if set, 8 otherwise
  362.                         bit 5 : not used
  363.                         bit 6 : not used
  364.                         bit 7 : not used
  365.  
  366.                     byte 2 : speed, like in preferences.h
  367.                         -    110 baud = 0
  368.                         -    300 baud = 1
  369.                         -   1200 baud = 2
  370.                         -   2400 baud = 3
  371.                         -   4800 baud = 4
  372.                         -   9600 baud = 5
  373.                         -  19200 baud = 6
  374.                         -   midi      = 7
  375.                         -  38400 baud = 8
  376.                         -  57600 baud = 9
  377.                         -  76800 baud = 10
  378.                         - 115200 baud = 11
  379.  
  380.                     byte 3 : not used
  381.  
  382.                 xcmd_sflush
  383.  
  384.                     flush serial device buffers
  385.  
  386.                 xcmd_squery
  387.  
  388.                     Return the number of chars waiting in the buffer of the
  389.                     serial device in xcmd_Args[15]. -1 in case of error
  390.  
  391.                 xcmd_sread
  392.  
  393.                     This command allows the external process to read
  394.                     characters from the serial device. xcmd_Args[0] is a
  395.                     pointer to buffer (provided by the external process),
  396.                     xcmd_Args[1] is the number of characters to read, and
  397.                     xcmd_Args[2] is a timeout given in micro-seconds. Term
  398.                     II will return the number of characters read in
  399.                     xcmd_Args[15], or -1 in case of error. If the time out
  400.                     value (in xcmd_Args[2]) is 0, Term will try to read as
  401.                     many characters as possible without waiting. Term
  402.                     return the message as soon as they are no characters
  403.                     waiting to be read from the serial device, or if the
  404.                     buffer is full (size of buffer is in xcmd_Args[1])
  405.  
  406.                     ATTENTION : when reading, be sure to be the only one to
  407.                     read the serial port. See the commands serial_on and
  408.                     serial_off in COMMANDS.doc
  409.  
  410.                 xcmd_swrite
  411.  
  412.                     This command allows the external process to write chars
  413.                     on the serial.device. xcmd_Args[0] is the address of a
  414.                     buffer and xcmd_Args[1] is the number of characters to
  415.                     write.
  416.  
  417.                 xcmd_wait
  418.  
  419.                     Like rexx_wait. This command can be used to perform a
  420.                     delay. xcmd_Args[0] is a pointer to a long which is the
  421.                     value of the delay in seconds.
  422.