home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / telecom / handshake_449 / handshake_arexx.doc < prev    next >
Text File  |  1991-02-02  |  12KB  |  261 lines
  1. -----------------
  2.  
  3.       /\/\
  4.      / /  \
  5.  ---/ / /\ \-----
  6.       \/  \ 
  7.  Hand     / Shake  Version 2.20a
  8.  ---\    / /-----
  9.      \  / /
  10.       \/\/
  11.  
  12. -----------------
  13.  
  14. The HandShake/AREXX Interface
  15. -----------------------------
  16.  
  17. HandShake has an AREXX port as of version 2.20a. This allows other
  18. programs to issue commands to HandShake, as well as providing a script
  19. language for HandShake. To use this feature, you must own a copy of AREXX
  20. which is available from you local dealer or directly from William Hawes.
  21.  
  22. HandShake deals with both AREXX commands and AREXX functions. When
  23. HandShake starts up, it will declare itself as an AREXX function host.
  24. Any AREXX macro which contains calls to the HandShake functions while
  25. HandShake is running will send them to HandShake.
  26.  
  27. In order to send commands to HandShake, it is nesessary to issue an
  28. ADDRESS or SHELL command from the macro of the following form:
  29.  
  30.         ADDRESS 'HANDSHAKE'  or
  31.         SHELL 'HANDSHAKE'
  32.  
  33. Note that the word HANDSHAKE must be in upper case. The name of the
  34. HandShake AREXX port is 'HANDSHAKE'. External programs can send commands
  35. or functions directly by sending correctly formatted Rexx Messages to
  36. this port.
  37.  
  38. Below is a list of the commands which can be sent to HandShake.
  39. NOTE: The case of the command or function name is not important to
  40.       HandShake.
  41.  
  42. COMMANDS
  43. --------
  44. HS_BAUD baud_rate       Sets the baud rate. The baud rate parameter can
  45.                         be any valid Amiga baud rate.
  46.  
  47. HS_COLOR                Causes HandShake to go into color (3 bit plane)
  48.                         mode. This command will fail if any windows are
  49.                         open on the HandShake screen.
  50.  
  51. HS_DATABITS stop_bits   Sets the number of data bits. This parameter must
  52.                         be '7' or '8'.
  53.  
  54. HS_DELAY seconds        Causes macro execution to pause for the specified
  55.                         number of seconds.
  56.  
  57. HS_ENDASCII             Causes an ASCII receive to finish.
  58.  
  59. HS_GETLENGTH            Sets the number of additional characters that are
  60.                         returned with the matched part of a string from
  61.                         the HS_GETSTR command. By default this is set to
  62.                         zero.
  63.  
  64. HS_HANGUP                Hang up the phone (Disconnect from the other host).
  65.  
  66. HS_HIDE                 Place the HandShake screen behind all other screens.
  67.  
  68. HS_MONO                 Causes HandShake to go into monochrome (2 bit
  69.                         plane) mode. This command will fail if any windows
  70.                         are open on the HandShake screen.
  71.  
  72. HS_PARITY parity        Sets the parity. The parameter must be one of:
  73.                         NONE, ODD, EVEN, SPACE, MARK.
  74.  
  75. HS_PROTOCOL protocol    This command sets the file transfer protocol for
  76.                         subsequent file transfers. The protocol must be
  77.                         one of:
  78.                                 ASCII
  79.                                 XMODEM
  80.                                 XMODEM/CRC
  81.                                 YMODEM
  82.                                 YMODEM/BATCH
  83.                                 KERMIT/TEXT
  84.                                 KERMIT/8BIT
  85.                                 KERMIT/7BIT
  86.                                 
  87. HS_SHOW                 Place the HandShake screen infront of all other
  88.                         screens.
  89.  
  90. HS_STOPBITS stop_bits   Sets the number of stop bits. This parameter must
  91.                         be '0' or '1' or '2'.
  92.  
  93. HS_TIMEOUT seconds      This sets the timeout value for the GETSTR()
  94.                         function. If no match is found within the
  95.                         specified number of seconds. The GETSTR() function
  96.                         will abort and return the string HSERR_TIMEOUT.
  97.  
  98. HS_QUIT                 This command will cause HandShake to terminate. It
  99.                         will fail if any windows are open on the HandShake
  100.                         screen.
  101.  
  102. Below is a list of the functions which can be sent to HandShake.
  103. NOTE: The returned value 'r' is a boolean value of '0' for failure or '1'
  104. for success unless otherwise noted.
  105.  
  106. NOTE: When calling AREXX functions, the openning parentheses must
  107. immediately follow the function name with no intervening white space.
  108.  
  109. r = HS_DIAL(dial_str)       This function dials a host system. The
  110.                             dial_str is a string of one of the following
  111.                             forms:
  112.                             'phone_number:baud_rate,data_bits,parity,
  113.                             stop_bits[*]'  or
  114.                             destination_name[*].
  115.                 
  116.                             HandShake makes a decision about which form is
  117.                             being used, based on the first character. if
  118.                             it is a numeric digit. If it is, it is assumed
  119.                             to be a phone_number string. If it is non-
  120.                             numeric, it is assumed to be a destination
  121.                             string.
  122.                 
  123.                             Note that the optional
  124.                             trailing '*' forces auto-redial.
  125.                 
  126.                             Following are some correct dial strings:
  127.                             '123-4567:2400,8,n,1'
  128.                             '1-(555)-555-5555:1200,8,e,1*'
  129.                             "Fred's BBS"
  130.                             'BIX'
  131.                             'John my brother'
  132.                             '555-5555:1200,7,e BIX*'
  133.                             The parameters after the phone number are
  134.                             optional, but they must be specified in the
  135.                             order if present.  A destination_name is the
  136.                             name of an entry in the dialing directory.
  137.                 
  138.                             For a more complete description of dial
  139.                             strings,see the file HandShake.doc.
  140.  
  141. r = HS_GETSTR(str1,str2,..) This function waits for one of the specified
  142.                             strings to arrive on the serial port. The
  143.                             first match will cause the funtion to return
  144.                             the string that was matched. If HS_GETLENGTH is
  145.                             set to a non-zero value, that number of additional
  146.                             characters will be returned wil the matched string.
  147.                             HS_GETSTR will wiat for a match for the number 
  148.                             of seconds specified by the HS_TIMEOUT command
  149.                             (see above). Upon completion, it will return
  150.                             either the matched string plus the next
  151.                             HS_GETLENGTH characters, or 'HSERR_TIMEOUT'
  152.                             in the event of a timeout.
  153.  
  154. r = HS_LOADPARMS(file_name) Load a parameter file. This is the same as
  155.                             selecting the load parameters item
  156.                             from the PROJECT menu. This function will
  157.                             fail if there are any windows open on the
  158.                             HandShake screen.
  159.  
  160. r = HS_RECEIVE(file_name)   This function causes HandShake to go into
  161.                             file receive mode. This file is received
  162.                             using the protocol selected by the PROTOCOL
  163.                             command (see above). If one of the batch
  164.                             protocols (Kermit or Ymodem Batch) is being
  165.                             used, the file name parameter is the 
  166.                             destination path name and must be terminated
  167.                             with a '/' or a ':'
  168.  
  169.                             if ASCII protocol is selected, this function
  170.                             only starts the receive. To terminate the
  171.                             ASCII receive, use the ENDASCII command
  172.                             described above.
  173.  
  174. r = HS_SAVEPARMS(file_name) Save current parameters to a file. This is
  175.                             the same as selecting the save parameters
  176.                             item from the PROJECT menu.
  177.  
  178. r = HS_STRING(char_str)     This function sends the specified string
  179.                             out the serial port. No carriage return is
  180.                             sent. A carriage return is not automatically
  181.                             appended. If you wish to send a carriage
  182.                             return of any other control character, it must
  183.                             be formatted into the string. onw way of doing
  184.                             this is illustrated below:
  185.                 
  186.                             /* Assign some characters to variables.*/
  187.                             cr = '0d'x
  188.                             esc = '1b'x
  189.                             /* Send a string without a carriage return */
  190.                             r = hs_string('No carriage return')
  191.                             /* Send a string with a carriage return */
  192.                             r = hs_string('With carriage return'cr)
  193.                             /* Send an escape sequence */
  194.                             r = hs_string(esc'[0m')
  195.                 
  196.                             The same technique could be used to define an
  197.                             ESCAPE character for instance.
  198.                             Any Features of the AREXX language can be used
  199.                             to build the string to be sent.
  200.  
  201. r = HS_TRANSMIT(file_name)  This function causes HandShake to go into
  202.                             file transmit mode. The file is transmitted
  203.                             using the protocol selected by the protocol
  204.                             command (see above). If one of the batch
  205.                             protocols (Kermit of Ymodem Batch) is being
  206.                             used, the file name parameter can contain
  207.                             AmigaDOS wild card characters.
  208.  
  209.  
  210. INVOKING AREXX MACROS FOR USE WITH HandShake
  211. --------------------------------------------
  212.  
  213. There are five ways to invoke an AREXX macro for use with HandShake:
  214.         1) From a workbench CLI window.
  215.         2) From a HandShake CLI window.
  216.         3) From the RUN MACRO item in the AREXX menu.
  217.         4) From the HandShake command line.
  218.         5) From a HandShake Project icon.
  219.  
  220. The first two methods are the same as running any other AREXX macro from
  221. the command line. In the first case just invoke the macro from any
  222. workbench WSHELL, AmigaShell or CLI window (or anybody elses shell for
  223. that matter.
  224.  
  225. In order to make it easier to run macros (especially those that require
  226. parameters from the command line) HandShake lets you open a CLI window
  227. on the HandShake screen if you have William Hawe's CONMAN console
  228. editing/manager running on your system. This is done by selecting the
  229. DOS window item from the AREXX window. HandShake will first try to start
  230. a WShell ( William Hawe's wonderfull shell), Then an AmigaShell and
  231. finally a CLI window on the HandShake screen. You can have as many of
  232. these DOS windows open as you like. Beware that some commands or functions
  233. sent to HandShake will not work if there is a window open on the HandShake
  234. screen. This is because some operations cause HandShake to close its
  235. screen (either temporarily or permanently), and this cannot be safely done
  236. with windows open on the screen. If the macro is run from a CLI on the
  237. workbench screen all commands and functions sent to HandShake by AREXX
  238. will function normally.
  239.  
  240. The third method can be used to run any AREXX macro which does not take
  241. any command line parameters. The RUN MACRO menu item will open a file
  242. requester. Just select the file which contains the AREXX macro which you
  243. would like to run. All commands and functions sent from AREXX to HandShake
  244. work when using this method.
  245.  
  246. The Fourth method allows you to have HandShake invoke an AREXX macro as
  247. it starts up. just specify the -m switch on the command line followed by
  248. the macro name. For instance:
  249.         HandShake -m readbix
  250. will invoke the READBIX.REXX macro. If a dial descriptor is included
  251. on the command line, the dial activity will take place before the macro
  252. is invoked.
  253.  
  254. The fifth method can be used when invoking HandShake from an icon. If
  255. there is a Tool Types array entry in the icon of the form:
  256.         MACRO=READBIX
  257. it will be invoked when HandShake is started. If there is also a
  258. DIALUP= Tool Types entry, the dial activity will happen first.
  259.  
  260.  
  261.