Beginning of File exit for 3270 data streams (APIUBF3)

The Beginning of File exit for 3270 data streams (APIUBF3) receives control when NetSpool starts a new output data set for 3270 input data streams. You can use this exit to do these functions:

• Add up to 275 bytes of printable text and PCL commands to the start of a data set.
• Print data that is wider than 132 characters (up to 255 characters) on the same line.

NetSpool calls the same exit for all LU type 0 and LU type 3 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

If your exit adds printable text and PCL commands, follow these guidelines:

• If NetSpool converts the input data stream to a line data stream:
  • If the printer accepts EBCDIC line data (such as an AFP printer that PSF controls), you can add text. Code the text data in EBCDIC representation, and precede the data with a carriage control character.
  • If IP PrintWay™ controls the printer, you can add text and any PCL commands that your printer supports. Code text data in ASCII representation, and precede the text and PCL commands with a X'35' character followed by a 1-byte length field. IP PrintWay removes the X' 35' and length field before transmitting the text and PCL commands, without change, to the printer.
• If NetSpool converts the input data stream to a PCL data stream:
  • You can add text and any PCL commands that your printer supports. Code text data in ASCII representation. NetSpool and IP PrintWay transmit the text and PCL commands to the printer without change.
  • If you add text, be sure to add a line termination control, such as a Carriage Return/New Line control sequence or a Form Feed control, after the text data to make sure that subsequent text starts either on a new line or page.
• Any PCL commands that you add in this exit override 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 print density or line density values.

Input to APIUBF3

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.

S2PLUNAM

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

S2LPTNAM

Name of the printer LU that NetSpool is processing — secondary LU (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 APIUBF3

At return from the Beginning of File exit (APIUBF3), restore the contents of all registers, and place one of these return 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.

You can set these fields in the APIPP1X2 control block:

S2WRKLEN

Length of work area S2WRKARA.

S2WRKARA

Data and PCL commands to be added to the output data stream.

S2OUTFLG

Flags to customize the line data and PCL output data streams that NetSpool creates:

S2VLN255

Set this flag if you want to print data that is wider than 132 characters (up to 255 characters) on the same line, without wrapping characters to the next line. If this flag is set, NetSpool sets the maximum line length with variable length line format to 255 characters (not including carriage control). If this flag is not set, NetSpool sets the maximum line length to 132 characters. This flag is ignored for Double Byte Character Set (DBCS) data.

Tip: The Write Control Character (WCC), which is the second byte in the first RU of a chain, sets the variable length line format.

Examples

1. To add no data, set return code 2 in register 15.
2. To add data and PCL commands:
   • Put the data and PCL commands in the S2WRKARA field.
   • Put the length of field S2WRKARA in the S2WRKLEN field.
   • Set return code 1 in register 15.
3. To print data wider than 132 characters without adding data or PCL commands:
   • Set flag S2VLN255.
   • Set return code 2 in register 15.