Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 211 bbs May contain a shell escape command to activate a Bulletin Board program via a DOS Gateway. The bbs string parameter is always processed as a shell escape command, and should not include a leading "!". For security reasons, it should specify an absolute pathname. EXAMPLE: set bbs "~bbsprog" blankfill When transmitting a file with the term function with p, r, or w modes, ZCOMM sends the contents of blankfill (if set) to prevent the remote from receiving a blank (empty) line. (Some programs interpret a blank line as an exit from text entry.) ZCOMM Character Escapes must be used to represent control characters. If blankfill is empty, nothing is sent. The call command resets blankfill to empty. break Stores a string or command to be executed by the Ctrl-Break key instead of the default 100 ms break. EXAMPLE: Some Novation modems cannot pass a break signal: set break "@break putw %B\336\ 1\r putw %U\336\ 0\r" Causes the break key to send a break to get the modem's attention, then tells the modem to send the break itself, and finally restores the modem's ersatz "transparent" mode. SEE ALSO: break command bs Stores an alternate string or command to be executed by the backspace key when in the term function. c When the h or s string parameters is accessed, the hundredths of a second are stored in the c string parameter. The accuracy and precision of this quantity depend on the operating environment. call1 ** Sets the string to be sent to the modem or command to be executed before each time ZCOMM scans for outgoing message control scripts. Typically this would consist of a modem command disabling autoanswer, to allow outgoing calls. This string is not used if callpath is empty. EXAMPLE: set call1 "ATMS0=0\r" (Hayes Modem) call2 Sets the string to be sent to the modem or command to be executed each time ZCOMM begins to wait for a call in Host State. Typically this would command the modem to enable autoanswer for (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 212 incoming calls. EXAMPLE: set call2 "ATMS0=1\r" (Hayes Modem) call3 * Sets the string to be sent to the modem or command to be executed each time ZCOMM begins waiting for incoming calls. Typically this would consist of a lput command to display an informational message on the local screen. Note that such a message will remain on the screen for long periods of time, possibly creating an afterimage on the CRT display. EXAMPLE: set call3 @lput "\n\nAwaiting Incoming Call. Press F1 to exit.\n" callers A pathname in which a log of successful host state logins is kept. If callers is null (the default), no log is kept. calllog * The filename that contains the log of successful autodialed calls. If empty (the default), this function is disabled. A typical entry with 6.3 minutes connect time with a system called cis02 is shown. C 2143:22 01-25-84 1200 c:226-0627 63 cis02 callpath ** Sets the ambiguous pathname that scans for scripts to transmit outgoing messages. If empty (the default), no scans are made. EXAMPLE: set callpath "/tmp/outmsg.*" NOTE: The "disks" string parameter must be set to include any drive specified in "callpath". SEE ALSO: call1, call2 string parameters challenge is executed when the caller connects and handshakes to determine transmission speed. This script runs without restriction, and should check for carrier after each reading of data. EXAMPLE: set challenge "@gosub .%lib/challeng.t" d Is set to the date when called, in the form "mmdd". EXAMPLE: t cia%d.TXT If the date is December 7, ZCOMM enters the term function with capture to KGB1207.txt EXAMPLE: create -st+ cbbs%d.tmp (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 213 SEE ALSO: h, t string parameters drive Is set to the current default disk drive letter when ZCOMM starts and when logging into a new disk drive with an A: command. nodename, altprompt, mprompt, hprompt string parameters dircx dirpx dirfx dirrx dirsx String parameters for default/override directories. Their uses are described in Chapter 16. disks Contains the disks that may be logged into with with the d: command where "d" is the drive letter, or that may appear as part of a pathname. If empty (the default), drive letters are not checked. This parameter should be set to prevent local or remote users from hanging the system by accessing an off-line disk drive. This string must be entered in lower case. EXAMPLE: set disks "abc" SEE ALSO: home, rdisks string parameters dport Contains the name of the active communications port, otherwise empty. SEE ALSO: port command drive Contains the drive letter of the current default DOS disk drive. emdir A directory pathname for incoming electronic mail files. emdir affects twxfile unless twxfile is an absolute path. emdir is also used for incoming electronic mail using the YMODEM Batch protocol in the absence of a login. EXAMPLE: set emdir "/memo" entstr If entstr is set, ZCOMM sends the contents of entstr when ENTER (carriage return key) is keyboarded in the term function, unless n mode is in effect. ZCOMM Character Escapes must be used to represent control characters. If entstr is empty, a carriage return is sent. The "call" command resets entstr to empty. EXAMPLE: set entstr "\3" (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 214 sends an ETX (octal 3) when Enter is keyboarded. This is handy for some computer systems that expect keyboarded lines to be terminated with something other than the usual carriage return. NOTE: The characters in entstr are always sent at full speed. SEE ALSO: eolstr string parameter eolstr When transmitting a file with the term function with p, r, or w modes, ZCOMM sends the contents of eolstr (if set) to terminate the line. ZCOMM Character Escapes must be used to represent control characters. If eolstr is empty, a carriage return is sent. The "call" command resets eolstr to empty. EXAMPLE: set eolstr "\r." sends a carriage return followed by a period at the end of each line read from the transmit file. NOTE: The characters in eolstr are always sent at full speed. SEE ALSO: entstr, blankfill string parameters esc Stores an alternate string or command to be executed by the ESC key when in term function. etx Stores an alternate string or command to be executed by ETX (Ctrl-C) when in the term function. exrc Is sent to the modem/executed when an interactive Host Operation session logs out. EXAMPLE: set exrc "@handshake off; set disks c" turns off flow control handshaking and resets the disks parameter in case privileged (unrestricted) callers modify this parameter. h is set to the hour of the day in the form hhmm. EXAMPLE: echo "It is now %h Hours" displays: It is now 1930 Hours. SEE ALSO: hh, mm, d, t string parameters helpfile The pathname that contains the online help file. You may wish to set this in the phone directory "setup" entry. Iff helpfile begins with the character @, the rest of helpfile is treated as a Zcomm command. SEE ALSO: xhelpfile string parameters, help command, T test condition (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 215 hh is set to the hour of the day in the form hh. EXAMPLE: echo "It is now hour %h." displays: It is now hour 09. SEE ALSO: h, mm, d, t string parameters home When ZCOMM is invoked, home is set to the current directory. When the "cd" command is given without an argument, the directory is changed to the contents of home. When ZCOMM is Restricted, absolute pathnames (those beginning with \ or /) must have home as a prefix. This restricts unprivileged users to the directory given in home and/or its subdirectories on any of the disks allowed by the disks string parameter. When changing the value of home, use slashes (/) and not backslases (\), and do not use a disk identifier. SEE ALSO: disks string parameter hprompt Overrides the default host operation command prompt. SEE ALSO: altprompt, mprompt, nodename, drive, pwd string parameters id0-id3 General purpose string parameters that may be used to hold ID strings (user account numbers) for script login applications. ifs The "Internal Field Separator" string contains the default characters to be used by the split command to parse a string into fields. item * When the expand command is executing a script, the item string parameter is set to the pathname of the matched file. intolink * A command that is executed or a string sent to the modem when ZCOMM enters the link command. EXAMPLE: set intolink "\r" sends CR to the linked computer. EXAMPLE: set intolink "@portx 0f8,2" selects a nonstandard link port. SEE ALSO: linkpass, outalink string parameters kermreset A string (up to 32 characters) may be sent by Pro-YAM's Kermit when it attempts to recover from a transmission error. The default value for this string is empty. Two metacharacters are special: \336 inserts a one second pause, \335 sends a break. (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 216 l l (letter l) indicates selection of a long distance carrier for calls to other area codes. It is set to "1" as a default. l may be set to the access code of the particular alternate long distance service desired with a "set" command. SEE ALSO: m string parameter lib A string variable which may be used to indicate the directory containing scripts. linkpass * If set, callers must enter this password when accessing the link command. lpnono Do not send any of the characters in lpnono to the printer. lpnono may use ZCOMM Character Escapes to represent control characters. EXAMPLE: set lpnono "\023" prevents the printer from receiving the DC3 (XOFF) character that places some printers off line. EXAMPLE: set lpnono "\7" prevents the printing of bell characters. SEE ALSO: l mode m m is used to indicate selection of a long distance carrier for calls within the same area code. It is set to "1" as a default. m may be set to the access code of the particular alternate long distance service desired with a "set" command. It is separate from the l string parameter because the default "1" prefix may not work if the area code is given, but some alternative long distance services require the area code to be specified for calls within the same area code. SEE ALSO: l string parameter mcommand A command that is executed instead of ZCOMM's built in dialing routine. This may be either "gosub dial" which would access the "dial" entry in the phones file, or "source /dial" which would access the script from a separate file. The second method allows a separate "dial" file for each machine, but requires one more file to be kept track of. Note that mcommand does not start with an @. The default value is empty, disabling this function. EXAMPLE: set mcommand "gosub dial" (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 217 SEE ALSO: telno string parameter mconnect A command that is executed or string that is sent to the modem when the modem makes a connection. A typical use is to set transparent mode for some Novation modems. The default value is empty, disabling this function. menu The filename that contains the script accessed by the menu command. EXAMPLE: set menu /host/menu.hst messages Messages entered with the message command are appended to this pathname. By convention, this file should be readable when ZCOMM is running in Restricted host mode. EXAMPLE: set messages "/host/messages" mprefix A command that is executed or a string that is sent to the modem as a prefix to dialing a number. The default ATD works with the Hayes Smartmodem(TM) 1200. ATDT instructs the modem to use DTMF (Touch Tone(TM)) dialing instead of pulse dialing. Character escapes may be used. mm is set to the minute of the hour. It expands to the form mm. EXAMPLE: echo "It is now %h minutes past the hour" displays: It is now 30 minutes past the hour. SEE ALSO: h, hh, d, t string parameters mprompt Overrides the default main command prompt. EXAMPLE: set mprompt "\r\E[1m%drive:\L%pwd <<<\E[m " Display the current disk drive (%c) and directory (%pwd) highlighted (\E[1m) and in lower case (\L). N.B.: If you access Unix systems with ZCOMM, choose an mprompt string that is distinct from your Unix prompt. EXAMPLE: set mprompt "\r\E[1m%nodename:%drive:\L%pwd <<<\E[m " SEE ALSO: altprompt, hprompt, nodename, drive, pwd string parameters msuffix A command that is executed or a string sent to the modem after the last digit in the phone number. Most intelligent modems (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 218 require the default value of "\r". n0-n9 General purpose string parameters. nodename Contains the node name given to individual Unix and Xenix systems. On other systems this must be set by a script. SEE ALSO: Unix uname command oname1...oname5 contains the information stored by the args string parameter for each level. oncloserx Optional user exit commands to execute after each file is received with a protocol file transfer.* Its use is described in Chapter 13. onclosetx Optional user exit commands to execute after each file is sent with a protocol file transfer.* Its use is described in Chapter 13. onexit Optional commands to execute as ZCOMM exits to the operating system. EXAMPLE: set onexit "@echo GOODBYE!!" outahost A command that is executed or a string sent to the modem when ZCOMM exits host operation with a F1 or ALT-N key. EXAMPLE: set outahost ATZ\r sends the ATZ command to a Hayes modem to restore its default no autoanswer state. outalink * A command that is executed or a string sent to the modem when ZCOMM exits the link command. EXAMPLE: set outalink "@kill; px0" clears the circular buffer and prevents restricted callers from accessing the link command. SEE ALSO: intolink string parameter parity Contains a string representation of the number of data bits and parity, such as 8n. password Changes the password callers must enter to gain access to your computer when ZCOMM is in host operation. If password is empty no password will be demanded. EXAMPLE: set password "Change This Already" (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 219 SEE ALSO: challeng.t script, demand command phones The filename that contains the telephone directory entries and associated commands used with the call and gosub commands. The default is "/PHODIR.t". The default may be changed at installation time by the putsnp program. The DOS environment variable PHONES will override the default when ZCOMM is started. Finally, a set command may be used to change the telephone directory once ZCOMM has started. picture The filename used by the ALT-Z command to "zap" a copy of the display memory to the specified file. plog The filename that contains the file transfer performance log. If empty (the default), this function is disabled. private Pathname that messages are stored into by the private command. This file should NOT be readable when ZCOMM is running in Restricted host mode. EXAMPLE: set private "/private" pw0-pw3 General purpose string parameters for holding passwords. If defined with a set _pw0 "secretpw" command, it will be cleared with the next call command. pwd This parameter is set to the current working directory by each cd and pwd command. quitcmd Sets the string to be sent to the modem or command to be executed when a protocol file transfer has been completed if the ALT-Q key was typed during that transfer. EXAMPLE: set quitcmd t\r\336\r\336\r\025off\r would send t, a pause, , a pause, , and ^Uoff. This sequence may be useful for automatically logging off Compuserve after downloading a file. SEE ALSO: ALT-Q special key rcmdlog * The filename that contains the log of commands issued remotely (in Host Operation) along with the time, transmission speed, and the name of the caller. If set to "prn", the commands are logged on the printer. A highly buffered printer, hard disk file or ramdisk file is recommended because this file will be opened and closed for each host command. If empty (the default), this function is disabled. EXAMPLE: set rcmdlog D:rcmds (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 220 rdisks Contains the disks that may be logged into with with the d: command where "d" is the drive letter, or that may appear as part of a pathname, when ZCOMM is Restricted. If empty (the default), drive letters are not checked against this parameter. (Drive letters are always checked with the disks parameter.) The rdisks parameter is used to prevent restricted remote users from accessing private data files. This string must be entered in lower case. EXAMPLE: set rdisks "c" SEE ALSO: home, disks string parameters remote ZCOMM reads The full name of the remote system from the telephone directory entry when the call command is given. EXAMPLE: call omen using the omen entry in the distributed PHODIR.t file assigns omen-tech to the remote string parameter. In Host Operation, the caller's name is read into remote. SEE ALSO: call command, xpassword string parameter, \PXXXX character escape rmtcheck Sets the string to be sent to the modem or command to be executed each time ZCOMM accepts a command line or ZMODEM protocol Command Download from the remote caller when in Host Operation, before that command is executed. SEE ALSO: rmtcmd, pwd string parameters EXAMPLE: set rmtcheck "@source D:remcheck.t" rmtcmd Contains the command line entered by the caller or received by ZMODEM protocol Command Download in Host Operation. This may be modified by an unrestricted script invoked via the rmtcheck string parameter. SEE ALSO: rmtcheck string parameter, checkrmt.t script rname * Contains the name of the last file received by a protocol, successful or not. rub Assigns a string or command to the RUBOUT (Shift Backspace) key. rxcnt A three digit number which counts the number of files that have been created for receiving. An incoming file with an illegal name is changed to rename.n with n is incremented from the value stored in rxcnt (or 0). (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 221 rxlog * The filename that contains the log of received files. If empty (the default), this function is disabled. s * Contains the current time in seconds since the last minute. s0...s9 These may be tested with the if %sN and if i%sN,string commands, or expanded into a string using character escapes with the "%sN" construction, where N is 1...9. Use set param "" (empty string enclosed by double quote characters) to set a string parameter to empty. speed String representation of the serial port speed. statliner May be used to place a messgae in the right side of the term function status line, replacing the information normally displayed there. If statliner begins with a space, it is placed at the far right of the status line, after the information normally displayed. If statliner does not begin with a space, it is processed for string substitution and character escapes, and then placed at column 31 of the status line. Soft Keys The f1 to fa12 strings are executed by the respective keys from the term function, review function, or command prompt. In the term function, soft keys definitions for fins, fdel, fhome, fup, fdown, fpgup, fpgdn, fleft, fright, fend will override ZCOMM's built-in definitions for these keys. The built-in definitions take precedence in the review function, conference command, and at the command prompt. Computers with the 101 key extended keyboard and ROM BIOS support allow ZCOMM to distinguish the cursor cluster keys and the two new function keys labelled F11 and F12. Extended keyboard cursor cluster keys may be reassigned with the fcdel, fcdown, fcend, fchome, fcins, fcleft, fcpgdn, fcpgup, fcright, and fcup string parameters. The fnp5 key may be assigned to the "5" key on the numeric pad.[2] ZCOMM's character escapes can be used to encode special characters, including spaces and/or tabs. EXAMPLE: set bs "\177"; set rubout "\b" Swap backspace and rubout for VMS The contents of these keys may be displayed by ALT-K or by the keys command. __________ 2. Visible on extended 101 key keyboards with extended BIOS support only (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 222 If the assigned string begins with "@" (commercial at), the string is executed as a command. A soft key command called from the term function should not end with a t or f command because this would cause excessive recursion (calling the term function from within the term function). (Use the create or open instead.) In the conference command, soft keys are inserted into the editing window unless they are commands, which are executed. Soft keys are not executed from review or the command prompt unless they are commands (beginning with "@"). EXAMPLE: set f3 @rb Assigns the rb command to F3. t expands to the current time and date each time it is used. SEE ALSO: d, h string parameters tab Assigns a string or command to the TAB key. telno The current telephone number string. SEE ALSO: mcommand string parameter tmodes Contains optional term function modes to be applied to each instance of the following term function commands: conference, create, f, learn, t and F-2 SEE ALSO: term funcion modes, Chapter 21. tmp A string variable which may be used to indicate the directory used for data to be transmitted or received. tname * Contains the name of the last file sent with a protocol, successful or not. txlog * The filename that contains the log of transmitted files. If empty (the default), this function is disabled. unrestrict Changes the password callers must match to allow remote functions that are normally restricted such as erasing files, listing and changing parameters, and changing to private directories. If unrestrict is empty (the default), the unrestrict command will fail. SEE ALSO: unrestrict command w Contains the day of the week (local time) as Mon, Tue, Wed, Thu, Fri, Sat, or Sun. (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 223 welcome is executed after the password (if any) has been demanded and accepted. EXAMPLE: set welcome "@type welcome.txt; purgek; nulls 0" xhelpfile The pathname that contains the online help file for host mode commands. This should be readable when ZCOMM is in Restricted Host Operation. Iff xhelpfile begins with the character @, the rest of xhelpfile is treated as a Zcomm command. SEE ALSO: helpfile string parameters, help command xpassword * xpassword is a master password string that may be used to generate a unique password for each system called. xpassword is encrypted by the name of the remote system (string parameter remote) to generate a password unique to each remote system called. The generated password is transmitted as a result of a Soft Key programmed with the \PXXXX construction described in Chapter 26. To view the generated password, set the remote string parameter to the full remote system name as it appears in the appropriate telephone directory (up to but not including any "-" character), then keyboard lput \PXXXX from the main command prompt. EXAMPLE: set f8 "\PXXXX" Programs F8 to transmit a 5 character password from the term function. Omen Technology Inc cannot accept responsibility for damages due to the breaking of any codes used or generated by ZCOMM. uucplock Contains an optional UUCP lock file prefix for arbitrating tty ports with the Unix UUCP program. This is normally set automatically, or from the UUCPLOCK environment variable. EXAMPLE: set uucplock "/usr/spool/locks/LCK.." Ee y* All variable names beginning with "y" are reserved! y0...y127 Read only string parameters y0 to y127 expand to represent lines displayed by the term function. y0 corresponds to the current partially finished line as displayed by the term function. The last line referenced by y0...y127 becomes the y string parameter current line used by the y, yb, and yf string paramrters. Each time the term function displays a newline from the remote, the y parameter is set to the new, unfinished line from the remote. y expands to represent the y parameter current line. yb Referencing the yb read only string parameter backs up the y string parameter current line one line, and then represents that (C) 1990 Omen Tech Inc Chapter 25 String Parameters Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 224 line. yf Referencing the yb read only string parameter advances the y string parameter current line one line, and then represents that line. SEE ALSO: H, h test conditions zmrxesc Requests the sending ZMODEM-90(TM) program[3] to escape the specified additional control character(s). Printing characters @ (40 hex) to _ (57 hex) escape the corresponding control characters NULL (0) to US (1F) in both parities. EXAMPLE: set zmrxesc "@" Requests the sending program to escape NULL (0) and NULL with 8th bit set (80 hex). SEE ALSO: zmtxesc string parameter zmtxesc Causes ZMODEM send commands to escape the specified additional control character(s). Printing characters @ (40 hex) to _ (57 hex) escape the corresponding control characters NULL (0) to US (1F) in both parities. SEE ALSO: zmrxesc string parameter __________ 3. DSZ.COM does not support the zmrxesc string parameter. (C) 1990 Omen Tech Inc Chapter 25 Character Escapes Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 225 26. CHARACTER ESCAPES Some commands use strings with character escapes similar to those used by the C programming language for describing string constants. When translating a string for character escapes, ZCOMM substitutes strings (%svar) and then translates the result for backslash (\) encoded character escapes. String-Parameter %svar Environment-Param %SVAR % (per cent) \045 password* \PXXXXXXX cleartext* \C+clear-text+ ciphertext* \M+ciphertext+ newline (LF) \n return (CR) \r tab (HT) \t alarm (BEL) \a backspace (BS) \b form feed (FF) \f escape (ESC) \E transparent \T lowercase \L uppercase \U octal byte \nnn decimal byte \dnnn hex byte \xHH control char \^C concatenation \& backslash \\ To preserve compatibility with future TurboDial enhancements, a backslash should not be followed by a character not listed above. %svar is replaced by the value of the corresponding string parameter. The string parameter name must be written exactly, in the correct case, with no extra letters or digits at the end. Any non alphanumeric character delimits the parameter name. The DOS environment is searched for parameters after exhausting the ZCOMM string parameters.[1] \PXXXXXXX uses the xpassword and remote string parameters to generate a password unique to each remote system, replacing each X character with an upper case alphabetic character.* The xpassword parameter must have at least as many characters as the number of characters used in __________ 1. DOS environment parameters are upper case only (C) 1990 Omen Tech Inc Chapter 26 Character Escapes Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 226 the \PXXXXX construction. SEE ALSO: xpassword, remote string parameters \M+ciphertext+ uses a cipher and the contents of the mpassword string parameter to decrypt and transmit the cleartext equivalent to ciphertext. Ciphertext is delimited by the character immediately following "M". \C+cleartext+ is treated as above, except for no decryption. EXAMPLE: \C+foobar+ is translated to foobar by ZCOMM's character escape expansion. A separate program pga encrypts instances of \C+cleartext+ into \M+ciphertext+ according to a user specified master password. Pga also decrypts \M sequences to either cleartext, or encrypts them with a new master password. Please refer to Chapter 99. The \n, \r, \t, \b, \f, \E, \nnn, \xHH, \^C and \\ character escapes generate the associated character. The \T character escape inhibits the processing of character eascpes (but not string substitutions) in the remainder of the string. It is useful when the raw string contains backslashes which must not be treated as character escapes. The \L character escape forces the rest of the string to lower case, up to the next \ character. Likewise, \U forces upper case. Octal byte escapes (\nnn) accept 1 to 3 octal digits terminated by the first non octal digit. Decimal byte escapes (\dnnn) accept 1 to 3 digits terminated by the first non digit. Hex byte escapes (\xHH) accept exactly 2 hex digits. Control characters may also be represented by \^C where C is the printing representation for Ctrl-C and ^ is the circumflex character. The \& character escape generates nothing; it is useful to delimit the lexical end of a string parameter name in string concatenation applications. 26.1 Concatenating String Parameters To concatenate the contents of a string parameter with other characters, one must escape the next character with a backslash if it is a letter or digit. The \& character escape expands to nothing. EXAMPLE: Assume string parameter s1 contains "foo". putw "%s1\&bar" (C) 1990 Omen Tech Inc Chapter 26 Character Escapes Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 227 sends "foobar". putw "%s1\142ar" sends "foobar". putw "%s1-skidoo" sends "foo-skidoo". putw "%s1bar" is undefined. putw "%s1\bar" sends "fooar" Failure to observe this property causes the sets and put commands to give unexpected results. An encrypted password* is generated from the prototype string \PXXXXXXXX where each X generates an upper case alphabetic character by encrypting the leading letters of the remote system name by xpassword. Only the leading letters of the remote system name are used to allow a directory to have a number of alternate access methods for a given system, yet produce the same automatic password. For example, "source", "source-telenet", "source300" would all generate the same password, but "sourceb" would generate a different password. xpassword must have at least as many characters as X characters in the prototype string. Omen Technology Inc and sellers of ZCOMM cannot accept any responsibility for damages due to the breaking of any ciphers used or generated by ZCOMM. An arbitrary byte is generated by backslash followed by one to three octal digits, backslash x followed by exactly two hex digits, or by backslash circumflex followed by three decimal digits. 7 bit transmission modes (7s, 7m, 7e, 7o) modify the parity bit of characters transmitted by the term function during the put[w] command. 26.2 Quoting Strings Strings must be enclosed by double quotes (Shift ' on the IBM Personal Computer) to allow white space and/or semicolon to be included in the string. If a string containing white space were not quoted, it would be terminated by the first space or tab, and ZCOMM would consider the rest of the intended string as another (incorrect) command. 26.3 Layering of Escaped Characters Sometimes a string will be processed two (or more) times by ZCOMM's character escapes. set fs2 "@accept s1 Name:; obey find\ \\n%s1\ %phones" (C) 1990 Omen Tech Inc Chapter 26 Quoting Strings Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 228 This example causes ZCOMM to ask for a name when Shift-F2 is typed. The name is read into string parameter S1, which is then used as part of the argument for the find command. The find command searches the telephone directory for lines beginning with the string you just typed in. To match only lines starting with the given string, a linefeed (\n) is prepended to the argument of the find command. When the obey command executes, the backslash-space sequences translate to spaces, and the double backslash translates to a single backslash. The space after "find" and after "%s1" must be escaped because the obey command accepts a single string argument. If these spaces were not escaped, the obey command would not "see" the rest of the line after "find". The find command performs its own character escape translation, changing the \n to a linefeed character. Since the find command performs string substitution on its list of files, it is not actually necesary to use the obey command here: set fs2 "@accept s1 Name:; find \n%s1 %phones" 26.4 Regular Expressions Regular Expressions allow TurboDialTm scripts to search and parse data from files, the keyboard, and remote computers. Regular expressions are used for string searching and parsing (splitting) with the ss and egrep commands, and the h and H test conditions. Many DOS and Unix programs use regular expressions to search and parse text, including grep, egrep, many flavors of EMACS, Brief, Epsilon, ed, vi, sed, lex, and Perl. The effort expended in learning how to use regular expressions will be rewarded by the increased utility of dozens of programs and tools, not just ZCOMM. ZCOMM regular expressions give "magic" meanings to the characters \ * + ? . | ^ [ ] ( ) A regular expression is zero or more branches, separated by |. It matches anything that matches one of the branches. A branch is zero or more pieces, concatenated. It matches a match for the first, if it is followed by a match for the second, etc. A piece is an atom possibly followed by *,+, or?. An atom followed by * matches a sequence of 0 or more matches of the atom. An atom followed by + matches a sequence of 1 or more matches of the atom. An atom followed by ? matches a match of the atom, or the null string. An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), . (matching any single (C) 1990 Omen Tech Inc Chapter 26 Regular Expressions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 229 character), ^ (matching the null string at the beginning of the input string), $ (matching the null string at the end of the input string), a \ followed by a single character (matching that character), or a single character with no other significance (matching that character). A range is a sequence of characters enclosed in []. It normally matches any single character from the sequence. If the sequence begins with ^, it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by -, this is shorthand for the full list of ASCII characters between them (e.g. [0-9] matches any decimal digit). To include a literal ] in the sequence, make it the first character (following a possible ^). To include a literal -, make it the first or last character. EXAMPLE: One can match separators (space, tabs, punctuation) by excluding them from a range [^0-9A-Za-z] That means "match anything except A to Z, or a to z, or 0 to 9.[2] If a regular expression could match two different parts of the input string, it will match the one which begins earliest. If both begin in the same place but match different lengths, or match the same length in different ways, life gets messier, as follows. In general, the possibilities in a list of branches are considered in left-to-right order, the possibilities for *, +, and ? are considered longest-first, nested constructs are considered from the outermost in, and concatenated constructs are considered leftmost-first. The match that will be chosen is the one that uses the earliest possibility in the first choice that has to be made. If there is more than one choice, the next will be made in the same manner (earliest possibility) subject to the decision on the first choice. And so forth. For example, `(ab|a)b*c' could match `abc' in one of two ways. The first choice is between `ab' and `a'; since `ab' is earlier, and does lead to a successful overall match, it is chosen. Since the `b' is already spoken for, the `b*' must match its last possibility-the empty string-since it must respect the earlier choice. In the particular case where no `|'s are present and there is only one *, +, or ?, the net effect is that the longest possible match will be __________ 2. Ranges in regular expressions are in ASCII collating order. For example, the range [A-z] matches all the letters in either case, PLUS all the funny characters between Z and a in the ASCII code chart. (C) 1990 Omen Tech Inc Chapter 26 Regular Expressions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 230 chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x', due to the begins-earliest rule. (In effect, the decision on where to start the match is the first choice to be made, hence subsequent choices must respect it even if this leads them to less- preferred alternatives.) Case is significant in regular expressions. Ranges may be used to match characters in either case. The regular expression [aA]ny matches "any" or "Any". The regular expression subroutines and much of this description were written at the University of Toronto. EXAMPLE: If s0 contains 1234567890 Hello There then the command ss s0 "(12.*0 ).*The(..)" results in z1='1234567890 ' z2='re' String parameter z0 contains the entire matched string, and may be used for testing the success of the match with an if %z0 goto foundit command. EXAMPLE: string = 'Here are 345 dots' ss string "([0-9]+)" z0= '345' EXAMPLE: Sometimes one needs to shorten a string which is too long. The following loops while the length of subject is greater then 24. One character is chopped off the end of the string each time the ss command is executed. The parentheses contain the portion of the string that should be retained. while %sbj>24 ss sbj "(.*)[A-z]" sets sbj "%z1" An alternative: if %sbj>24 ss sbj "........................."; sets sbj "%z1" 26.4.1 Sample Script - Browse/Download The kcisdl.t script downloads a file after it has been listed by the Compuserve Special Interest Group DownLoad "bro" command. The kcisdl.t script should be bound to F3 with (C) 1990 Omen Tech Inc Chapter 26 Regular Expressions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 231 set f3 "@source kcisdl.t" The Compuserve "browse" command displays file information and then invites the user to download it: [73125,617] P3YAM.ARC/binary 09-Jul-87 3224 Accesses: 13 Keywords: YAM PRO-YAM ZCOMM YAMDEMO Sample YAMscript, for handling messages and file up/downloads with the popular PCBoard bulletin board systems. Disposition ! Keyboarding F3 activates the script to scan the circular buffer for the file name and download the file. if !h^\[ echo "Can't find Account Number"; return The h test condition searches backwards through the circular buffer for a left square bracket ([). Since "[" is a magic character for regular expressions, it must be escaped. The "^" magic character anchors the search to the beginning of the line. The script prints a message and exits if the search was unsuccessful. ss yf "^[^ /]+" The yf string parameter accesses the next line in the circular buffer. This line, which follows the uploader's account number, contains the file name. The ss command extracts the file name, discarding the rest of the line starting with a possible file type designation ("/binary"). As above, "^" matches the beginning of the line. The "[^ /]+" phrase matches a class of characters ("[") excluding ("^") space, tab, and "/". The trailing "+" matches one or more instances of the search string, resulting in all characters starting at the beginning of the line up to but not including the first space, tab, or "/". setc s0 "\L%z0" Translate the file name in string parameter z0 to lower case. (This script is also used on Unix systems where most file names are lower case.) if f%s0 echo "%z0 Exists: No Action taken."; return echo "File name is %s0" put "\025dow %s0/PRO:B\r" pat 2i "\nFile name" wait -f20 if 2 put "\025%s0\r" ena -C; return (C) 1990 Omen Tech Inc Chapter 26 Regular Expressions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 232 The remainder of the script generates commands using the parsed file name. The script enables Compuserve's B Protocol, allowing the mainframe to initiate the download. 26.4.2 Magic Characters: Synopsis ZCOMM regular expressions give magic meanings to the characters \ * + ? . | ^ $ [ ] ( ) as follows: * 0 or more + 1 or more ? 0 or 1 . Any single character | Branch separator (for matching) EXAMPLE: ss s0 "(^cc: *|^ *)([^ ]+)" The first () grouping matches either "cc:" or a space at the begining of the line in s0. ^ Matches beginning of line $ Matches end of line [] Single character(s) in a class [^] Single character(s) not in a class () Grouping (for parsing) ZCOMM regular expressions closely resemble those used by the Unix egrep command. The Unix ed and vi editors use regular expressions with a slightly different syntax. Epsilon and Brief editors for DOS also use regular expressions. Regular Expression pattern matching is a software disicipline unto itself. Different program behave differently when matching ambiguous patterns. A number of Unix related books contain useful information on the uses of Regular Expressions. In the meantime, practice makes perfect. Setup some string variables with strings to search and parse, and experiment with different ss command search patterns. A full screen editor that uses regular expressions is a handy learning aid. (C) 1990 Omen Tech Inc Chapter 26 Test Conditions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 233 27. TEST CONDITIONS (if, on, while commands) The following conditions may be tested with the if, on and while commands. Where a string parameter is indicated, it is an error to specify a nonexistient string parameter. When an immediate string argument is indicated, that argument is delimited only by white space. As a result, if "is1,hello&&L<5" command ... won't work as expected, but if is1,hello if "L<5" command ... will work. Some of the test conditions described below may be used with ">", "==", "!=", or "<" for numeric comparisions. The right hand argument of a numeric comparision may be: + A decimal number. EXAMPLE: if "L>5" abort + A string paremeter which contains a decimal number. EXAMPLE: set maxloops "5" if "L>maxloops" abort + The length of the string stored in a string parameter, denoted by a leading % character. EXAMPLE: set s1 "Hello" set s2 "foo" if "%s1>%s2" echo "%s1 is longer than %s2" These comparisions should be quoted in case a future version of ZCOMM implements output redirection in the same manner as COMMAND.COM or the Unix shell. On 16 bit machines, 16 bit numerical values are used in comparisions; numbers greater than 32767 should not be used. Numeric conditions may also be tested against a bit mask using the & operator. EXAMPLE: if s&64 echo "Caps Lock is ON" 0...25 The specified pattern (see pattern command) was matched in the last wait command. (C) 1990 Omen Tech Inc Chapter 27 Test Conditions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 234 %svar The specified string parameter svar (see the set command) is non empty. May be used with ">", "==", or "<" for numeric comparisions of the string length of svar. EXAMPLE: if %s1 putw %s1 EXAMPLE: if %symbol>4 ss symbol "(.*)[A-z]"; sets symbol %z1 If the length of the string in string variable symbol exceeds 4, chop off the rightmost letter. ? The ? numeric parameter counts the number of files sent or received with a protocol, and the number of lines matched by the find command. The fFILE test condition (if true) assigns the file length to the ? parameter. On 16 bit computers, file lengths greater than 32767 are represented as 32767. With certain operating systems, the exit status of a subprogram accessed by a DOS Gateway is stored in the ? numeric parameter. The ? numeric parameter may then be tested with the ? test condition. It can be used with ">", "==", or "<" for numeric comparisions. EXAMPLE: p?0 find fizzbin *.txt; if ? echo "Found fizzbin" SEE ALSO: ? numeric parameter B True iff Ctrl-Break has been pressed since the last purgek command. Csvar True iff string parameter svar contains any control characters less than 040 (hex 20) or rubout. EXAMPLE: if Cs0 echo "Please Retype E True iff the elapsed time in seconds is non 0. Used with ">", "==", or "<" for numeric comparisions. NOTE: Elapsed time may be off by up to one second. On 16 bit machines, the maximum testable value for elapsed time is 32767 seconds. EXAMPLE: if "E>300" off Disconnects the modem if the elapsed time is greater than 300 seconds. SEE ALSO: restime command F>N True iff more than N kilobytes (1 kilobyte = 1024 bytes) of free space remain on the default drive. (C) 1990 Omen Tech Inc Chapter 27 Test Conditions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 235 EXAMPLE: if "F>2000" usq hugefile.q Hregular-expression Searches backward thru the last 127 lines of circular buffer for the next line matching regular-expression. If the search is successful, the y string parameter points to the matched line. The N test condition may be used to test the number of lines that were searched before finding a match. EXAMPLE: To allow processing of information such as: 5 Review folder UFO (0 stories) (a typical news item in the Executive News Service), one must scan for lines with a certain pattern (in this case the character "(" immediately followed by 1...9 indicating 1 or more stories). while "H\([1-9]" ss (rest of line) The above searches backwards for the next line containing "(1" to "(9". Note that "(" is a magic character in regular-expressions, and must be escaped. The h test condition is similar, but starts the search with the last displayed line. SEE ALSO: ens.t and kcdisl.t scripts, regular-expressions, y, yb, y0...y127 string parameters, N test condition Isvara,svarb Tests whether the contents of string variable svara are IDENTICAL to the contents of string variable svarb. Case is significant. EXAMPLE: if Is0,s9 goto exactmatch SEE ALSO: i test condition (compares a string parameter and an immediate string) Jsvar,string Tests whether any of the characters in the immediate string string appear one or more times in string parameter svar. EXAMPLE: if "Js0,!@#$%^&()_" echo "No funny characters"; goto getname L>N True iff this while command has made more then N loops. EXAMPLE: while !1 put "\r" wait ife "L>5" off Disconnects the modem (C) 1990 Omen Tech Inc Chapter 27 Test Conditions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 236 if the while command has sent more than five "\r"'s. The "L>N" should be quoted in case a future version of ZCOMM implements output redirection in the same manner as command.com or the Unix shell. N>N True iff the last h or H condition searched more than N lines before a match. SEE ALSO: h and H test conditions Q>N True iff the number of active queue entries is greater than N. R>N After a zcommand "" command, evaluates true iff more than N kilobytes (1 kilobyte = 1024 bytes) of free space remain on the remote system's default disk drive. EXAMPLE: zcommand ""; if "R>1000" sz -y hugefile S>N True iff the transmission speed is greater N bits per second. EXAMPLE: if S>2400 put "set verbose\r" U True if ZCOMM was unrestricted when the first level of the current set of scripts was activated. SEE ALSO: u test condition asvar The numeric value of the specified string parameter svar is non zero. May be used with ">", "==", or "<" for numeric comparisions. The string variable may contain leading spaces or tabs, an optional + or - sign, and digits. EXAMPLE: if "as1==30" goto seen30 Performs the goto if s1 contains "30". bTIME True if the current time is Before TIME. TIME is written in the form [yy[mm[dd]]]hhmm. No further conditions may be given in the if statement after the b condition. EXAMPLE: if b2300 return Returns from the script if the time is before 11 p.m. EXAMPLE: if b8512250900 return Returns from the script if the date/time is before 9 a.m. Christmas day in 1985. (C) 1990 Omen Tech Inc Chapter 27 Test Conditions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 237 c Carrier detect is present on the modem port. EXAMPLE: if !c goto lostit NOTE: On Unix systems, a dis -d command must be given to "arm" the system to detect carrier loss. SEE ALSO: d mode d{2?ADLMPSTXZacdflmprtu} True iff the corresponding configuration is true: 2 ZCOMM is executing under OS/2 protected mode. ? True if an unrecoverable error or manual abort was detected on the last protocol file transfer. A True if the term function's emulation Alternate Keypad Mode mode is on. C>N Numeric, true if the display column is greater than N. D The script is running on a demonstration program. H True iff no software flow control has been specified by the handshake command. Assuming the last handshake command correctly reflects flow control settings on any modems or networks involved, this test condition will give an indication that the transmission path should not intercept XON and XOFF characters. L True if ZCOMM is recording TurboLearn(TM) script information (learn command). M True if term function Keyboard Mapping is on ("display mapkb"). P Packet state is active (X.PC driver). R>N Numeric, true if the display row is greater than N. EXAMPLE: set fa10 @pat 23cp \n "@lput \E[K if dR>23 lput \E[H\E[K" When the Alt-F10 key is struck, a search pattern (23) is set. This searches for each linefeed from the remote and performs a local display clear to end of line on each new line. If the display row exceeds 23, jump to the top of the screen and clear the first line. This "trick" may be used to prevent scrolling on displays that smear badly. (C) 1990 Omen Tech Inc Chapter 27 Test Conditions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 238 S The script is running on a shareware program (e.g., ZCOMM). T True if a higher level of the script has called the Term Function. When True, the script should return to the Term Function; the script should not invoke the Term Function. X The X.PC commands are available. EXAMPLE: if dX goto xpclogin Z The ZMODEM commands are available. EXAMPLE: if dZ sz -n logfile a>N True iff ZCOMM was called from the operating system with more than N arguments (counting the program name). c The color/graphics display is selected. d ZCOMM is executing under DOS or OS/2. f The program is running in the foreground. On DOS, a script is considered to be running in the foreground when it is NOT called by the Callout Queue as described in Chapter 28. A program running in the background is unlikely to have an operator available for interaction. Under Unix, a script is considered to be running in the background if it is detached from possible keyboard input, and ZCOMM will exit when it reaches the main command prompt. SEE ALSO: fg, bg commands l>N True iff the script level (nesting) is greatern than N. m The monochrome display is selected. p The program has a non zero serial number. r Data Set Ready (DSR) on the modem is active. t ZCOMM is running under a Topview or DESQview virtual screen which may be smaller than the physical screen size u ZCOMM is executing under Unix/Xenix. v ZCOMM is executing under the VMS operating system. (C) 1990 Omen Tech Inc Chapter 27 Test Conditions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 239 e True iff an t, sz, or rz command terminated with an error, or if the term function has detected framing or overrun errors. Unless the q file transfer option is used, each file skipped as a result of ZMODEM selective transfer increments this parameter. This is the e numeric parameter, and is reset with each call command. It can also be reset with a pe0 command. SEE ALSO: e numeric parameter e>N True iff the e parameter (number of errors) is greater than N. EXAMPLE: if "e>5" off Disconnects the modem if more than 5 errors have been counted. The "e>N" should be quoted in case a future version of ZCOMM implements output redirection in the same manner as command.com or the Unix shell. NOTE: The e parameter is not compared within the term function, so "detection" may be delayed. SEE ALSO: e numeric parameter fFILE (No space between f and FILE). Tests whether FILE exists as a normal readable file (not a directory or hidden file). FILE is expanded for string parameters. If the test is successful, the ? numeric parameter (testable with the ? test condition) is set to the file length. [1] The N test condition reflects the number of links to the file. EXAMPLE: if fnit put "message\r"; f -xp nit; put "\r\336y" If nit exists, give a "message" command, upload the file, then send carriage return, pause, and the letter "y". When used in a numeric context, the fFILE test represents the size of the file in full kilobytes (1024 bytes), or 1, whichever is greater. EXAMPLE: if ffoo.bar>30 echo "File Longer than 30kb" EXAMPLE: if fspy.kgb if !? echo "Zero Length File" SEE ALSO: obey command __________ 1. On 16 bit computers, file lengths greater than 32767 are represented as 32767. (C) 1990 Omen Tech Inc Chapter 27 Test Conditions Version 17.78 TurboDial 2.35 Universal Line Printer Edition ZCOMM User Manual 240 g Tests whether term function file transmission flow is go (not stopped by an XOFF character). EXAMPLE: if !g echo "Remote has not sent XON"; pg1 SEE ALSO: g mode, term function XON and XOFF hregular-expression Please refer to the Hregular-expression test condition. isvar,string Tests whether the contents of string variable svar are identical to the immediate string string. Case is significant. No further conditions may be given in the if statement after the i condition. This test is useful in designing menu applications. The menu script menu.hst uses this test condition extensively. EXAMPLE: accept s1 Choice:; if is1,a goto choicea Executes a goto choicea if the user keyboards an a in response to the "Choice:" prompt. SEE ALSO: I test condition (compares two string parameters) jsvar,string Tests whether the immediate string string is a substring of (contained somewhere within) the contents of string variable svar. Lower case characters in string match characters in either case. Upper case characters in string match upper case characters. No further conditions may be given in the if statement after the j condition. This test is useful in designing menu applications, and for examining message lines read with the grab command. EXAMPLE: grab s1; if js1,sig= goto endofsig Executes a goto if the line read by the grab command contained "sig=" or "This SIG=". k One or more characters have been received from the keyboard and are in the interrupt queue awaiting processing. Note: Keyboard characters are transmitted to the remote by the term function, except during a put command. l True if the line printer is ready to accept a character. m One or more characters have been received from the modem and are in the interrupt queue awaiting processing. n No pattern was matched as a result of the last wait command or search pending term function. n detects a search timeout, loss of carrier detect signal, or manual exit with F1 or ALT-X. (C) 1990 Omen Tech Inc Chapter 27 Test Conditions