home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / am_radio / comlink350 / Manual / Script_Man / part5 < prev    next >
Encoding:
Text File  |  1991-12-15  |  15.2 KB  |  449 lines
  1.  
  2. ONERROR:<comment>
  3. -----------------
  4.  
  5. Purpose: Allows a single jump to be made in the script.
  6.  
  7. Use: If a timeout occurs in the program when it is waiting for a certain
  8. character sequence or cannot output any more characters, then when the time
  9. previously specified in the DELAY: command has ellapsed, a timeout will
  10. occur. If no ONERROR: command has been used and a timeout occurs then the
  11. script will finish. If an ONERROR: command has been used, execution of the
  12. next command after the ONERROR will occur, ie a jump will be made.
  13.  
  14. Use of this command can allow a script to exit cleanly, if for instance the
  15. link to the BBS fails, the ONERROR: command can then be followed by script to
  16. disconnect and put the TNC in a defined state.
  17.  
  18. The commands than can cause a timeout error are:-
  19.  
  20.   TYPE: if the serial buffer remains full and does not empty.
  21.   UPLOAD: if the serial buffer remains full and does not empty.
  22.   WAITFOR: if the specified string is not received.
  23.   SCANLIST: if any line takes longer than the delay set.
  24.   READ: if it takes longer than <delay> seconds to read a whole message.
  25.  
  26. Only one ONERROR: command can be used in each script. If more than one is
  27. present, only the last one will be recognised.
  28.  
  29. If there is not a FINISH: command before the ONERROR: command then execution
  30. of the script with no timeout occuring will continue on past it as though it
  31. were not there.
  32.  
  33. Examples: ONERROR: The script will jump to here if a timeout occurs
  34.  
  35. Related commands: TYPE: WAITFOR: SCANLIST: READ: (if a timeout occurs)
  36.  
  37.  
  38. SAVELIST:<comment>
  39. ------------------
  40.  
  41. Purpose: Forces the program to save the message list to a file called "List".
  42.  
  43. Use: Normally placed at the start of the script program but only has an
  44. effect if a SCANLIST command is used. The saved list is put in the ComLink
  45. application's download directory, called "List" or in !ComMail.
  46.  
  47. Examples:  SAVELIST: This command turns on the "save list" feature.
  48.  
  49. Related commands: SCANLIST:
  50.  
  51.  
  52. ENDLIST:<text>
  53. --------------
  54.     ********************  IMPORTANT   ***********************
  55. This command is no longer supported. This command must be deleted from old
  56. scripts along with any WAITFOR: command after a SCANLIST: since the SCANLIST:
  57. command now finishes having seen a prompt.
  58.     *********************************************************
  59.  
  60. BREAK:<comment>
  61. -----------------
  62.  
  63. Purpose: Sends a 50 millisecond "break" to the TNC.
  64.  
  65. Use: Use this command to force the TNC out of transparent mode.
  66.  
  67. Examples: BREAK:
  68.  
  69. Related commands: None
  70.  
  71.  
  72. REPORT:<comment>
  73. ----------------
  74.  
  75. Purpose: Pops up a status window.
  76.  
  77. Use: Useful to force the status window to appear. A status window can be
  78. popped up at any time by using the menu option.
  79.  
  80. Examples: REPORT:
  81.  
  82. Related commands: None
  83.  
  84.  
  85. Command: MONITOR:<text>
  86. -----------------------
  87.  
  88. Purpose: Allows incoming text to be displayed in the bottom of the status
  89. window.
  90.  
  91. Use: The <text> can be ON or OFF. When ON, the status window will be updated
  92. whenever new text arrives at the serial port. When OFF, the incomming text
  93. is not displayed or updated. The comand can be used at any point in the
  94. program, typically during script program testing it would be used at the
  95. beginning of the script. The ON/OFF text must be in upper case.
  96.  
  97. The status window is not popped up automatically by this command, but may
  98. be either manually popped up using the ComLink menu, or, may be popped up
  99. using the REPORT: command.
  100.  
  101. Example: MONITOR:ON
  102.  
  103. Related commands: REPORT:
  104.  
  105.  
  106. Command: DIRUP:<text>
  107. ---------------------
  108.  
  109. Purpose: Sets the upload directory for text files.
  110.  
  111. Use: The command allows the upload directory to be specified. If a script is
  112. run and the command UPLOAD: used, then any files in the specified directory
  113. will be sent to the serial port. If the command is not used in the script
  114. then the default directory used will be For_Upload within the ComLink
  115. application.
  116.  
  117. The directory specified must exist. System variables may be used in <> or {}
  118. brackets.
  119.  
  120. If this command is not used in a script, uploaded files will be taken from
  121. the default directory "For_Upload" in the !ComLink application.
  122.  
  123. The command may be used more then once if files from several directories
  124. are to be sent, in this case, use it before each UPLOAD: command.
  125.  
  126. See the section on ComMail near the end if this manual.
  127.  
  128. Example: DIRUP:RAM:$.ToSend
  129.  
  130. Related commands: UPLOAD:
  131.  
  132.  
  133. Command: DIRDOWN:<text>
  134. ---------------------
  135.  
  136. Purpose: Sets the download directory for recieved text files.
  137.  
  138. Use: The command allows the download directory to be specified. If a script
  139. is run and the commands SCANLIST: or READ: used, then any text received will
  140. be saved in the specified directory. If the command is not used in the
  141. script then the default directory used will be Download within the ComLink
  142. application.
  143.  
  144. The directory specified must exist. System variables may be used in <> or {}
  145. brackets.
  146.  
  147. If this command is not used in a script, downloaded files will be placed in
  148. the default directory "Download" in the !ComLink application.
  149.  
  150. The command may be used more then once if files are to be saved in several
  151. directories, in this case, use it before each SCANLIST: or READ: command.
  152.  
  153. See the section on ComMail near the end if this manual.
  154.  
  155. Example:  SAVELIST:
  156.           DIRDOWN:RAM:$.Lists
  157.           SCANLIST:ARCHIM:G7ALN
  158.           DIRDOWN:adfs::BBS_files.$.ReadFiles
  159.           READ:
  160.  
  161. Related commands: SCANLIST: READ: DIRUP: SAVELIST:
  162.  
  163.  
  164. Command: FILESCAN:<text>
  165. ------------------------
  166.  
  167. Purpose: Scans a specified file for marked message numbers, susequently these
  168. may be read/killed using the READ:/KILL: commands. Also sets a system
  169. variable "OldList$Num".
  170.  
  171. Use: Allows an old  "List" file to be scanned for numbers to be read or
  172. killed. The command causes the file to be examined, if the 6 th character of
  173. any line is a "+", then the five characters before it are assumed to be a
  174. message number. That message number will be read later if the READ: command
  175. is used, the messages that are marked will be saved in the download
  176. directory in a file called "-General-". If the sixth character is a "-"
  177. then that message will be "killed" if the KILL: command is subsequently used.
  178.  
  179. The command also sets a system variable "OldList$Num" which can be used
  180. in the TYPE: command. The number taken is the first one seen in the file.
  181. This is particularly useful for BBSs that need you to specify the last
  182. listed message. Use:-
  183.  
  184. TYPE:L {OldList$Num}
  185.  
  186. The command may be used on its own before READ:/KILL: commands, or before a
  187. SCANLIST: command. If used before a SCANLIST:, both sets of messages will be
  188. read, ie those marked in the FILESCAN: command and those meeting the
  189. criteria specified in the SCANLIST:. Only messages which have been marked
  190. with a "-" will be killed when KILL: is invoked.
  191.  
  192. The <text> in the SCANLIST command should be a valid filepath.
  193.  
  194. An efficient way to use the command is to point to a previously downloaded
  195. list from a BBS/PMS, in which you have marked the messages to be read. The
  196. message list can be marked using !Edit, simply put a + after the message
  197. number. Eg. in the following example list, message 23456 is marked:-
  198.  
  199. MsgNo  TS Size  To      At      From   Date   Subject
  200. 46824+  B$ 443   ARCHIM   GB7BNM  G6DEN  17-Mar ComLink
  201. 46813  BN 926   SATTV   GBR     G8XZD  17-Mar Sendz LNB\Mod for Telecom Band
  202. 46802-  B$ 807   ALL     GBR     G7ALN  17-Mar What is VT220 please.
  203.  
  204. Any text after the 6th character in a line will be ignored, so you don't
  205. need to remove anything from a BBS list. Of course you can always create a
  206. list of messages to be read yourself. Just make sure the 6th character is a
  207. "+". Eg. the file could contain:-
  208.  
  209. 1245 + 
  210. 23   + 
  211.    34- 
  212.  
  213. Note that spaces are ignored.
  214.  
  215. Remember that ComLink can save a message list with filename "List" in the
  216. download directory. I normally rename this file to "List+" and then mark the
  217. messages I want to be read the next time the relevant ComLink script is run.
  218. (Why put a plus on the end? Because the + is right next to the Enter key
  219. on the numeric keypad, so it is convenient!)
  220.  
  221. Once ComLink has performed a FILESCAN: on the specified file, the file is
  222. renamed with a + at the begining, this ensures that if ComLink is run again,
  223. the same messages will not be read!
  224.  
  225.  
  226. Example: FILESCAN:adfs::Disc_1.$.!ComLink.Download.List+
  227.  
  228. System variables may be used as part of the file path and may be enclosed
  229. in <> or {} brackets.
  230.  
  231. eg FILESCAN:{ComLink$Dir}.Download.List+
  232.  
  233.  
  234. OSCLI:<text>
  235. -----------------
  236.  
  237. Purpose: Executes a * command.
  238.  
  239. Use: Allows command line commands to be executed within the script. In one
  240. of the example script programs the command is used to open directory
  241. windows. System variables such as ComLink$Dir may be used BUT MUST be
  242. enclosed in curly brackets, eg {ComLink$Dir}. ComLink will then substitute
  243. the appropriate string before passing to the CLI. I found this was necessary
  244. since some CLI commands dont like system variables in the normal <>
  245. brackets.
  246.  
  247. Example: OSCLI:Filer_OpenDir {ComLink$Dir}.Download
  248.          OSCLI:sound 1 340 200 6
  249.  
  250. Nb. {} BRACKETS MUST BE USED AROUND SYSTEM VARIABLES.
  251.  
  252. Related commands: None
  253.  
  254.  
  255. APPEND:<text>
  256. -----------------
  257.  
  258. Purpose: Adds some text to the end of an upload file.
  259.  
  260. Use: The <text> will be sent at the end of each upload file. The upload file
  261. must NOT contain the end of message code, eg /ex or CTRL/Z, these MUST be
  262. put at the end of the APPEND: command.
  263.  
  264.  
  265. Note the /ex must be sent as a separate line, hence the carraige return
  266. codes [13] in the example below.
  267.  
  268. System variables may be added to date the file etc, they must be put in {}
  269. brackets as shown in the example.
  270.  
  271. More than one APPEND: command can be used, the text strings will all be
  272. "added" to form one string. This gets around the limitation that the
  273. script command lines must be less than 100 characters long.
  274.  
  275. The total length of the appended string must not be more than 255 characters
  276. after system variables have been expanded.
  277.  
  278. Examples:
  279.  
  280. APPEND:73 de Alan (G7ALN @ GB7IMB)
  281. APPEND:    *** Sent  on {sys$date} {sys$year} at {sys$time} ***[13]/ex[13]
  282.  
  283.  
  284. Related commands: UPLOAD:
  285.  
  286.  
  287. KILL:<text>
  288. -----------------
  289.  
  290. Purpose: Kills messages.
  291.  
  292. Use: Messages in a list can be marked with a "-" and a FILESCAN: performed.
  293. If a KILL: command is used later, then the marked messages will be deleted.
  294. The <text> must be the BBS or PMS kill command, for a PMS it is usually
  295. "Kill" but for a BBS "K".
  296.  
  297. Note: On a BBS it is best to kill "read" messages to you, using the "KM" BBS
  298.       command. eg.
  299.  
  300.       TYPE:KM
  301.       WAITFOR:Alan >[13]
  302.  
  303. *** IMPORTANT *** If both FILESCAN: and SCANLIST: commands are used in a
  304. script, the FILESCAN: must come first.
  305.  
  306.  
  307. Examples:  KILL:Kill
  308.            KILL:K
  309.  
  310. Related commands: FILESCAN:
  311.  
  312.  
  313. DAYTIME:<text>
  314. -------------
  315.  
  316. Purpose: Sets the TNC clock.
  317.  
  318. Use: The <text> must be either 10 or 12. The number sets the length of
  319. the time command string to be sent to the TNC. If it is 10 then the string
  320. sent will be of the form:-
  321.  
  322. DA yymmddhhmm
  323.  
  324. Where yy=year, mm=month, dd=day, hh=hour and mm=minutes
  325.  
  326. If the number is 12 then the string sent to the TNC will also include
  327. seconds:-
  328.  
  329. DA yymmddhhmmss
  330.  
  331. Use the number that is appropriate to you TNC. Of course the TNC must be
  332. in command mode to accept the time, so position the command appropriately!
  333.  
  334. Example:  DAYTIME:10
  335.  
  336. Related commands: None
  337.  
  338. FLUSH:<text>
  339. ------------
  340.  
  341. Purpose: Allows the serial input buffer to be flushed.
  342.  
  343. Use: This command is handy if you are not interested in what is coming from
  344. your TNC. When ON the command causes the input buffer to be repeatedly
  345. flushed during the execution of the script, this ensures the input buffer
  346. in the archimedes does not become full and stop the TNC operating.
  347.  
  348. In general this command is only useful when ComLink is conversing directly
  349. with the TNC, ie when no connection has been made. The command has a built
  350. in side effect, a delay is introduced before each line of text is sent to
  351. the TNC. I found that this was neccessary as it is possible to "overload"
  352. my TNC with commands otherwise, and it just "freezes" on me.
  353.  
  354. A typical use would be when you are setting lots of TNC options and don't
  355. want to wait for the "cmd:" prompt after every one.
  356.  
  357. The text must be "ON" or "OFF". You must be careful with this command and
  358. remember to switch it OFF before the script needs input again.
  359.  
  360. Example:
  361.  
  362. FLUSH:ON
  363. TYPE:CONMODE CONV
  364.       ....
  365.       ....
  366. TYPE:ECHO OFF
  367. FLUSH:OFF
  368.  
  369. Related commands: None
  370.  
  371. TRYAFTER:<number> LOOPIF:<text> and UNTIL:<text>
  372. ------------------------------------------------
  373.  
  374. Purpose: Allows loops conditional on the text received.
  375.  
  376. Use: Typically used to check if the BBS is busy and try again later if it
  377. is. These commands to setup a conditional loop.
  378.  
  379. The LOOPIF: command specifies the text which will cause a loop back from the
  380. UNTIL: command. A pause equal to the TRYAFTER: value will be made on each
  381. loop back. The text specified in the UNTIL: command, when seen will allow
  382. the script to continue with the following command. No delay is made on the
  383. first pass through the loop, only when a loopback is made.
  384.  
  385. Choose the text by looking at the BBS output when it is busy. GB7IMB sends
  386. *** IMBBBS busy
  387. so I can specify all or part of this in the LOOPIF: command. When a
  388. successful connection is made I get back the prompt, so I can use
  389. Alan > as the text in the UNTIL: command. Wildcards are NOT allowed!
  390.  
  391. In the example below the TRYAFTER: command defines a 360 second (6 minute)
  392. pause on loop back. A connection to the BBS will be attempted and the
  393. text "Alan >" OR "busy" waited for. If "Alan >" is received the script will
  394. continue with TYPE:L but if "busy" is seen then the next script command
  395. executed will be LOOPIF: again and a pause of 6 minutes made.
  396.  
  397. The last used DELAY: command sets the timeout limit to see one of the text
  398. strings (in the example "busy" or "Alan >") while the UNTIL: command is
  399. executing.
  400.  
  401. There is no limit to the number of loop backs! More than one loop can
  402. be setup in the script but you can't have nested loops.
  403.  
  404. Examples: TRYAFTER:360
  405.           LOOPIF:busy
  406.           TYPE:C IMBBBS
  407.           UNTIL:Alan >
  408.           TYPE:L
  409.  
  410. Related commands: DELAY:
  411.  
  412.  
  413.  
  414.  
  415. !ComMail for setting the upload and download directory paths.
  416. ------------------------------------------------------------
  417.  
  418. !ComMail provides an easy way of setting your upload and download paths.
  419.  
  420. A !ComMail directory has been added which allows the path of upload and
  421. download to be set easily. Simply put the !ComMail directory where you like
  422. on floppy, in RAM drive etc. Double click on the !ComMail directory to be
  423. used for upload and download. A system variable ComMail$Dir will be set to
  424. point to the selected directory. This can be used in your scripts, eg :-
  425.  
  426. DIRDOWN:{ComMail$Dir}.From_BBS
  427. DIRUP:{ComMail$Dir}.To_BBS
  428. OSCLI:Filer_OpenDir {ComMail$Dir}.From_BBS
  429.  
  430. You can create your own directories within !ComMail, put them in the
  431. !ComMail.Mail directory. Double clicking on the !ComMail icon automatically
  432. opens this directory for you.
  433.  
  434.  
  435. PROBLEMS?
  436. =========
  437.  
  438. I hope you have the time to write a script file or to adapt one I have
  439. provided. The time you save by not having to sit at the keyboard to get
  440. messages from the BBS is time you can use more usefully. (If you are married
  441. perhaps your wife will see more of you!)
  442.  
  443. The programs supplied are not guaranteed to be free of bugs. The usual
  444. disclaimers apply, don't blame me if use of the programs causes loss of any
  445. data or any other type of damage!
  446.  
  447. Do contact me via packet if you have any problems or have any suggestions
  448. regarding possible improvements. I'll try to help.
  449.