Printers

Printers are used to produce formatted output; they are typically used where the output required is to be printed. The data sent to a printer device includes control characters that provide the necessary formatting information. This formatting information is provided by the host; in addition, the following SNAP-IX options can be used to control the format of printer output:

Vertical Presentation and FCBs

The vertical page layout of printer data can be determined by a Forms Control Buffer (FCB) included in the SNAP-IX RJE workstation style file. An FCB defines the following:

• The length of the output form (page), given as the maximum number of lines that can be printed on it

• The first and last line positions at which data should be printed (for example, a first line of 3 implies a top margin of 2 lines)

• Vertical channel positions, which specify 'vertical tab' positions at which data should be printed on the page

The definition of a printer device for an RJE workstation, in the RJE workstation style file, specifies a default FCB. This FCB defines the page layout used to print output data, unless the host overrides it as follows:

• The host can specify in a Peripheral Data Information Record (PDIR) the name of an FCB to be used (see Peripheral Data Information Records). If this matches an FCB defined in the SNAP-IX RJE workstation style file, this FCB is used instead of the default.

• The host can include a Set Vertical Format (SVF) control character in the data. This sets the page format explicitly, and overrides any layout specified by an FCB.

Code Conversion

The definition of a printer in the RJE workstation style file provides the option of converting the code of the received data from EBCDIC to ASCII, or receiving it without translation. A separate option is provided for converting transparent data (data that is marked by control characters to indicate that it should be received without checking for further control characters). Typically, the default of code-converting both transparent and nontransparent data is used.

For details about the translation table used for this conversion, see Code Conversion Table.

Punches

Punch devices are used to produce unformatted 'raw data' output, such as simple text files, as opposed to the formatted output produced by printers. For example, if RJE is used to retrieve a file that has been sent to the host for storage, the data is generally sent to a punch device. The data consists of variable length records, usually up to 80 bytes. (Some host job entry systems allow a different maximum record length.) The following options control punch device output:

Code Conversion

The definition of a punch in the RJE workstation style file provides the option of converting the code of the received data from EBCDIC to ASCII, or receiving it without conversion. A separate option is provided for converting transparent data (data that is marked by control characters to indicate that it should be received without checking for further control characters). Typically, the default of code-converting both transparent and nontransparent data is used.

For details of the translation table used for this conversion, see Code Conversion Table.

NL Option

The punch definition also provides the option of inserting a new-line (NL) character after each received record or of receiving the data as a continuous sequence of bytes. When the option of inserting NL characters is selected, SNAP-IX also inserts an NL character if a received record exceeds the record length specified by the host (normally 80 bytes), thus breaking the data up into lines of not more than the record length specified by the host.

Binary Output

By disabling both 'NL between records' and code conversion, you can ensure that the data written to file is exactly the same as the data sent by the host.

Exchange Devices

Host job entry subsystems normally handle data as punch data-in 80-byte data records, as it would be read from standard 80-column punched cards. Some host systems can also handle exchange data, which would be read from other types of input device and is normally in 128-byte data records. There are two types of exchange data:

• Transmission Exchange, which is similar to punch data except that the records are normally 128 bytes instead of 80 bytes

• Basic Exchange, which is not record-oriented and is generally used only for binary output

When the host sends output data as exchange data, it specifies a particular exchange device to which the output is to be routed. SNAP-IX supports exchange devices by routing any output for exchange device n to punch device n. For example, if the host specifies that an output device is exchange device number 3, output for this exchange device is sent to punch number 3. See The RJE Workstation Style File, for more information about configuring RJE punch devices.

The options for controlling exchange device output are the same as for punch output, except that the record length (defined by the host) is normally 128 bytes.

PDIR Parameters

A PDIR consists of the following parameters; note that some hosts may not include all of these parameters:

DATE

The date of creation of the host data set (host file) being sent as output data. This is in the format MM/ DD/YY (month, day, year).

TIME

The time of creation of the host data set (host file) being sent as output data. This is in the format HH. MM.SS (hours, minutes, seconds).

FORMS

The name (up to eight EBCDIC characters) of the printer forms to be used. Blank indicates 'use the standard forms.'

FCBNAME

The name (up to eight EBCDIC characters) of the FCB to be used to format the output. If this name matches the name of an FCB configured for SNAP-IX, this FCB is used to process the output; otherwise it is ignored. Blank indicates 'use the default FCB.'

TRAIN

