PDRREF:DBIDI Command Structures and Command Flow
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
All structures used by PrtQuery and PrtSet use offsets into the return buffer for variable-length data, instead of returning pointers. These offsets are used to make transmission of the bidirectional structures easier between processes and machines.
For example, in a structure that returns a description string, the field that references the storage location of this string is a ULONG. If zero, that string is not returned. If nonzero, the field is the offset, from the beginning of the output buffer, to the description string.
All structures with variable-length data should pack this data immediately following all the fixed-length structures. As a result, *pcbOutData contains the number of bytes to copy from the beginning of the pOutData buffer.
- Note
- All returned structure-offset fields are offsets from the beginning of the output buffer given, not offsets from the beginning of the structure.
The Query and Set command structures are listed in the following two tables. The tables show which part of the system is called for each command structure. The values indicate the following:
- A PrCo in the "Sent To" column indicates that the protocol converter is called first.
- A PDrv indicates that the port driver is called first.
- If both are called, they are listed in the order called.
The numbers in the "Init Sequence #/Description" column indicate, across both the Query and the Set tables, the order in which these command structures are called.
| Query Command | Command Code | First Sent To: PrCo/PDrv |
Init Sequence # and Description |
|---|---|---|---|
| BIDI_Q_CONVERTER_INFO | (8021h) | PrCo | |
| BIDI_Q_Device | (800Dh) | PrCo; PDrv | |
| BIDI_Q_FONTS | (8012h) | PrCo; PDrv | |
| BIDI_Q_INPUTBINS | (800Fh) | PrCo; PDrv | |
| BIDI_Q_INTERPRETER | (800Eh) | PrCo; PDrv | |
| BIDI_Q_JOBID | (8017h) | PrCo | During PrtOpen, after BIDI_STARTJOB |
| BIDI_Q_JOBS_COMPLETE | (8013h) | PrCo; PDrv | |
| BIDI_Q_JOBS_QUEUED | (8014h) | PrCo; PDrv | |
| BIDI_Q_OUTPUTBINS | (8010h) | PrCo; PDrv | |
| BIDI_Q_PORT | (800Bh) | PDrv | 2 - Determines protocol converter to use |
| BIDI_Q_PORTDRV | (8019h) | PDrv | Free-format buffer |
| BIDI_Q_RESPONSE_FMT | (8018h) | PrCo | 5 - Gets printer msg format |
| BIDI_Q_SPOOLER_VERSION | (8022h) | Handled by spooler | |
| BIDI_Q_STATUS | (8015h) | PrCo; PDrv | |
| BIDI_Q_STORAGE | (8023h) | PrCo; PDrv | |
| BIDI_Q_SW | (800Ch) | PrCo | 7 |
| BIDI_READ_ALERT | (801Dh) | PrCo | |
| BIDI_READ_PASSTHRU | (8001h) | PrCo | Copies SplProtXlateCmd data |
| BIDI_WAIT_ALERT | (8016h) | PDrv | 3 - One thread per port driver |
┌──────────────────────────┬────────┬──────────┬─────────────────┐ │Set Command │Command │First Sent│Init Sequence # │ │ │Code │To: │and Description │ │ │ │PrCo/PDrv │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_ADD_VIRTUAL_PORT │(26h) │PDrv │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_CANCELJOB │(6h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_DEL_PORT │(28h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_DEL_VIRTUAL_PORT │(27h) │PDrv │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_DISABLE_ALERT │(25h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_ENABLE_ALERT │(24h) │PrCo; PDrv│9 │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_END_PASSTHRU │(1Bh) │PrCo │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_ENDJOB │(3h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_HOLDJOB │(4h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_INIT │(Bh) │PDrv │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_INIT_PORTDRV │(8h) │PDrv │1 - Once per │ │ │ │ │PortDRV │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_INIT_PROTCNV │(Fh) │PrCo │4 - Given Q_PORT │ │ │ │ │for each port │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_NOTIFY_ENDJOBCONNECT │(20h) │PDrv │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_NOTIFY_PORT_RELEASED │(22h) │PDrv │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_NOTIFY_PORT_SELECTED │(21h) │PDrv │10 │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_PACKET_SIZE │(Eh) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_RELEASEJOB │(5h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_RESPONSE_FMT │(Dh) │PDrv │6 │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_RESET │(9h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_SEND_PASSTHRU │(1h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_SET_DEVICE_ID │(23h) │PDrv │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_SET_PORTDRV │(19h) │PDrv │Free-format │ │ │ │ │buffer │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_SET_SW │(10h) │PDrv │8 │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_SHUTDOWN │(Ah) │PrCo; PDrv│Sent to both │ │ │ │ │protocol │ │ │ │ │converter and │ │ │ │ │port driver │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_START_PASSTHRU │(1Ah) │PrCo │ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_STARTJOB │(2h) │PrCo; PDrv│ │ ├──────────────────────────┼────────┼──────────┼─────────────────┤ │BIDI_TERM │(Ch) │PrCo; PDrv│ │ └──────────────────────────┴────────┴──────────┴─────────────────┘
Protocol Converters
A protocol converter is a DLL written to support printers that are capable of returning information to the host PC. A protocol converter is responsible for understanding the control language of the printer. Examples of control languages are as follows:
- Network Printer Alliance Protocol (NPAP)
- Printer Job Language (PJL)
- Simple Network Management Protocol (SNMP)
The file type of a protocol converter is ".CNV". The protocol converter does not get involved in the physical transmission of commands or data to the printer. The converter will generate appropriate printer commands to send to the printer, and the converter is able to translate the data sent from the printer to the host PC.
Developers can write a protocol converter if they have a port driver that can communicate with a group of printers that does not yet have a protocol converter. See the "Bidirectional Communications" chapter in the Printer Device Driver Reference for OS/2 for more information.
The functions exported from a protocol converter are as follows:
- SplProtSendCmd
- SplProtXlateCmd
- Note
- SplProtWrite is an optional function that can be exported from a protocol converter.
A protocol converter is installed in a system by adding the following entry to the system .INI file:
AppName = PM_PROTOCOL_CONVERTER KeyName = ConverterName Example: "PJL", "NPAP" KeyValue = Path to converter Example: "C:\OS2\DLL\PROT.CNV"
Printer Control Panels
A printer control panel is a DLL written to display the current status of a printer. Optionally, this DLL also allows a user to change the front panel settings for a printer that can communicate bidirectionally with the OS/2 print subsystem.
This printer panel DLL is called when the user selects the "Printer Panel" menu item on a print object that is connected to a printer communicating bidirectionally with the OS/2 print subsystem.
The file type of a printer control panel is ".DLL". The printer control panels make use of the PrtQuery and PrtSet APIs to get current status of printers. See the "Bidirectional Communications" chapter in the Printer Device Driver Reference for OS/2 for more information.
The functions exported from a printer control panel are as follows:
- SplQueryControlPanel
- SplRegisterControlPanel
A protocol converter is installed in a system by calling SplRegisterControlPanel. This adds the following entry to the system .INI file:
AppName = PM_SPOOLER_CONTROL_PANEL KeyName = ControlPanelName Example: "NewPrinter" KeyValue = Path to DLL with ctrl panel Example: "C:\OS2\DLL\CPANEL.DLL"
The print object typically calls SplGetControlPanelList, which causes the spooler to call the API SplQueryControlPanel for each installed printer control panel, in order to determine if the printer panel DLL can display a control panel for the given printer.
The print object gives the list of printer panel names to the user and, after one is selected, the print object will call SplDisplayControlPanel.