Beginning of File exit for SCS data streams (APIPPTD1)

The Beginning of File exit for SCS data streams (APIPPTD1) receives control when NetSpool starts a new output data set for SCS input data streams. You can use this exit to add up to 275 bytes of data to the start of a data set or to close the VTAM® session with the printer.

NetSpool calls the same exit for all LU type 1 sessions. However, your exit can do different functions based on these input fields in the APIPP1X2 control block:

• S2FLAGS: Type of output data stream NetSpool creates for this printer— a line or PCL data stream
• S2LPTNAM: NetSpool printer name, also known as the secondary LU (SLU) name
• S2PLUNAM: LU name of the VTAM application, also known as the primary LU (PLU) name
• S2PRTCLS: LU classes to which the NetSpool printer belongs

You can use this exit to add SCS controls, printable text, and PCL commands. Follow these guidelines when you add data:

• You can add any SCS controls that NetSpool supports. For more information about using LU classes, see z/OS Infoprint Server User’s Guide.
• If IP PrintWay™ controls the printer, you can add text data and any PCL commands that your printer supports as transparent data. Code text data in ASCII representation, and precede text and PCL commands with an SCS Transparent (TRN) control — X' 35' followed by a 1-byte length field. Either NetSpool or IP PrintWay removes the SCS TRN control before transmitting the text and PCL commands, unchanged, to the printer.
• If you add transparent data in a TRN control, you might need to adjust the column and line number of the next print position. By default, when NetSpool finds a TRN control, NetSpool increases the column and line number at which the next character prints by the length of the transparent data, as specified in the TRN control. In your exit, you can change the column and line number where the next character after the transparent data prints. To assist in calculating the desired line and column numbers, NetSpool provides the exit with the column and line number of the next print position before any transparent data is added.
• Any PCL commands that you add in this exit override any PCL commands specified in the IP PrintWay Document header field in the printer definition. They also override any PCL commands that NetSpool automatically generates as a result of PCL conversion values specified in the printer definition, such as the print density or line density.

Input to APIPPTD1

At input to the Beginning of File exit (APIPPTD1), the contents of the registers are:

Register 1

Address of the APIPP1X2 control block

Register 13

Address of an 18-word save area for saving the caller's registers

Register 14

Return address

The APIPP1X2 control block is described in Figure 20. These fields are valid at entry:

S2FLAGS

Type of conversion and VTAM session:

S2LU1

Set for VTAM LU1 session. Not set for VTAM LU0 or LU3 sessions.

S2PCL

Set when NetSpool will convert the input data stream to a PCL data stream.

S2COL

The column number of the next print position

S2LM

Left margin column number

S2RM

Right margin column number

S2MPP

Maximum presentation position (line length)

S2LINE

The line number of the next print position

S2TM

Top margin line number (channel 1)

S2C2T12

Channel 2-12 line numbers

S2BM

Bottom margin line number

S2MPL

Maximum page length

S2PLUNAM

LU name of the application generating the print request (PLU).

S2LPTNAM

Name of the printer LU that NetSpool is processing (SLU).

S2PRTCLS

Logical unit classes to which the printer LU belongs. Each bit in this field represents a class, with the high order-bit of the leftmost byte representing class 1. For a description of the bits, see Figure 20.

Output from APIPPTD1

At return from the Beginning of File exit (APIPPTD1), restore the contents of all registers, and place one of these codes in register 15 to tell NetSpool what action to take:

Code

Meaning

1

Add the data from S2WRKARA to the output data set.

2

Do not add data from S2WRKARA to the output data set.

4

Close the VTAM session for this printer LU.

8

Do not call exit APIPPTD2 for any transparent data found in the data stream for this output data set. Do not add data from S2WRKARA to the output data set.

9

Do not call exit APIPPTD2 for any transparent data found in the data stream for this output data set. Add the data from S2WRKARA to the output data set.

Also, set these fields in the APIPP1X2 control block:

S2DBCSM

The number of character positions NetSpool is to allocate in an output line for each double-byte character.

Value

Meaning

0

Allocate two print positions for each DBCS character. This is the default value set by NetSpool.

1

Allocate only one print position for each DBCS character.

S2NCNUM

The column number of the next print position after the transparent data. If this field is zero, NetSpool determines the column number.

S2NLNUM

The line number of the next print position after the transparent data. If this field is zero, NetSpool determines the line number.

S2WRKLEN

The length of the data in the work area, S2WRKARA.

S2WRKARA

The transparent-data control (TRN) and data to be added to the data stream. You can also add other SCS controls that NetSpool supports. Valid controls are described in z/OS Infoprint Server User’s Guide.

Examples

1. To add no data to the beginning of the data set, set return code 2 or 8 in register 15.
2. To add data to the beginning of the data set:
   • Put the data in the S2WRKARA field.
   • Put the length of the data in S2WRKARA into the S2WRKLEN field.
   • Set return code 1 or 9 in register 15.