HP OpenVMS Systems Documentation
Content starts here

VMS DECwindows Device Driver Manual
Previous Contents Index

A.8 Class Vector Table

The class vector table (IK$VECTOR or IM$VECTOR) data structure contains vectors to the routines of the class driver module (see Figure A-12). The driver builds the data structure using the $VECINI, $VEC, and $VECEND macros. Table A-10 lists and defines the fields of the data structure.

Figure A-12 Class Vector Table Data Structure

4735CLASVSTRUCT.TEX

Table A-10 Class Vector Table Fields
Field Name Contents
CLASS_PUTNXT Points to the put-next-input-data-on-queue routine (IK$PUTNXT) in the class input driver module.
CLASS_GETNXT Points to the get-next-byte-for-output routine (IK$GETNXT) in the class input driver module.
CLASS_DDT Points to the class driver dispatch table.
1read only fields

A.9 Common Vector Table

The common vector table (DECW_COMMON_VECTOR) data structure in the I/O database contains vectors to the routines and data segments of the common driver module (see Figure A-13). The driver builds the data structure using the $VECINI, $VEC, and $VECEND macros. Table A-11 lists and defines the fields of the data structure.

Figure A-13 Common Vector Table Data Structure

4735COMMVSTRUCT.TEX

Table A-11 Common Vector Table Fields
Field Name Contents
COMMON_DDT Pointer to the driver dispatch table (IN$DDT).
COMMON_POS_CURSOR Points to the cursor positioning routine (IN$POS_CURSOR).
COMMON_SETUP_INPUT_UCB Points to the UCB setup routine (IN$SETUP_INPUT_UCB) for the input drivers.
COMMON_SETUP_OUTPUT_UCB Points to the UCB setup routine (IN$SETUP_OUTPUT_UCB) for the output driver.
COMMON_VSYNC Points to the vertical retrace timer routine (IN$VSYNC) for a time mark in the common driver code.
COMMON_FLAGS Points to the flags longword in the common driver that stores global status.
1read only fields

A.10 Port Vector Table

The port vector table (PORT_VECTOR) data structure in the I/O database contains vectors to the routines of the input port driver module (see Figure A-14). The driver builds the data structure using the $VECINI, $VEC, and $VECEND macros. Table A-12 lists and defines the fields of the data structure.

Figure A-14 Port Vector Table Data Structure

4735PORTVSTRUCT.TEX

Table A-12 Port Vector Table Fields
Field Name Contents
PORT_STARTIO Vector to the start I/O routine in the port input driver module.
PORT_SET_LINE Points to the set-terminal-line-characteristics routine in the port input driver module.
PORT_DS_SET Points to the set-modem-output-signals routine in the port input driver module.
PORT_XON Points to the send XON routine in the port input driver module.
PORT_XOFF Points to the send XOFF routine in the port input driver module.
PORT_STOP Points to the reset-active-output routine in the port input driver module.
PORT_ABORT Points to the abort-active-output routine in the port input driver module.
PORT_RESUME Points to the resume-stopped-output routine in the port input driver module.
PORT_SET_MODEM Points to the initialize-modem-polling routine in the port input driver module.
PORT_MAINT Points to the DZ11 maintenance routine in the port input driver module.
1read only fields

A.11 Output Vector Table

The output vector table (GA$VECTOR or GC$VECTOR) data structure contains vectors to the routines of the output driver module. The output driver builds the data structure using the $VECINI, $VEC, and $VECEND macros. Table A-13 lists and defines the fields of the data structure.

