.! standard beginning .page size 60,65 .! length,width .rm 65 .! width again .flags uppercase { .flags lowercase } .flags accept \ .flags underline _ .no flags bold .!flags bold % .flags hyphenate ` .flags break | .flags space ^ .flags period ~ .no flags capitalize .no flags overstrike .!flags overstrike < .no flags subindex .!flags substitute $ .no flags substitute .no autosubtitle .spr 0,1,2 .! change if indented paragraphs desired .ap .sthl 4,0,6,7,7,2,1,7,2 .! run-in heads at level 4, level 0 all caps .title ESB CONNEX Program .subtitle .!date .!first title .! probably don't want first title .autosubtitle 1 .figure 14 .c;Elias Sports Bureau .c;CONNEX External Dial-out Connection Controller .c;Version 1.0 .s .s2 .flags substitute $ .C;$$month $$day, $$year .no flags substitute .s3 .c;prepared by .c;George Merriman .c;Cambridge Computer Associates .c;56 Beaver Street .c;New York NY 10004 .c;merriman@camb.com .s2 .no fill .c;Derived from the DECUS UUCP documentation by .c;Hanrahan, Allebrandi and Pizzolato .!no justify .!no autojustify .display number RL .chapter Using CONNEX The CONNEX program is designed to facilitate automated data transfer operations from VMS systems to remote hosts by way of PSTN dial-out circuits. Most of the code was derived from V1.1 of the DECUS UUCP facility by Hanrahan, Allebrandi and Pizzolato. .hl 1 Overview CONNEX uses ordinary VMS text files to maintain a database of remote hosts and available dial-out terminal ports. It uses script files as specified in the database files to drive the MODEM dialing, remote host login, remote host logout and MODEM disconnect interchanges. CONNEX runs in two phases -- the connect phase and the hangup phase. In a typical session, CONNEX is first run in the connect phase, which finds and allocates a dial-out port, makes the outgoing call and runs the login script. When CONNEX exits with success from the connect phase the user has the outgoing port allocated as device CNX\_DEV and can run whatever data transfer application is appropriate. After the data is transferred CONNEX is run in the hangup phase, which runs the logout and hangup scripts and deallocates the port. CONNEX uses three logical names as defined in the JOB logical name table to maintain context between the connect and hangup phases: CNX\_DEV, noted above; CNX\_LOGOUT, which specifies the logout script; and CNX\_HANGUP, which specifies the hangup script. .hl 1 Using CONNEX Assuming the CNX foreign command has been set as described below, CONNEX is run in the connect phase by the DCL command line .lm+8 .lit $ CNX [-xn] [-c] .end lit .lm-8 where: .list " " .le;-xn sets the debug level; .le;-c uses as the Control File, default CNX\_CFG:CONTROL.; .le; is the target system name used in the Systems File. .end list Run CONNEX in hangup mode with the DCL command line: .lm+8 .lit $ CNX [-xn] [-c] -h .end lit .lm-8 where: .list " " .le;-xn sets the debug level; .le;-c uses as the Control File; .le;-h indicates hangup mode .end list Do not specify a target for hangup mode -- the CONNEX context is maintained between phases. .hl 1 CONNEX Exit Status CONNEX returns several exit status codes to DCL: .list "-" .le;CNX\_OK -- the normal success status; .le;CNX\_ERR -- program error; .le;CNX\_FAIL -- failed call -- specified in a script file; .le;CNX\_NOPORT -- no port available for the system; .le;CNX\_NOSYS -- the target system is not in the Systems File; .le;CNX\_BUSY -- the target was busy -- specified in a script file. .end list These codes are defined in CONNEX.MSG. .chapter CONFIGURING CONNEX CONNEX requires two logical names be defined in the user's environment: .list "-" .le;CNX\_CFG must point to the directory containing the Systems, Control and script files; .le;CNX\_EXE must point to the directory containing the CONNEX.EXE image file. .end list CONNEX requires CMEXEC, SYSNAM and TMPMBX privileges to operate. These can be provided by the user's process, or CONNEX can be installed with privileges. In addition, the CONNEX command must be defied as a foreign command with a DCL symbol definition such as: .lm+8 .lit $ CNX :== $CNX_EXE:CONNEX .end lit .lm-8 CONNEX is configured by the use of a Control File and a Systems File: CNX\_CFG:CONTROL. and CNX\_CFG:SYSTEMS. These files are described below. .hl 1 The Control File The Control File defines the CONNEX environment. Each entry in the Control File consists of an entry type field optionally followed by one or more parameter fields. Blank lines are ignored. The two most interesting parameters are the Debug parameter, which sets the debug message level for CONNEX, and the port parameter, which specifies a serial port available to CONNEX. Several other parameters are available, but in most cases the default value will be used. .hl 2 Debug The "debug" parameter specifies the classes of debug output that are written to the debug log files. It is interpreted as a binary mask; each bit corresponds to a class of debug messages. .note This parameter is interpreted according to the syntax rules for C integer constants, meaning that {_leading zeroes (one or more) in the number cause it to be interpreted in octal}_. If you prefer hex notation, change it to the form 0xhhhh, where hhhh represents any number of hex digits; the "x" may be in upper or lower case. In either case, at least one leading zero is required. If you eliminate the leading zeroes, the number will be interpreted in decimal. .end note The debug bits are interpreted as follows: .list "-" .le;0^^--^error messages and a copy of the LOGFILE output .le;1^^--^dial,login,init trace -- errors only .le;2^^--^dial,login,init trace -- non-errors (incl char I/O) .le;3^^--^file transfer commands -- errors only .le;4^^--^file transfer commands -- non-errors .le;5^^--^file name munging trace .le;6^^--^file directory scanning trace .le;12^--^call decisions .le;16^--^script processing internals .end list .hl 2 Port Provide a "port" line for each serial line which you intend to allow CONNEX to use for dialout. The format of this line is: .s .lm+8 .literal port .end literal .lm-8 .ls1,"o" .le;As shown in the supplied example file, "port" is a literal string. .le; is a CONNEX-specific name for the port, or for a class of ports (which is to say that multiple port entries can specify the same name). By convention we use "ACU" (short for Automatic Calling Unit, an archaic piece of AT&T hardware with which uucp was first used) to specify an autodialing modem. .le; can be anything, but typically it is either "none" (for hardwired connections to other systems, perhaps in the same room) or the name of a type of modem. If this string is anything other than "none", CONNEX uses it as the extension of the file name for dial and hangup scripts for the modem in question. For example, with the Control File shown, CONNEX will expect to find files CNX\_CFG:DIAL.HAYES and CNX\_CFG:HANGUP.HAYES . Scripts are described in detail in the next chapter. .le; and The and are the VMS device name of the serial port and the bit rate which the modem (or target systems, for hardwired links) support. If your modem supports multiple speeds (as most do), and you want CONNEX to use them, put several "ports" lines in the file, one for each speed but with the all other parameters the same. (Or perhaps not all the same. For example, some modems might need a special dial script to operate properly at one particular speed.) .els0 .hl 2 Other Control Variables There are three other Control File variables, for which the default values are appropriate in most cases: .list "-" .le;sysfile^--^the FULL file specification for the Systems File, default CNX\_CFG:SYSTEMS.; .le;cfgdir^^--^the directory specification for script files, default CNX\_CFG:; .le;logfile^--^the FULL file specification for the log file, default is no log file. .end list .hl 1 The Systems File The Systems File tells CONNEX who your target systems are and how to reach them. CONNEX scans this file once each time it is run. Each {_entry}_ in the file describes a target system. Each entry in the Systems File consists of one or more lines, every line except the last ending with a backslash (\\). (The \\ must be the {_very}_ last character on the line, with no subsequent blanks.) Leading !'s or #'s may be used to denote comment lines, and these may appear in between the lines of a single entry. A single system might have multiple entries in the file, perhaps specifying different telephone numbers. When CONNEX encounters the first entry for a given system, it sees if the system can be called according to the rules given by that particular entry and available ports. If the answer is yes, and the call is placed and is successful, all successive entries for that system are skipped. If the answer is no, processing continues with the next entry, and the call decision is made according to that entry's fields. It is a good idea to use comments in the Systems File to record information such as the name, voice telephone number, and so on, of the system manager at each of your target sites. The format of each entry is: .s .literal \ \ ... .end literal This is a series of strings, or fields, separated by white-space (any combination of blanks, tabs, and, if preceded by backslashes, line breaks). No white-space may appear {_inside}_ any of the strings. (There is an "escape convention" to allow the encoding of white-space within certain strings, should that be necessary.)~ The angle brackets denote syntactic elements; they do not appear in the file. When a line is continued, the "newline" between each pair of lines disappears completely; it does not appear as white-space in the assembled entry (but if you have white-space before the backslash or at the beginning of the new line, it is preserved). The following subsections describe each field in turn. .hl 2 field is the CONNEX name of the remote system and is passed as the argument to the CNX command. CONNEX will only call systems whose names appear in the Systems File. .hl 2 field is a string used to identify the system entry in certain log file records. A hyphen (-) will cause the system-name to be used; this is fine if you have just one Systems File entry per target system. If your Systems File is more complex than that, putting a different entry-name on each entry will help to make the log file less ambiguous. .hl 2 field identifies the port, or class of ports, which may be used to contact the system; If the system is reached via a hardwired connection, this should be the that appears in the corresponding "ports" entry in the Control File; otherwise it should be "ACU" (or whatever name you gave to your ports with autodial modems). If you want contacts with a particular system to use a particular type of modem, you can invent a special port name, and add one or more "ports" entries to the Control File accordingly, specifying the physical devices to which those modems are connected. .hl 2 field is the line speed to use when calling the system. When CONNEX decides to call a system, based on a particular entry for that system in the Systems File, it scans the Control File for a "ports" entry with matching and fields. The fields must match exactly; "2400" is not taken to mean either "2400 or less" or "2400 or more". .hl 2 field is the number to dial to reach the system. You can include "W"s in the string to denote wait-for-dialtone and "P"s to denote a timed pause for two seconds, if your modem supports these functions. Use these characters regardless of the actual codes your modem wants in its dial command; they will be translated when the dial script is processed. .hl 2 field is the filename extension applied to CNX\_CFG:LOGIN\. and CNX\_CFG:LOGOUT. to derive the name of the scripts that will be used to log into and out of the remote systems. Login (and other) scripts are described briefly in the next section; the following chapter provides a complete description of the script language. .hl 2 ... fields are optional string parameters, available to the login script.^[3]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [3]^^And to the dial and hangup scripts, for that matter, though they are typically only used with the login script. .end footnote Note that no blanks or other white-space per se may appear in these strings, but blanks may be specified as \\s, tabs as \\t, etc., as described under "Extended Strings" in the next chapter. If you want an actual backslash in one of these strings, use two backslashes in succession. Trailing unspecified parameters default to empty strings; a non-trailing empty string may be specified as "-" (a lone hyphen), and a string containing only a hyphen may appear as \\-. .hl 1 Script Files The final set of configuration files you will need are "script files". These tell CONNEX how to dial a remote system, how to log into and out of the remote system, and (optionally) what to do to the modem at the end of the call. You will find a complete description of the script language in the following chapter. You will need to ensure that the following script files exist and are correct for your situation: .hl 2 Dial Scripts For each different that appears in a "ports" entry in the Control File, you will need a script file called CNX\_CFG:DIAL. . This script tells CONNEX how to use that type of modem's autodial feature. For instance, for Hayes-type modems, the script (to simplify matters a bit) tells CONNEX to send "AT", wait for an "OK", and then send "ATDT" followed by the from the systems entry and a carriage return, and then wait for a response from the modem indicating success or failure. .hl 2 Login Scripts If the dial script ends in success, CONNEX then uses the specified in the systems entry for the called system to negotiate the login sequence (wait for "Username:" prompt, send username, etc.). The name of the login script used is CNX\_CFG:LOGIN.extension, where the filename extension is given by the parameter of the current system entry. .hl 2 Logout Scripts Logout scripts, if available, are used by CONNEX during the hangup phase. The name of the logout script used is CNX\_CFG:LOGOUT.extension, where the filename extension is given by the parameter of the current system entry. .hl 2 Hangup Scripts Finally, for some s, you {_may}_ need a script file called CNX\_CFG:HANGUP. . This script, if present, is run after the logout script during the hangup phase. It tells CONNEX how to return the modem to a state suitable for accepting incoming calls. For example, in order to accept incoming calls under VMS, most modems must be configured to {_not}_ send "result codes" (strings such as RINGING, CONNECT 2400, and the like) to the local VAX, and so these modems are normally configured that way. But it is convenient to get result codes from the modems during the dial sequence, so the dial sequence starts with steps to turn result codes on. The hangup script is used to turn them back off again at the end of the outgoing call. (See the preceding chapter on modem setup options.) Some modems allow you to store your desired option settings in nonvolatile RAM, and will reset to these settings whenever the VAX drops the Data Terminal Ready (DTR) signal. Since DTR is dropped at the end of each call, even if CONNEX terminates abnormally, this provides a convenient way to ensure that the modem gets reset to the correct state. For such modems, hangup scripts need not be provided. Some other modems will work correctly for both outgoing calls and incoming calls with the same set of options; in this case no option changes are needed in the dial script, so no hangup script is needed either. .hl 1 Summary Here is a brief list of the steps required to set up CONNEX configuration files: .ls1,"o" .le;Edit the Control File to specify the default debug options and the serial ports to be used for outgoing calls. .le;Create one or more entries in the Systems File for each of your target systems. .le;Create appropriate dial, login, and hangup script files. .els0 .chapter Script Files CONNEX uses "script files" to direct modem dialing, login sequence, logout sequence and modem reset operations. Script files are somewhat like DCL (or other CLI) command procedures, with some modifications as appropriate for this application. Formally, a script file describes a state machine; CONNEX interprets the script file^[1]~ and does what the state machine tells it to. .hl 1 Script File Format Script files are ordinary text files containing {_comments}_, {_labels}_, and {_statements}_. Comments are denoted by leading "!" or "#" characters. Some statements (those which do not end with an "extended string" argument; see below) can also have trailing comments. Labels begin in column one and are ended by colons (:). A label specifies a state name. All lines between a pair of labels are the statements for a single state. Processing always begins at the head of the script (no leading state name is necessary). Statements are divided into two categories, "action" and "expect". When a state is entered, all of its actions are performed in the order in which they appear in the file. A transition to another state may occur for any of three reasons: .ls1,"o" .le;One of the actions may cause a transition to another state, in which case the rest of the current state's actions are skipped. Processing resumes with the first action statement of the new state. .le;If none of the actions cause a state transition, and there are no expects in the state, processing "falls through" to the next state in the file. .le;If none of the actions cause a state transition, but there are expects in the state, the state machine pauses until one of the expects is "satisfied". It then transitions to the state named in the expect statement. .els0 Finally, there are two action statements which, when executed, cause the script to exit. .hl 1 Script File Statements This section describes all of the statements that may appear in script files, except for a few special action statements. Those are described in a later section, "Overriding Defaults". Some statements accept one or two arguments, referred to in the following descriptions as "int", "ns", "str", or "xstr", to indicate whether the argument is an integer, a new state name, a string, or an "extended string" (described in a later section). For {_all}_ statements that accept two arguments, the first is the name of a new state, and the second specifies a condition or reason for changing to the new state. .hl 2 Action Statements .hl 3 Termination and informational statements .lm+17 .spr-17,1,2 log^^^^^xstr^^^^^send xstr to log file. logerr^^xstr^^^^^send xstr to log file, with error indicator. failed^^^^^^^^^^^exit script with "failed" status. success^^^^^^^^^^exit script with "success" status. busy^^^^^^^^^^^^^exit script with "busy" status. .lm0 .spr0,1,2 .hl 3 Sending data .lm+17 .spr-17,1,2 dial^^^^^^^^^^^^^send the string given by the field in the systems entry to the serial port. "W" and "P" characters in the phone number are converted as described under "dial strings", below. This statement also sets a default timeout value, as described under the "timeout" statement. send^^^^xstr^^^^^send the string xstr to the serial port. sendstr^int^^^^^^the argument of this statement is a digit from 0 through 7. Send the corresponding string parameter (, , etc.) from the systems entry (interpreted as an extended string). .lm0 .spr0,1,2 .hl 3 Special terminal Control statements .lm+17 .spr-17,1,2 flush^^^^^^^^^^^^flush the terminal port's typeahead buffer. break^^^^^^^^^^^^send a break signal. hangup^^^^^^^^^^^momentarily drop Data Terminal Ready on the serial port, causing the modem to hang up. (Not usually needed, since CONNEX does this at the end of each call.) .lm0 .spr0,1,2 .hl 3 Counting, branching, and testing statements .lm+17 .spr-17,1,2 sleep^^^int^^^^^^delay for i milliseconds. zero^^^^^^^^^^^^^clear the counter. count^^^^^^^^^^^^add one to the counter. ifgtr^^^ns^int^^^go to state ns if counter greater than i. ifblind^ns^^^^^^^go to state ns if terminal multiplexer does not allow receipt of data when Carrier Detect absent (e.g\. DMF32). ifblgtr^ns^int^^^go to state ns if counter greater than i {_and}_ the terminal multiplexer does not allow receipt of data when Carrier Detect absent (e.g\. DMF32). goto^^^^ns^^^^^^^go to state ns unconditionally. ifstr^^^ns^int^^^go to state ns if string parameter str is nonempty. ifnstr^^ns^int^^^go to state ns if string parameter str is empty. .lm0 .spr0,1,2 .hl 2 Expect Statements Expect statements are usually the last statements that appear in a given state, though in fact they can appear anywhere within the state. Even if they appear at the beginning, the script processor always does all of the action statements first. As a practical matter, the order of these statements is not significant; they are all interpreted "in parallel". .note We have, no doubt unfortunately, used the word "expect" for both a particular statement and for the class of statements which includes {_expect}_, {_timeout}_, and {_ifcarr}_. In the narrative, we will differentiate between the two by underlining the word {_expect}_ to refer to the statement; the unadorned word refers to the statement class. (Alternatives for the class name are hereby solicited!) .end note .lm+17 .spr-17,1,2 expect^^ns^xstr^^change to state ns if the string specified by xstr is received from the serial port. Case is significant, but high-order bits are not checked. ifcarr^^ns^^^^^^^change to state ns if Carrier Detect is true. timeout^ns^int^^^change to state ns if the time (in milliseconds) given by i has elapsed without satisfying any expects. If the time specified is^0, a default timeout value (calculated from the length and other characteristics of the most recent dial string) is used. .lm0 .spr0,1,2 .hl 1 Script Processing Details .hl 2 Extended Strings In the statements that accept string arguments, the strings are interpreted as "extended strings". Extended strings begin with the first non-blank character and continue, including all imbedded and trailing blanks and other white-space, until (but not including) the end of the line in the script file. (There is no provision for line continuation.)~ No trailing spaces should be present between the last "desired" character of the string and the end of the line, as they will be included in the stored string and sent or expected, just as they appear in the script file. And, obviously, no trailing comments are permitted! They will just be stored as part of the string. Within an extended string, the following "escape sequences" will be converted as indicated before being sent or expected: .s .lm+8 .literal \d EOT character (control-D) \N null character \n line feed \r carriage return \s space \t tab \- hyphen \\ backslash \ooo character with value ooo (in octal) .end literal .lm 0 Since extended strings in scripts can include imbedded spaces, tabs, etc., these escape sequences are only required in strings appearing in systems entries, though they may be used in script files to improve readability. The octal-character specification (\\ooo) may have from one to three octal digits; it is terminated either after the third digit or when a non-octal character is encountered. But if you want to specify one of these followed by something that happens to be a valid octal character^-- for example, a control-A followed by a 7^-- make sure to include all three digits after the \\. (\\0017 would become a control-A followed by the Ascii character "7", but \\17 or \\017 would become a control-Y (decimal value 25). \\1S would convert to a control-A followed by an "S".) Extended strings are stored without a trailing carriage return unless one is explicitly present in the string (via \\r). .hl 2 String Parameters The {_sendstr}_ statement sends (after conversion from extended string format) one of the string parameters (, , etc.) in the current systems entry. The parameter is selected by the integer argument of the statement. This allows "generic" script files (such as LOGIN.VMS) to serve for many different systems; the string parameters in the systems entry provide the username, password, etc. Character substitutions described under "extended strings" above are performed on these strings. The {_ifstr}_ and {_ifnstr}_ statements allow further generality in script files, by testing whether a particular parameter is present in the systems entry. For example, a single script, LOGIN.VMS, can be used both for those VMS systems that require a system password and those that do not. The system password is specified as the string parameter in the systems entry; the script tests for this parameter's existence and skips the system password sequence if the parameter is empty. .hl 2 "Wait" and "Pause" Characters in Dial Strings A different conversion is performed on dial strings. Dial strings are {_not}_ interpreted as extended strings. However, the characters "W" and "P" within a dial string are interpreted as "wait for dial tone" and "pause", and may be converted to other characters. By default, "W" is left alone, and "P" is converted to a comma (,); these are appropriate for Hayes-type modems. The dial script may specify other substitutions (see below). .hl 2 Default Timeouts for Dial Strings When a {_dial}_ statement is executed, a default timeout value is set. This is the timeout value used by a subsequent {_timeout}_ statement if the statement specifies a timeout value of^0. The default timeout is given by ctime^+ (ndigits*dgttime)^+ (nwchar*wtime)^+ (npchar*ptime), where ndigits, nwchar, and npchar are the number of digits, wait characters, and pause characters in the dial string, and ctime, dgttime, wtime, and ptime are 45^seconds, 0.1^seconds, 10^seconds, and 2^seconds, respectively. All of these times may be changed as specified below under "Overriding Defaults". .hl 2 Trailing Carriage Returns Not Assumed In the {_dial}_ and {_sendstr}_ statements, the dial string or systems entry string parameter is sent with no trailing carriage return; if a carriage return must be sent after one of these, a separate send statement must provide it. .hl 2 Overriding Defaults The script processor sets several default values. The following statements, which override these defaults, may be useful in certain circumstances. .lm+17 .spr-17,1,2 chrdly^^int^^^^^^Since many modems cannot accept dialing commands at full "computer speed", the script processor sends all strings with a brief inter-character delay. This statement specifies the delay time, in milliseconds. The default is 100 (0.1 second). pchar^^^str^^^^^^Specifies the character to which "P"s in the dial string should be converted. Default is ",", for use with Hayes-type modems. ptime^^^int^^^^^^Specifies the time, in milliseconds, to allow in the default timeout for each pause character in the dial string. Default is 2000 (2^seconds). wchar^^^str^^^^^^Specifies the character to which "W"s in the dial string should be converted. Default is "W", for Hayes modems. wtime^^^int^^^^^^Specifies the time, in milliseconds, to allow in the default timeout for each wait-for-dialtone character in the dial string. Default is 10000 (10 seconds). dgttime^int^^^^^^Specifies the time, in milliseconds, to allow in the default timeout for each digit character in the dial string. Default is 100 (0.1 second). ctime^^^int^^^^^^Specifies the time, in milliseconds, to allow in the default timeout for carrier to appear after the dial string is sent. Default is 45000 (45 seconds). .lm0 .spr0,1,2 .appendix Source Files The source code and related files for CONNEX are as follows: .list "-" .le;CONNEX.C -- the main program; .le;CONMISC.C -- various subroutines; .le;CALL.C -- routines related to call management; .le;SYSDEP.C -- VMS system dependent subroutines; .le;CONNEX.H -- top-level variables and defines; .le;SYSDEP.H -- VMS system dependent definitions; .le;INCLUDES.H -- various definitions; .le;CONNEX.MSG -- message definition file; .le;C.OPT -- linker option file for VAX C; .le;CONNEX.RNO -- this document; .le;CONNEX.MMS -- MMS descriptor file to build CONNEX; .le;BUILD.COM -- simple system build script -- alternative to CONNEX.MMS. .end list CONNEX.MMS recognizes two command-line macros: .list "-" .le;XSCA -- if defined creates .ANA files and loads an SCA library, if defined; .le;DEBUG -- if defined, compiles with /DEBUG/NOOPT and links with /DEBUG switches. .end list