Open Communications

The Open communications (OPE) statement equates a file number in a program with a serial port used for communications. Through asynchronous communications, Business Rules! programs can send data to and receive data from other computers using serial communications ports.

1.) DOS versions of Business Rules use the value of the WAIT parameter as the maximum number of seconds to wait for a device to accept each output character. Once this maximum is reached, the system will generate an I/O error. Previously there was no timeout for DOS communications output.

2.) When a file is opened for both SHR and INPUT, Business Rules! will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error 0608 will result. This will affect current programs.

See also Communications.

Comments and Examples

A "communications file" is defined as a display file with two special characteristics in its OPEN statement:

1.) It must include FORMAT=ASYNC.

2.) Its name must be a valid specification for a serial port.

The syntax for the OPEN communications statement consists of many of the parameters for the OPEN display statement, plus several optional communications parameters (e.g., parity, stopbits). As communications files have several options that are not available for other display files, their syntax is explained in a separate syntax diagram. The following are examples of OPEN statements for communications files that use the defaults for all of the optional parameters:

00100 OPEN #1: "NAME=COM1:,FORMAT=ASYNC",DISPLAY,OUTIN ! for IBM PC
00200 OPEN #2: "NAME=:/dev/tty22,FORMAT=ASYNC",DISPLAY,OUTIN ! Unix

OUTIN on a communications file allows INPUT, LINPUT and PRINT statements to be used with the same file number. OUTIN is generally necessary for proper line initialization to be sure the modem connections have been successful. OUTIN is valid only for communications files; other display files cannot use this option.

Unix and Linux communications ports are file names which usually begin with tty and are located in the /dev directory. They must not be enabled for logins. In line 30 below, notice the colon (:) after the NAME= keyword. This colon is required for Business Rules to accept a Unix / Linux file name.

00030 OPEN #3: "NAME=:/dev/tty33,FORMAT=ASYNC",DISPLAY,OUTI N

Some optional parameters for the OPEN communications statement are unique to communications: BUFSIZE=, BAUD=, PARITY=, DATABITS=, STOPBITS= and RETRY= are unique to communications file processing. Some other optional parameters are also used for display files: RECL=, WAIT=, TRANSLATE= and EOL=.

As of version 4.0, Business Rules now opens serial ports to 9600 bits/second, with no PARITY, eight data bits, one stop bit (an exception is that communications files default to 1200 bits/second). Formerly, the default was 300 bits/second.

After an OPEN statement, INPUT, LINPUT, PRINT and CLOSE statements may be used with communications files. Their usage is very similar to the way they are used with other display files, see each for information about their general use.

Syntax

Defaults

1.) RECL=132.

2.) BUFSIZE=2000 for DOS, N/A for Unix / Linux.

3.) BAUD=1200.

4.) PARITY=N.

5.) DATABITS=8.

6.) STOPBITS=1.

7.) RETRY=5.

8.) Wait 15 seconds.

9.) No translation.

10.) EOL=CRLF for DOS, EOL=LF for Unix / Linux.

11.) Interrupt the program if an error occurs and ON error is not active.

Parameters

The required "file-num" parameter is a numeric expression that must be equal to 255 or between 1 and 127, inclusive.

"NAME = port" is a required parameter which specifies the serial communications device. For DOS systems, COM1: and COM2: are automatically supported as communications ports. COM ports 3-8 may be assigned (see the COM specification in the BRConfig.sys chapter for more information). For Unix / Linux systems, communications ports are file names which usually begin with tty and are located in the /dev directory. These device names must be preceded by a colon, must use forward slashes (/) in the path, must exactly match the uppercase/lowercase pattern in the Unix / Linux directory listing, and should use the full absolute pathname.

As with other display files, the "RECL" parameter specifies the maximum number of characters that can be output before EOL characters (see EOL= below) are added to the data stream. "RECL" has no effect on input processing.

"FORMAT=ASYNC" indicates that the data is to be transmitted as is, without any special or enveloping protocol.

On Unix / Linux versions, the "BUFSIZE" parameter is ignored since all buffering is handled by the Unix / Linux operating system. On DOS versions, "BUFSIZE" specifies the size of the buffer. The default is 2000 bytes, which is small for high-speed data transmission. At 2400 bits/second, this default buffer will fill up every 8.3 seconds. When the buffer fills, additional data will be lost unless input or output statements are executed fast enough to keep ahead of the buffer. For rates of 2400 bits/second or higher, you probably should increase the BUFSIZE default.

