Jump to content

PDRREF:DBIDI Command Structures and Command Flow: Difference between revisions

From EDM2
Newer edit →
Created page with "{{PDRREF}} {{IBM-Reprint}} All structures used by PrtQuery and PrtSet use offsets into the return buffer for variable-length data, instead of returning pointers. These offset..."
 
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
Line 2: Line 2:
{{IBM-Reprint}}
{{IBM-Reprint}}


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.  
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.  
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.  
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.  
;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:  
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 PrCo in the "Sent To" column indicates that the protocol converter is called first.  
*A PDrv indicates that the port driver is called first.
*A PDrv indicates that the port driver is called first.  
*If both are called, they are listed in the order called.
*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.  


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.
{|class="wikitable"
!Query Command||Command Code||First Sent To:<br/>PrCo/PDrv||Init Sequence #<br/> 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
|}


<PRE>
<PRE>
┌──────────────────────────┬────────┬──────────┬─────────────────┐
│Query Command            │Command │First Sent│Init Sequence #  │
│                          │Code    │To:      │and Description  │
│                          │        │PrCo/PDrv │                │
├──────────────────────────┼────────┼──────────┼─────────────────┤
│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 #  │
│Set Command              │Command │First Sent│Init Sequence #  │

Revision as of 00:48, 20 November 2019

Presentation Device Driver Reference for OS/2
  1. Introduction to OS/2 Presentation Drivers
  2. Design Considerations for All Drivers
  3. Graphics Engine/Presentation Driver Design Changes
  4. Design Considerations for Display Drivers
  5. Design Considerations for Hardcopy Drivers
  6. Display Drivers
  7. Distributed Console Access Facility (DCAF) Architecture
  8. Graphics Engine Hardcopy Drivers
  9. Queue Drivers
  10. Port Drivers
  11. Presentation Manager Function Categories
  12. Exported Driver Function Reference
  13. Mandatory and Simulated Graphics Engine Function Reference
  14. Device Support Function Reference
  15. DBIDI Command Structures and Command Flow

Appendixes

A - OS/2 Version Compatibility Considerations
B - Syntax Conventions
C - Format of the Journal File
D - Bit-Map Simulation for 16-Bit Hardcopy Drivers
E - Data Types
F - Notices

Miscellaneous

G - Glossary

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.

Retrieved from "https://www.edm2.com/index.php?title=PDRREF:DBIDI_Command_Structures_and_Command_Flow&oldid=65088"