home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / internet / starterpck / !SLIPdial / !Help < prev    next >
Text File  |  1995-04-09  |  32KB  |  798 lines
  1. SLIPdial - a dialler for Archimedes !TCPIP               version 0.34
  2. ------------------------------------------
  3.  
  4. Slipdial is a script-driven dialler and general-control program for
  5. communications using !TCPIP. Its primary use is to initiate a connection
  6. with the network services provider (including dialling and logging-in)
  7. before handing over control to !TCPIP, and then to close down the connection
  8. cleanly when !TCPIP has finished. As well as the normal dialling and
  9. expect/send string functions for controlling your modem and negotiating a
  10. login, it also has many facilities to start and kill sub-tasks (both
  11. wimp-based and taskwindow-based); capturing and displaying messages from the
  12. remote computer; file handling; dialogue with the user; timer functions and
  13. more...
  14.  
  15. For example, you can define new icons to be added to the icon bar, which can
  16. have script-defined menus associated with them, as well as predefined
  17. actions for when the user clicks on them or drops a file on them.
  18.  
  19. Windows and controls
  20. --------------------
  21.  
  22. When slipdial starts, its icon appears on the icon bar. Clicking with SELECT
  23. on this icon opens the Status window, which tells you slipdial's state, and
  24. may allow selection of actions from a user-defined menu. Four icons down the
  25. right side of the window give access to a menu, perform a redial (if
  26. dialling), pause/unpause the script, or stop the script.
  27.  
  28. If no script is loaded, either as a default or by the startup switches you
  29. used (see later), you can load and start one by dropping its file on the
  30. iconbar icon or on the status window, or you can select one from the status
  31. window menu. Most of the time, however, a script will be run automatically.
  32.  
  33. Clicking on the slipdial icon with the ADJUST button opens the Control
  34. window. This window displays the script as it executes, incoming text from
  35. the serial port, and other status information. At the bottom of this window
  36. is an input field, which allows you to directly enter slipdial commands.
  37.  
  38. Two menus are available from the Control window. Pressing MENU gives you the
  39. choice of listing various items - the script itself; the currently-defined
  40. menus; variables, tasks and alarms. Pressing MENU while holding down the
  41. CTRL key lets you change the current "Debug level". This controls how much
  42. information about script execution is displayed in the Control window (see
  43. the entry on the "debug" command for more information on the exact effects).
  44.  
  45. The other window available from the slipdial icon - actually from its
  46. associated menu - is the "Choices" window. With this you can specify which
  47. windows to open, how large to make them, and whether to run a specified
  48. script automatically (you can drag a file to the writable field to set
  49. this). These choices can be saved as default actions for every time you run
  50. slipdial.
  51.  
  52. The Status Window
  53. -----------------
  54.  
  55. If you have trouble getting slipdial to communicate with your modem, the
  56. status window contains some diagnotic aids in the form of 3 "LED's", in the
  57. lower right-hand corner of the window. These show the state of some of the
  58. more important serial control lines - from left to right: DTR (data terminal
  59. ready); CTS and CD (carrier detect). Of these, probably only DTR and CD are
  60. of very much interest - DTR indicates that the serial line is active and the
  61. modem is in a condition to be talked-to; while CD indicates that the modem
  62. is online and has established communication with the remote modem.
  63.  
  64. Startup flags
  65. -------------
  66.  
  67. To override the auto-run option, hold down the ALT key while starting
  68. SLIPdial.
  69.  
  70. Command-line startup flags include:
  71.  
  72. -file <filename>
  73.  runs a specified script file on startup. Example:
  74.    run Slipdial:!Run -file SLIPdial:call_demon
  75.  
  76. -quiet
  77.  pevents status and control windows from being opened at startup.
  78.  
  79. -auto
  80.  autoruns the script Slipdial:default
  81.  
  82. -sprite <size>
  83.  specifies size of slipdial's internal sprite area, for addition of user icons.
  84.  
  85. All startup flags/switches can be abbreviated to 1 significant character. For
  86. example:
  87.   run slipdial:!Run -s 8000 -f Slipdial:call_demon
  88.  
  89. Script language
  90. ---------------
  91.  
  92. There's no consistancy to what's in the language; just whatever I thought
  93. might be useful. The language has evolved to be something like VMS DCL, in
  94. that commands are often modified by qualifiers (command/qualifier=value).
  95. It's even similar to DCL in its extreme lethargy of execution!
  96.  
  97. One useful point to know is that the first line of a script MUST be:
  98. #slipdial
  99.  
  100. and another is that that scriptfiles must have the "Text" filetype. The
  101. "#slipdial" comment at the start of the file prevents slipdial from
  102. attempting to load non-script textfiles.
  103.  
  104. Events
  105. ------
  106.  
  107. Certain commands set up actions with may occur asynchronously, meaning they
  108. don't follow the normal flow of the script. These could include timed
  109. alarms, user menu selections, line-condition alarms, etc. For the sake of
  110. giving these a name, I shall call these "events". Though they can be a
  111. little hard to understand at first (they can make it hard to understand the
  112. "flow" of your script), many of the most useful script capabilities center
  113. around them.
  114.  
  115. SLIPdial script syntax
  116. ----------------------
  117.  
  118. Many slipdial commands can take qualifiers, which alter their behaviour
  119. in some way. Command qualifiers are introduced with a slash (/) and may in
  120. some cases be followed by a value after an equals sign.
  121.  
  122. Parameters and qualifiers are generally space-delimited - if you wish to
  123. include spaces, the parameter or qualifier should be enclosed in quotation
  124. marks.
  125.  
  126. Multiple commands on a line are separated with the ";" character.
  127.  
  128. Commands may be continued across lines by using a trailing "-".
  129.  
  130. Characters with special meaning may be escaped with the "\" character to
  131. prevent their interpretation. Special characters include:
  132.  /      introduces qualifier
  133.  space  separates command components
  134.  "      encloses components to prevent splitting
  135.  ;      separates commands on a line
  136.  %      introduces script variable
  137.  \      the escape character itself
  138.  
  139. Remember to use extra escape characters in lines which may be expanded more
  140. than once. For example, the line:
  141.  alarm/icon=test "message \\%$file \\%$type"
  142. needs two escape characters to quote the variables, as they are expanded
  143. once upon setting the alarm, then again on alarm execution. Unfortunately,
  144. the number of escape characters needed in any relatively complex situation
  145. like this may not make sense. Where this proves to be a problem, the command
  146. may be preceded by the "literal" command to prevent any interpretation of
  147. special characters (such as % or \) in that command. This is particularly
  148. useful in setting variables for modem initialisation strings.
  149.  
  150. The values of script variables may be substituted into lines by prefixing
  151. them with a "%". For example, after the command "set test hello", the
  152. command "message %test" expands into "message hello".
  153.  
  154. The output of another command can also be substituted into a line. To do
  155. this, the command is enclosed in curly brackets {,}. The return value of the
  156. enclosed command will be substituted in its place. For example:
  157.  set test {?file slipdial:!run}
  158. expands to:
  159.  set test 1
  160. (assuming the file 'slipdial:!Run' has an object type of 1).
  161. Another example:
  162.  message {icon/free}
  163. displays the number of free bytes in the slipdial sprite area in a window.
  164.  
  165. Slipdial script commands
  166. ------------------------
  167. 1: General
  168. ----------
  169.  
  170. # comment
  171.  introduces a comment - the line is ignored (and, in fact, not loaded).
  172.  
  173. debug <n>
  174.  sets debugging level - controls what level of information is sent to the
  175.  control window and debug file (if any).
  176.    0 no debug output
  177.    1 script progress
  178.    2 text received from modem
  179.    3 log both text & script
  180.  
  181. echo [/status] [/date] <string>
  182.  echoes a string (or set of strings) to the control window (default)
  183.   or the status window.
  184.  /date adds the current date to the string before writing.
  185.  
  186. set <variable> <value> [<variable> <value> ... ]
  187.  assigns a value to a script variable. <value> should be quoted if it
  188.  includes spaces. More than one variable/value pair may be set at once.
  189.  
  190. unset <variable>
  191.  deassigns a script variable.
  192.  
  193. ?eq <variable> <variable|value>
  194. ?ne <variable> <variable|valu