The "BAUD" parameter sets the transmission speed in bits per second. The default is 1200 bps. The valid baud rates for DOS and NetWork versions are 110, 150, 300, 600, 1200, 2400, 4800 and 9600. The valid baud rates for Unix / Linux versions are 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800 and 9600. BR now supports extended communications speeds which test the limits of conventional serial IO hardware. In particular, the following baud rates are permitted:

       19200      38400      57600      115200

The "PARITY" parameter establishes the parity setting to be used for communications. One of three values may be specified: N (no parity checking), E (even parity) or O (odd parity). The default is PARITY=N.

"DATABITS" defines the word length or number of data bits for communications. It must be set to one of two values 7 or 8. The default is DATABITS=8. For binary files (including .BRO and .BR files), you should always use 8 data bits.

The "STOPBITS" parameter defines the character terminator to be either 1 or 2 stop bits for communications. The default is STOPBITS=1. Normal operation of most asynchronous modems requires the total of data bits, parity bit and stop bits to equal 9.

The "WAIT" parameter specifies how many seconds to wait for a complete record to be received before generating error code 4271 (incomplete record received). The default is WAIT=15. See Communications for a more detailed explanation.

For formats with error detecting protocols, the "RETRY" parameter specifies how many times to attempt to send or receive the record before generating an I/O error. The default is RETRY=5.

The "TRANSLATE = file-ref" parameter can be used to perform character-by-character translations as data is input from or output to a file. A typical use would be reading and writing EBCDIC files. The file-ref is the name (and optional path) of the file that contains the translate table. The translate feature can also be used with internal, external and display files. See File I/O for more information about TRANSLATE=.

The optional "EOL" parameter defines the end-of-line separator (record delimiter) for the data file being opened. It specifies the character(s) to be sent at the end of every record (after RECL characters have been printed and at the end of each normal print line). EOL must be set to one of the three values: CRLF (carriage return and line feed), LF (line feed only), or NONE (no characters are added or removed). If CRLF or LF is specified during input processing, record delimiters determine whether a complete record has been read (see Communications for more information about record processing). LINPUT, rather than INPUT, should be used with EOL=NONE. LINPUT will read characters until the maximum string length is reached. If either CRLF or LF is specified, then both are accepted as valid record delimiters for input, and are removed from incoming data.

With the exception of the #filenum parameter, all the parameters described above form the file identification string and can be replaced with a "string expression" (see the bottom path of the syntax diagram) that specifies the required information. This string constant, string variable, or string expression must include the NAME= and FORMAT=ASYNC parameters. The other parameters are optional to override default values.

The required "DISPLAY" parameter identifies the communications file as a type of display file. As is mentioned above, the syntax for communications files and other display files cannot be interchanged.

Either "INPUT" or "OUTIN" are allowed to indicate how information will be transmitted through the communications port (OUTIN is generally preferred). The OPEN communications statement allows error processing with the "error-cond line-ref" parameter. See the Error Conditions chapter for more information.

Technical Considerations

1.) Blanks are not allowed before the equal sign in OPEN statement parameters.

2.) Parameter items enclosed in quotes are not checked, syntactically, until program execution. Also, the distinction between uppercase and lowercase is ignored in OPEN statements, including in the "NAME=..." parameter.

3.) When LINPUT is used while EOL=NONE is active, Business Rules reads data from the input buffer until one of the following occurs:

• The variable is full.
• A timeout occurs on a communications file (on a non- communications file, Business Rules will read until the buffer is empty.

5.) During output, if the number of characters exceeds the value specified in the RECL= clause, the characters defined in the EOL= clause are inserted in the data stream. For example, with RECL=132 (the default) and EOL=CRLF (the DOS default), if a PRINT statement outputs 150 characters, CRLF will be inserted after 132 characters and again after the 150th character. When the output is to a 132-column printer, this will look as if a "wrap around" occurred at the end of the first 132- character line. When the output is to a file, this will result in two records being written to the file (since the one output string has two EOLs in it)

6.) RECL has no effect on input processing. With RECL=132 (the default), it is still possible to input strings longer than 132 bytes (provided the input variables are dimensioned large enough). When EOL=NONE is specified, input processing in LINPUT and INPUT statements is terminated by the dimensioned length of the string variables. When EOL=CRLF or EOL=LF is specified, input processing in LINPUT and INPUT statements continues until the EOL characters in the file are found.