Table A-13 Output Vector Table Fields
Field Name Contents
OUTPUT_CLEAR_CURSOR Points to the clear-cursor routine (CLEAR_CURSOR) in the output driver subroutine module (not used in GPX drivers).
OUTPUT_CURSOR_PATTERN Points to the set- or load-cursor-pattern routine in the output driver subroutine module.
OUTPUT_DISABLE_VIDEO Points to the disable-video routine (DISABLE_VIDEO) in the main output driver module.
OUTPUT_ENABLE_VIDEO Points to the enable-video routine (ENABLE_VIDEO) in the main output driver module.
OUTPUT_BUFFERED_FDT Points to the FDT-parsing routine (GA$FDTPARSE) in the main GPX output driver module.
OUTPUT_POS_CURSOR Points to the position-cursor routine in the output driver subroutine module.
OUTPUT_CANCEL Points to the cancel-I/O routine (GA$CANCEL) in the GPX main output driver module.
OUTPUT_DIRECT_FDT Points to the FDT-parsing routine (GA$FDTPARSE) in the main GPX output driver module.
OUTPUT_SET_DVI Points to the set- or initialize-the-DVI-data-structure routine in the output driver subroutine module.
OUTPUT_OPWIN_VISIBLE Points to the check-for-operator-window-mode-capability routine in the output driver subroutine module.
OUTPUT_OPWIN_UP Points to the display-operator-window routine in the output driver subroutine module.
OUTPUT_OPWIN_DOWN Points to the remove-operator-window routine in the output driver subroutine module.
OUTPUT_OPWIN_RESIZE Points to the resize-operator-window routine in the output driver subroutine module.
1read only fields

Appendix B
Device Driver Macros

Macros within device driver software modules ensure consistency and simplify the coding of the DECwindows interface. This appendix describes the macros used in the various driver modules. They are presented in three groups as follows:

  • General device driver
  • Input queue and packet processing
  • Vector generation

The DECwindows driver macro definitions are in SYS$LIBRARY:DECW$DRIVER.MLB.

B.1 General Device Driver Macros

This section describes the VMS macros that provide general services within the device driver modules. Information concerning data structures referenced in this chapter may be found in Appendix A. The general device driver macros are as follows:

  • COMMON_CTRL_INIT
  • COMMON_UNIT_INIT
  • $DECW_COMMON_READY
  • $DECWGBL

COMMON_CTRL_INIT

The COMMON_CTRL_INIT macro relocates a vector table generated by the $VEC macro. The controller initialization routine containing this macro is called at system startup and during recovery after power failure.

FORMAT

COMMON_CTRL_INIT dpt, vector

arguments dpt is a symbolic name of the driver prologue table.

vector is the address of the table generated by $VEC. output

Location Contents
R0 Destroyed
R1 Destroyed

COMMON_UNIT_INIT

The COMMON_UNIT_INIT macro sets the driver dispatch table field in the device data block and unit control block (UCB) to contain the address of the common driver dispatch table (DDT). This macro contains the common code for the unit initialization routine that is run whenever a unit is created.

FORMAT

COMMON_UNIT_INIT

input
Location Contents
R0 Address of the DDT for this unit
R5 UCB address
output
Location Contents
R1 Destroyed
R2 Destroyed

$DECW_COMMON_READY

The $DECW_COMMON_READY macro senses whether the common drivers are loaded. The macro is used by all DECwindows drivers that depend on a common driver to operate. It checks for the presence of the common driver (INDRIVER) by examining the symbol DECW$GL_VECTOR, set by the driver's controller initialization routine. It then checks for keyboard and mouse class drivers by looking at the flags longword (indexed from the common vector).

FORMAT

$DECW_COMMON_READY

output
Location Contents
R0 Contains a value of 0 when the common driver is not loaded. Contains a value of 1 when all common drivers are loaded.

$DECWGBL

The $DECWGBL macro is an external definition that defines the DECwindows common, input, and output driver data structures. The global macro directly calls other structure definition macros within the various DECwindows and VMS modules (see Table B-1) that define the I/O database.

Table B-1 Structure Definition Macros Called by$DECWGBL
Macro Name Macro Function
$TTYVECDEF Defines the port and class vector tables.
$SILODEF Defines the SILO block.
$DECWDEF Defines the DVI, KIB, and INP data structures.
$DECWCMNINPUCB Defines the common input extension (DWI$x_DECW_ ) and calls $TTYUCBDEF to link the device-specific input extension structure.
$DECWPTRINPUCB Defines the pointing device input UCB extension (DWI$x_PTR_ ).
$DECWKBINPUCB Defines the keyboard input UCB extension (DWI$x_KB_ ).
$DECWOUTPUTUCB Defines the output device UCB extension (UCB$x_DECW_ ).
$DECWCOMMON Defines the INB and MHB, the common vector and output vector tables, common flag word (COMMON_FLAGS), and calls the dynamic definition macro $DYNDEF.

B.2 Input Queue and Packet Processing Macros

