Beijing Paradise BBS Backup

home *** CD-ROM | disk | FTP | other *** search

/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / ZCOMMDOC.ZIP / ZCOMMDOC.AI < prev next >

Wrap

Text File | 1995-03-21 | 66.8 KB | 1,771 lines

Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 241 control characters NULL (0) to US (1F) in both parities. The ? character corresponds to FF (all ones character). 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. The ? character corresponds to FF (all ones character). SEE ALSO: zmrxesc string parameter (C) 1994 Omen Tech Inc Chapter 25 Character Escapes Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 242 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) 1994 Omen Tech Inc Chapter 26 Character Escapes Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 243 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) 1994 Omen Tech Inc Chapter 26 Character Escapes Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 244 sends "foobar". putw "%s1\142bar" sends "foobbar". putw "%s1-skidoo" sends "foo-skidoo". putw "%s1bar" is undefined. putw "%s1\bar" sends "foo<BS>ar" 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 term options (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) 1994 Omen Tech Inc Chapter 26 Quoting Strings Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 245 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) 1994 Omen Tech Inc Chapter 26 Regular Expressions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 246 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) 1994 Omen Tech Inc Chapter 26 Regular Expressions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 247 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) 1994 Omen Tech Inc Chapter 26 Regular Expressions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 248 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) 1994 Omen Tech Inc Chapter 26 Regular Expressions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 249 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) 1994 Omen Tech Inc Chapter 26 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 250 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) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 251 %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) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 252 EXAMPLE: if "F>2000" gosub getfiles 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) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 253 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) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 254 c Carrier detect[1] 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 term option d{2?ADLMPSTXZacdflmprtu} True iff the corresponding configuration is true: 2 The OS/2 protected mode ZCOMM flavor is executing. ? 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. G The script is running on a gyam (graphics file xfer display) flavor. 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" __________ 1. Carrier Detect, CD, pin 8 on RS-232 25 pin connectors (C) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 255 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. 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 The DOS or OS/2 ZCOMM flavor is executing.[2] SEE ALSO: d2 test condition (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. __________ 2. The dd test condition detects what flavor of Zcomm is running, not what environment Zcomm is running under. The dd test condition does not distinguish between DOS, DR-DOS, DOS-Merge, VP/ix, or other DOS emulators (C) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 256 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. 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. [3] The N test condition reflects the number of __________ 3. On 16 bit computers, file lengths greater than 32767 are represented as 32767. (C) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 257 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 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 term option, 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=". (C) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 258 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. psvar,string Tests whether the immediate string string is a prefix of the contents of string variable svar. The match is case sensitive. No further conditions may be given in the if statement after the p condition. This test is useful for examining message lines read with the grab command. EXAMPLE: grab s1; if ps1,sig= goto endofsig Executes a goto if the line read by the grab command contained "sig=", but not if it contained "This sig=" or "SIG=". q>N True iff the number of free queue entries is greater than N. r True iff a receive file is open for capture. SEE ALSO: create, t commands s>N True iff the keyboard shift state is greater than N. EXAMPLE: if "s>63" echo "Caps Lock is Active" t True iff a transmit file is open. EXAMPLE: if !t echoc "%1 Short file! "; goto foobar SEE ALSO: f, open commands u True if ZCOMM is unrestricted. SEE ALSO: U test condition v True if the v (Verbose) numeric parameter is non zero. EXAMPLE: if "v>0" s Displays the status on the console if the v numeric parameter (Verbose) is greater than zero. (C) 1994 Omen Tech Inc Chapter 27 Test Conditions Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 259 y ZCOMM accepts a single character from the keyboard, which is printed followed by a newline. True if the character is "y" or "Y". False the H numeric is non zero, and a character is not typed within the time limit set by that parameter. EXAMPLE: echo "Really quit?"; if y quit Compound tests may be formed with the unary ! (not), binary || (or), and binary && (and) operators. The tests are evaluated strictly left to right. The unary ! operator applies to the following operand only. EXAMPLE: if n&&!n||c echo "Carrier Detect Present" simply tests carrier because the result of the binary and operation above is always false. EXAMPLE: if !c||1||2 o abort Disconnects the modem and aborts the script if carrier detect is off, or if either pattern 1 or pattern 2 were matched. EXAMPLE: on e>45||!c goto allsignd Each time the term function returns, branch to the end of the script if carrier detect is lost or more than 45 line hits have been detected. (C) 1994 Omen Tech Inc Chapter 27 Host Operation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 260 28. HOST OPERATION / REMOTE CONTROL ZCOMM Host Operation allows callers to access files, programs, and other computers with baud rate detection, speed conversion, and multiple layers of password access control. The comments in this chapter apply when ZCOMM is in Host Operation. Host Operation is entered by the host command. The host command is given only from a script, such as the telephone directory "host" entry. In Host Operation, the default disk is set to the default disk as of when ZCOMM was started. The port and baud rate are set to those in effect when the host command was given. Normally the screen is cleared, unless the v numeric parameter is set >0. The status line displays the number of Calls, Logins, Messages, and Scans since ZCOMM was invoked. ZCOMM then awaits a carrier detect signal or character from the modem indicating an incoming call. The modem must be configured to obey Data Terminal Ready (DTR) and provide an accurate Data Carrier Detect (CD) signal to the computer. While awaiting a call ZCOMM periodically scans the queue of outgoing message scripts if the callpath string parameter is set.*\*(ZZ*F The call3 string parameter may be used to display a help message which will show while ZCOMM is awaiting calls. EXAMPLE: set call3 @echo "Now awaiting incoming calls. Press F1 to exit." When a character is received from the modem or the modem's carrier detect signal comes on, ZCOMM executes the baudstr string parameter.[1] Most contemporary modems can send a string indicating the incoming transmission speed.[2] The baud2.t script searchs for these strings and sets the transmission speed accordingly. The caller does not have to hit carriage returns to allow ZCOMM to detrmine the transmission __________ 0. The Callout Queue is described in a later subchapter. 1. If the executed string begins with "@", the rest is treated as a command line, otherwise the string is sent to the modem. 2. At the current speed, before switching to the speed of the incoming transmission (C) 1994 Omen Tech Inc Chapter 28 Host Operation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 261 speed. The call2 string parameter setting in the distribution phones.t file commands a Hayes compatible modem to transmit these extended result codes. When ZCOMM completes execution of baudstr, ZCOMM checks the modem's carrier detect signal. If carrier has disappeared, ZCOMM executes the call2 string parameter and resumes its vigil. If carrier is still present, ZCOMM increments the Call counter and switches to remote operation. Remote operation allows characters to be keyboarded from either the local keyboarded, or by the caller. Remote operation also causes most screen output to be sent to the modem. Then ZCOMM executes the challenge string parameter. The supplied CHALLENG.T script file first states the name of the system. If the string parameter password is set, the script demands a password. The caller must enter it correctly, in the correct case, or be disconnected after three tries. If password is empty, no password is demanded. The caller then enters his name. Names with special characters are rejected. The name link immediately access the link command.**[3] Otherwise, the script asks the caller to confirm the name just typed. If the script is exited with a fail command, ZCOMM terminates the call. Iff none of the previous activities has terminated the call, ZCOMM increments the login counter, sets Restricted and executes the welcome string parameter and then drops into remote command function. Most commands are allowed remotely, except those that would disrupt the connection (port selection) or violate security if unrestricted privileges are not granted. The caller may request unrestricted privileges with the unrestrict command.* The caller must enter a password matching the unrestrict string parameter. The session is terminated by loss of carrier detect, the bye, o, or off command, or by typing F1 or NUKE (ALT-N) on the local keyboard. In Host Operation, ZCOMM will drop the call if it has to wait more than five minutes for the next command. The j numeric parameter sets __________ 3. The supplied CHALLENG.T script terminates the call when the link command exits. (C) 1994 Omen Tech Inc Chapter 28 Host Operation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 262 the connect time limit in seconds for restricted callers. This limit is checked each time the host command prompt is displayed. If Restricted, pathnames are checked against the contents of string parameter home. Absolute pathnames (beginning with \ or /) must include home as a prefix, and contain no references to parent directories (..). This allows remote users to access a subtree of the disk without allowing access to other directories. The string parameter rdisks should be set to include only the disks that are to be accessed by restricted callers.[4] The disks string parameter should be set to include the disks that are to be accessed remotely by any caller. ZCOMM's Kermit commands operate properly in Host Operation. When the caller disconnects by issuing a bye or off command or by dropping carrier, the exrc string parameter is executed. exrc should contain commands to "clean up" after a host session. If hardware handshaking is used, exrc should contain a handshake off command. The callout queue is scanned, and the call2 parameter is executed and ZCOMM resumes waiting for incoming calls. The screen is then cleared unless the v numeric parameter is greater than 0. If the user keyboards F1 ZCOMM leaves host state and executes the outahost string parameter. 28.1 Remote Execution of DOS Programs The ! command is allowed only if unrestricted privileges have been granted. All the caveats mentioned under the ! command apply, especially since it may be inconvenient to reset the computer hardware from a distance. A DOS program invoked with the ! command will normally display on the local screen only. The program's output may be redirected to the modem by referring to the DOS device corresponding to the modem port. For example, if serial port 1 (COM1) is being used for the modem connection, the following ZCOMM command will output to the modem. !chkdsk >com1 Although input can be redirected from the modem, the modem status may not be appropriate for the desired operation. Some careful checking __________ 4. The pathnames private, messages, rxlog, txlog, and callers are not checked. They cannot, however, be changed by a Restricted user. (C) 1994 Omen Tech Inc Chapter 28 Host Operation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 263 beforehand may forestall the frustration of a distant computer tightly wedged beyond all hope. Be especially careful to check what such commands might do in the event of line hits or loss of carrier detect. The DOS "ctty" command may be used with caution. It should be preceded with a DOS mode command to set 7 bits. The caller should be using the same number of bits and parity as used with the DOS mode command. The following may be placed in a .BAT file to allow remote operation of DOS programs: mode com1:1200 ctty com1 command ctty con If these commands placed in "CT.BAT", then the caller can type !~ct to get a DOS "shell" (command.com). When finished, give the DOS "exit" command. CT.BAT then returns DOS control to the console and then returns to ZCOMM's Host Operation. Please refer to the DOS Gateway subchapter in Chapter for more information on running DOS programs under ZCOMM. The Doorway or similar programs may be useful for remote DOS program execution. Doorway intercepts VIDEO BIOS calls and transmits ANSI escape sequences to regenerate the display on the calling terminal. Doorway may be set to use an extended keyboard mapping supported by ZCOMM's term function ALT-= toggle. (Current Doorway versions command ZCOMM's term function to extended keyboard mapping automatically.) DOS doesn't do anything intelligent with break or carrier dropout, so be careful. ZCOMM will reinitialize the modem UART properly when it regains control. 28.2 Script for Host Operation The supplied scripts assume the following directories exist on the c: drive: \host \tmp \memo \yam host echo "Host" host: echo "Host1" set emdir /memo; set twxfile twx; set disks "c" set rdisks "c" set call1 ATZ\r\336ATZ\r set call2 @bye; sleep 3; putw "\336ATZ\r\336\336ATX1 M0 S0=1\r"; clears (C) 1994 Omen Tech Inc Chapter 28 Host Operation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 264 set callpath /tmp/*.xx? set outahost ATZ\r : set rmtcmd "C:/host/checkrmt.t" The above lines set parameters used with Host Operation. The call1 callpath, and rmtcmd lines must be commented out for use with ZCOMM. px2; py9600 : Set parameters for link cmd set linkpass "Giznoid" set outalink "@kill; put \r\4;o" port 1; bye; set rcmdlog "c:/tmp/rcmds" speed 1200 putw "ATZ\r" set callers "c:/host/callers" :Do NOT remove the "." in ".%lib..." below set baudstr "@gosub .%lib/baud2.t" set challenge "@gosub .%lib/challeng.t" set welcome "@type welcome.txt; purgek; nulls 0" set password "Change This Already" set rxlog "c:/host/rxlog"; set txlog "c:/host/txlog"; set unrestrict "" set xhelpfile "/host/xyamhelp.t" set home "/host"; cd set private "/private"; set messages "/host/messages" set emdir "/memo"; set twxfile "twx"; set answerback "\r\nJ. Fred Muggs\r\n\21" set outahost "ATZ\r" set menu "/host/hostmenu" host 28.3 Command Intercept Script After the remote caller in Host Operation keyboards each command, before that command line is executed, ZCOMM executes the rmtcheck string parameter. * This is also performed on commands received by ZMODEM protocol Command Download. The rmtcheck parameter may be set to invoke a READ ONLY script to examine the command line stored in the rmtcmd string parameter. Such a script may modify the command by changing the contents of rmtcmd disconnect the user with a bye command, or perform other checks for the particular application. The script can trap references to illegal disks, directories, or files, or redefine or add commands. SEE ALSO: pwd, rmtcheck, rmtcmd string parameters An example remote command inspection script is provided in checkrmt.t shown below. ss rmtcmd "(^arc[^ ]*)(.*)" if %z2 obey "!~pkxarc /v %z2>COM1"; goto done (C) 1994 Omen Tech Inc Chapter 28 Host Operation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 265 String Split the user's command (in rmtcmd) into a command name starting with "arc" and an argument separated by a space or tab. If the split is successful, execute the DOS pkxarc program with a "/v" (verbose archive listing) flag and the name of the archive stored in the z2 string parameter. Program output is redirected to the modem. if %z1 echo "Must specify archive"; goto done If the "arc" command was found but no archive name was given, complain. ss rmtcmd "^whereis |^sd$|^sd |^ls |ls$" if !%z0 return obey "!~%rmtcmd>COM1" If the command is "whereis" with an argument, "sd" with ot without an argument, or "ls" with ot without an argument, execute the DOS command with output redirected to the modem. done: set rmtcmd ""; return After command execution, clean up by clearing rmtcmd and return to ZCOMM. This script must be stored with the READ ONLY file attribute for normal operation. For convenience in testing, use the unrestrict command to allow operation without the READ ONLY file attribute. The ALT-1 and ALT-2 keys allow local keyboard access to commands without executing the rmtcmd string parameter. 28.4 Callout Queue When entering host operation, and periodically thereafter, ZCOMM scans for script files specified by the callpath string parameter.** (If callpath is empty, this function is disabled.) The period in seconds between scans is set by the c numeric parameter. Between these scans, ZCOMM waits for incoming calls. The pathspec callpath is expanded alphabetically, and a queue entry is made for each file found, up to a maximum of 40 entries. If one or more queue entries are found, the transmission speed is set to the speed in effect when the host command was given, and call1 is executed. Typically, call1 disables the modem's autoanswer mode. Then each queue entry is executed as a source file. Unless enclosed by double quotes, string parameters appearing in the commands (as %spar) are replaced by their values as the commands are read from disk. These script files typically contain commands to check the time, set transmission speed, dial a telephone number, and transfer data. The last line of each script usually contains a command to (C) 1994 Omen Tech Inc Chapter 28 Callout Queue Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 266 delete itself (or to rename itself so it will no longer be executed) after successful transfer of data. If the data transfer fails, the script will not execute its last line, and will be retried on the next callout. After the queue entries have been exhausted, the transmission speed is set to the speed in effect when the host command was given, and call2 is executed. Usually, call2 sends a command to the modem to to make it answer incoming calls. ZCOMM then waits for incoming calls until it is again time to scan for outgoing scripts. 28.5 Callback Security In security conscious applications, it may be desireable to limit access to specified users calling from authorized locations. A callback scheme is demonstrated in the supplied script callback.t with a sample callback directory callback which references entries in the phone directory. Be sure to remove the echo commands before using this script. (C) 1994 Omen Tech Inc Chapter 28 Terminal Emulation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 267 29. TERMINAL (CRT) EMULATION PCDOS flavors emulates the DG Dasher, 3101, TI940, H19, Z19, VT52, VT100, VT102, VT220, Wyse, and LSI-ADM3a terminals with the display command. The display command controls the display's emulation of control characters and escape sequences. Keyboard mapping is defined with mk commands. A number of script files with the mk extension are provided for common configurations in the SCRIPTS.ZOO archive. 29.1 Wyse 60 Emulation DOS flavors can emulate the Wyse 60 terminal given the command display wyse. Wyse (wy60) terminal emulation supports operation with applications on Unix/Xenix systems. The command display wyse enables Wyse screen emulation. Wyse emulation can place YAM in "PC Terminal" mode with 25 display lines (status line invisible) and "scan code" operation. Since the SysRq key does not return a code to Zcomm, the sequence LeftShift Alt = sends the scancodes generated by the SysRq key. To exit from VP/ix, hold down on the LeftShift and Alt keys, keyboard =, keyboard m (for menu), and then keyboard q before releasing the Alt and Shift keys. 29.2 Data General DASHER Emulation 8 bit Dasher terminal emulation is enabled by the display 8bit command. 29.3 Printer Controller ZCOMM supports the DEC VT100 Printer Controller command (ESC [ 5 i). When the display vt100 has been given, NULL, XON, and XOFF characters are not passed to the printer. Disable vt100 emulaion to pass these characters to the printer. To pass 8 bits to the printer, give ena -8g or toggle ALT_P until 8g shows in the status line. If you are using software flow control (XON/XOFF) and the printer is slower than the communications line, the host must not be configured to resume output on receipt of a second XOFF character (Unix "stty ixany") or data will be lost. 29.4 VT220 8 bit Controls The command display 8bit casuses ZCOMM to emulate the VT220 in "level 2" operation. The DEC "GR" display characters are not currently supported. (C) 1994 Omen Tech Inc Chapter 29 Terminal Emulation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 268 29.5 Keyboard Mapping When enabled by a display mapkb command, DOS flavors of ZCOMM reassign keys to simulate the function keys of the emulated terminal. Keyboard Mapping operartes only in the term function, where the mappings override the other meanings of the affected keys. The following key assignments for a PC-AT style 84 key keyboard are made by the distribution setup entry. VT100 Keyboard Mappings for PC-AT Keyboard PC Key.................VT100 keyCharacter F7.....................UP.......A Cursor Keys F8.....................DOWN.....B F9.....................LEFT.....D F10....................RIGHT....C F1.....................PF1......P PF Keys F2.....................PF2......Q F3.....................PF3......R F4.....................PF4......S Pad 0..................Pad 0....p Number-Pad Keys ... Pad 9..................Pad 9....y Pad -..................Pad -....m Pad *(PrtSC)..........., comma..l (lowercase L) Del (.)................(.) (period)n Pad +..................ENTER....M Many users prefer a different keyboard layout for terminal emulation. Laptop computers that do not use a standard keyboard layout may not map well in Alternate Keypad Mode, suggesting different mappings. The mk command, K and N numeric parameters provide a flexible, if complex, keyboard mapping ability for various terminal emulations. ZCOMM's term function maps the keyboard by scanning a table of mappings for a match to the key's modified scan code, shift state, and the state of the emulation machine. Iff the match is successful, special characters required by the emulation are sent to the application according to the class field, followed by the character(s) defined in the mapping. If you have a 101 key keyboard and ROM BIOS support for it, set the K numeric parameter to 1 to activate the extra keys,[1] distinguish the __________ 1. This may cause problems with certain versions of IBM BIOS. (C) 1994 Omen Tech Inc Chapter 29 Terminal Emulation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 269 cursor keys from the numeric pad, and set the N numeric parameter to 1 to keep the keyboard in its preferred NumLock state at all times. With a regular keyboard, you must make more compromises in selecting your keyboard mapping, depending on which keys are important to your particular application. In particular, the "5" key on the numeric pad doesn't work unless NumLock is on. The four possible values of the N numeric parameter allow the keyboard to be placed in NumLock none of the time, all the time, when the emulation's Numeric Keypad mode is on, or when Alternate Keypad mode is on. To devise your own mapping, you will need to know the modified scan code, shift state, and ZCOMM internal value for each key you wish to use. The modified scan code and internal value information are provided by the _ (underscore) command. To clear the keyboard mappings, give the mk command without arguments. For each term function keyboard mapping, the mk command takes four arguments. modified scan code This is normally the value returned by the ROM BIOS indicating the key's physical location on the keyboard. If the raw scancode equals 224 (extended keyboard only), the modified scancode consists of the scancode added to the ZCOMM internal code. It is shown by the second number printed by the _ (underscore) command. shift state The arithmetic sum of the following conditions: 1 Right hand shift key 2 Left hand shift key 4 Ctrl Key 8 Alt key 16 Provided the Shift, Crrl, and Alt key states match, select this mapping regardless of whether the Application Keypad Mode or the Decoded Function Key conditions (below) are true. 32 Alternate Keypad Mode (not numeric) 64 Decoded Function Key (Character value greater than 0400 as displayed by the _ (underscore) command. 128 Select this mapping unconditionally. Note that a separate entry must be made for each shift key (left/right). A separate entry may be made for BOTH left and (C) 1994 Omen Tech Inc Chapter 29 Terminal Emulation Version 18.18 TurboDial 2.41 Universal Line Printer Edition ZCOMM User Manual 270 right shif keys provided your computer's BIOS recognizes characters entered with both shift keys down. class 0 Cursor Code (LRUD). In VT52 mode, ESC is prepended to the string. In VT100 Application mode, "ESC [" is prepended. In VT100 Cursor mode, "ESC O" is prepended. 1 PFK Key. In VT52 mode, ESC is prepended, otherwise "ESC O". 2 Numeric Keypad. Not mapped in Numeric Keypad mode. In Alternate Keypad mode, the string is prepended with with "ESC ?" for VT52, "ESC O" for VT100. 3 An ESC is prepended. 4 No characters are added to the string. string A string of 1 to 7 characters taken from the third column above. Control characters must be represented with ZCOMM character escapes. 96 keyboard mapping entries are allowed. To change an entry, all must be cleared and reloaded. EXAMPLE: To remap the backspace key to send RUBOUT without affecting Ctrl-H: mk mk 14 0 4 "\177" display mapkb EXAMPLE: We wish to map the Up key to send the VT100 cursor up code. First, we see _ (underscore) command dislays 72 72 0 510 for the Up key, indicating a scan code of 72, modified scan code of 72, 0 shift state, and a ZCOMM internal code of 0510 (Function Key). (Exit the _ command by typing Ctrl-Enter). To make this key always active in "display mapkb" mode, assign it a shift state of 16. Since VT100 cursor keys have class 0, the command is: mk 72 16 0 A EXAMPLE: mk 72 1 0 A maps "right shift keypad 8" to send the VT100 cursor up code (assumes right shift key). The set command may also be used to define suitable key mappings. (C) 1994 Omen Tech Inc Chapter 29 Terminal Emulation