If you are a PC programmer, you can change your programs to use the PRINT370 device drivers to send print data to S/390 channel printers. Chapter 9 describes the PRINT370 device drivers. This appendix describes how to develop the device driver interface.
Because you cannot load the Barr base software and device drivers at the same time, this works best when you do not use software such as BARR/RJE, BARR/SPOOL, or BARR/AFP.
When you install the PRINT370 device drivers, they create a new DOSdevice that your programs can access like any standard DOS device, such as LPT1. There are two ways your program can access the device drivers:
IOCTL method – The PRINT370 device drivers can accept standard IOCTL calls from applications you write in Assembler or any other language that can access DOS functions. These calls include Open Device/File, Close, Write Status, and Write.
High-Level Language method – You can use high-level programming languages such as C to open, write to, and close the device driver.
The IOCTL method or a combination of both methods is preferred. If you use only the high-level language functions, you might not be able to perform some operations.
When you develop the interface to the PRINT370 device drivers, follow these guidelines.
Your program must open the device driver with binary or raw mode. When applications pass data to the device, binary mode prevents DOS from examining each character and removing non-printable characters as it does with ASCII mode. This dramatically improves performance.
If you are using IOCTL calls, perform the IOCTL call after the open call by issuing IOCTL: Set Device Information, DOS Function 4401 with Device Information Bit 5 ON (binary mode).
If you are programming in C, pass WB as the mode of the fopen call.
Your program should perform a Write Status call before writing data to the device driver. If the call returns the Busy status, the application should wait before writing the data. If the program attempts to write while the device is in a Busy state, the device driver waits until enough internal data space is freed to hold the data from the write operation, and then the driver returns to the application. The wait can last several minutes if the output device is in an error state, such as out of paper.
The ability to check the write status is helpful if your application program is CPU-intensive or if you cannot allow the write call to wait before returning. When your program receives a Not Busy reply to the WriteStatus call, it can pass up to 500 bytes of data to the device driver.
C programmers might need to code a new function to perform the IOCTL call. There is no generic C call to retrieve the write status. An example C call to perform the IOCTL Write Status call is shown below.
Your program should write data to the device driver in 500-byte pieces or less. If your program attempts write operations with more than 500 bytes of data, the Write call is not guaranteed to return immediately. The program should issue a Write Status call before writing data. If the Write Status returns a Not Busy status, the device driver guarantees that a write of 500 bytes will return immediately.
Because the device driver uses internal buffering, the last block of data written to the device driver cannot be printed until the device driver is closed. Then all data is flushed to the printer.
The PRINT370 device drivers accept the following file formats: ASCII, Barr S/370, Xerox LPS, Xerox Interpress, and Xerox Metacode. S/370 format is preferred because it is the most efficient.
Applications can use the printer address to obtain the printer’s current status. Because none of the functions within the DOS IOCTL function set allow character devices to obtain this information, the device driver implements a back door. Only those applications that can call DOS interrupts can use this feature.
To obtain the Printer Status information, use the DOS multiplex interrupt (2F), which allows applications to communicate with each other.
Use the registers and values in Table D-1 to program the Printer Status call. The Printer Status call returns information to two register pairs, as shown in Table D-2, and returns status bits to the DX register, as shown in Table D-3.
Table D-1. Calling Conventions
|
Register |
Value |
Description |
|
AH |
EE |
Multiplex Number (ID of listening program). Barr software uses hexadecimal EE. |
|
AL |
0F |
Obtain Printer Status function |
|
CL |
nn |
Address of printer |
Table D-2. Register Pair Returns
|
Register Pair |
Description |
|
DS:SI |
Pointer to Error Text Description (15 bytes long); only valid during an error condition. |
|
ES:DI |
Pointer to Sense Bytes (24 bytes of sense data last received); only valid during a sense error. |
Table D-3. Register Status Bits
|
Register |
Status Bits (hexadecimal)* |
Description |
|
DX |
0080 |
Sense Error, sense bytes are valid |
|
|
0008 |
Other Error review text description only |
|
|
0020 |
Device is currently active |
*All other bits are reserved and might or might not be ON.
Do not modify any of the data pointed to by DS:SI or ES:DI. If this data is modified, the device drivers could fail. The active bit (0020 in the DX register) is reset once a second, making it possible for active to be indicated with other error conditions. During any error condition, the Text Description is the driver interpretation of the error and the sense bytes are the last sense bytes received from the device. The sense bytes reflect the current state of the device when the sense error bit is indicated.