The name (up to eight EBCDIC characters) of the printer train to be used. Blank indicates 'use the standard train.' Historically, this field was used to identify the printer train that the job would use. The field now can be used for other purposes. Consult your System Administrator to determine how the field is used.

COPIES

The number (shown in EBCDIC characters) of additional copies of the printed output to be produced. SNAP-IX uses 0 (zero) to indicate 'print only one copy,' 1 to indicate two copies in total, and so on.

VOLIO

An indication of the volume of output produced (shown in EBCDIC characters). Note that this provides information only about the relative sizes of different jobs.

JOBNAME, STEPNAME, PROCSTEP, DDNAME, SPINNO

These five parameters make up the DSNAME parameter used by the host to identify the job. Many host systems use only JOBNAME and do not include the remaining parameters.

REQID

PDIR request identifier. This takes one of the following values:

0 (zero)

Standard PDIR

1

Job separator PDIR

2

System message PDIR

PDIR File Format

When PDIR information is retained for use in processing output, it is stored in files with a fixed format. Sample PDIR File, shows an example of a PDIR file.

Sample PDIR File

   0 OPEN  WKSTPRT1
   0 PDIR  11/14/91 18.28.46 STD  STD6  QN  0  30  NEWJOB1  None None None   None 0
1054 PDIR  11/14/91 18.28.46 STD  STD6  QN  0  50  NEWJOB1  None None None   None 1
2835 CLOSE

The first column of the PDIR file indicates the byte offset into the output data at which the information was received.

The first line of the file is OPEN, shown at offset 0 (zero). This line includes the RJE device name, which is a combination of the workstation name and the device identifier (PRT n for printer number n, or PUNn for punch number n or exchange device number n).

The last line of the file is normally CLOSE, indicating the end of the data. If the received data was truncated but the truncated data was not discarded (either because data was being appended to a file, or because the workstation was configured to keep failed files), this line contains CLOSE ERROR instead of CLOSE.

Other lines of the file are PDIR followed by a list of the PDIR parameters as described above. If any of the PDIR parameters from the host are left blank, SNAP-IX inserts the string None. The format of each line is as follows:

Program Output without PDIRs

Once the output from the host has been received successfully, the output program is started without parameters; the data from the host is piped as standard input to the program. For example, the data could be piped to the Solaris print spooler lp, or to a shell script which calls lp with suitable parameters.

Program Output with PDIRs

Once the output from the host has been received successfully, the output program is started. The parameters from the first PDIR received with the data are passed as parameters to the output program, and the data from the host is piped as standard input to the program. In other words, the host data is piped to:

programname DATE TIME FORMS FCBNAME TRAIN COPIES VOLIO JOBNAME STEPNAME PROCSTEP DDNAME SPINNO

The program can then use the PDIR parameters to determine how to process the data.

For example, the following shell script calls the print spooler lp with different options according to the form name and number of copies specified by the FORMS and COPIES parameters. (Note that COPIES is the number of additional copies, not the total; COPIES =0 represents 1 copy.)

#
copies=`expr $6 + 1`
cat | lp -f$3 -n$copies

If this script, named myprog, is called with the PDIR parameters in the example PDIR file shown in Sample PDIR File, the host output would be piped to:

myprog 11/14/91 18.28.46 STD STD6 QN 0 30 NEWJOB1 None None None None

The script myprog would then calculate the number of copies as 1, and pipe the output to:

lp -fSTD -n1

If the host sends additional PDIRs with the data, the RJE workstation uses the information in each PDIR to process the data as it is passed to the program, although the PDIR itself is not passed to the program. For example, if the host sends a second PDIR to change the FCB name part-way through the data, the new FCB name is not passed to the output program, but the RJE workstation uses the information from the new FCB (page length, first and last lines, and vertical channel positions) when processing the data passed to the output program.

General Guidelines for Output Programs

The program runs with the user and group ID of the primary user and group of the workstation, as specified in the SNAP-IX configuration. The program inherits the environment in which it runs from the user who started the workstation. However, it is preferable to set any required environment variables explicitly from within the program, rather than relying on the inherited environment. Similarly, if the program needs to access files, be sure the program specifies the full path of the file to open (rather than relying on the environment).

Do not send output to the screen (which is the default for standard output and standard error). If the program uses standard output and standard error, they should be re-routed (for example, to a file).

The program should return the value 0 (zero) if it completes successfully or a nonzero value otherwise. A shell script returns the exit code from the last Solaris command executed, unless you use the exit command to return an explicit value. An executable program must use either the exit call or return call to return an explicit value.