This section describes the macros that are used in a class input driver module to acquire free input packets and insert them into the input queue. The input queue and packet-processing macros are as follows:
  • GET_FREE_KB_PACKET
  • GET_LAST_EVENT_PACKET
  • PUT_INPUT_ON_QUEUE

GET_FREE_KB_PACKET

The GET_FREE_KB_PACKET macro returns the address of a free packet in R1 if one is available. If a packet is not available, 0 is returned in R1. It uses the interlocked queue instruction (REMQHI) to remove the packet from the free queue.

FORMAT

GET_FREE_KB_PACKET

input
Location Contents
R5 UCB address of the input device
output
Location Contents
R1 Address of the free packet; 0 if there is none
R2 Destroyed

GET_LAST_EVENT_PACKET

The GET_LAST_EVENT_PACKET macro removes a specified type event packet from the tail of the input queue for motion compression. The macro tests the packet type (INP$B_TYPE) to ensure that it matches the event_type argument in the macro call. If a match is found, the macro increments the motion compression count (DWI$L_PTR_MOTION_COMP_HIT) and returns the free-queue address of the removed input packet in R1. If an event_type (typically, X$MOTION_NOTIFY) packet is not found, it reinserts the packet in the input queue and returns a 0 in R1.

FORMAT

GET_LAST_EVENT_PACKET event_type

arguments event_type defines the X11 event (X$MOTION_NOTIFY) for which the packet is removed from the input queue for compression. input
Location Contents
R5 UCB address of the input device
output
Location Contents
R1 Address of the removed packet; 0 if there is none
R2 Destroyed
DWI$L_PTR_MOTION_COMP_HIT Motion compression count, incremented by one if the specified event type packet is found

PUT_INPUT_ON_QUEUE

The PUT_INPUT_ON_QUEUE macro inserts an input packet onto the input queue shared with the server. The macro uses the interlocked queue instruction INSQTI for queue insertion and uses the queue header information from the UCB to select the right input queue.

FORMAT

PUT_INPUT_ON_QUEUE

input
Location Contents
R1 Address of the input event packet
R5 UCB address of the input device
output
Location Contents
R2 Destroyed

B.3 Vector Table Generation Macros

This section describes the VMS macros that should be used to generate the various vector tables. Using these macros ensures the generation of a valid table, even if the vector table is expanded in new releases. The vector table generation macros are as follows:
  • $VECINI
  • $VEC
  • $VECEND

$VECINI

The $VECINI macro generates and initializes the vector table. The table is initialized with the entries pointing to the driver's null routine. Subsequent calls to $VEC fill the table with the addresses of the real entry points.

FORMAT

$VECINI drivername, null_routine, [prefix]

arguments drivername defines the driver prefix, usually two alphabetic characters.

null_routine defines the address of the driver's null entry point.

prefix defines the prefix to be added to the generated symbols (for instance, PORT_, CLASS_, COMMON_, OUTPUT_). PORT_ is the default.

Note
The null routine should simply contain an RSB instruction. It is called for any function that the driver does not support.

$VEC

The $VEC macro generates fields (vectors) and validates the vector table entry. Each invocation of the $VEC macro specifies the entry argument. However, a driver need not supply the address of a routine for each entry in the table. The $VEC macro constructs a valid table regardless of how many entries are supplied. The $VEC macro accepts the entry names minus the driver type prefix (PORT_ or CLASS_ or OUTPUT_). (For examples, refer to the figures for the class or port vector table data structures in Appendix A.) The $VECINI macro defines the prefix applied to the entries: PORT_ for the port vector table and CLASS_ for the class vector table. This macro ensures that a working table is generated, or that you are notified of any error by message. Note that a driver accesses the table using the symbolic offset names shown in the vector table data structures of Appendix A.

FORMAT

$VEC entry, routine

arguments entry defines the name of the table entry.

routine defines the name of the routine being inserted in the entry.

$VECEND

The $VECEND macro generates the longword of zeros that terminates the vector table list and sets the location counter to the correct position. The exact placement of $VECEND in the sequence of $VEC entries marks the end of the vector table.

FORMAT

$VECEND [end]

arguments end is a flag controlling the generation of the end of the vector table. This argument is generally omitted so that the $VECEND macro can generate the end of the vector table. Otherwise, the $VECEND macro does not generate the end of the table.

Index Contents