PDRREF:Display Drivers

From EDM2
Jump to: navigation, search
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

This chapter describes video cursor support and the installation utility program used by OS/2 display drivers.

Exported Entry Points (Cursor)

The following entry point is exported by the dynamic link library of a display driver:

EXPORTS
   MoveCursorBlock     @103

MoveCursorBlock

Display drivers must export an entry point for the MoveCursorBlock table. This table contains information about the display driver's MoveCursor routine (code) and data areas. The table values are checked after the display driver is initialized. This allows the driver to determine the correct values.

typedef struct _MCDESCRIPTION {
    PVOID    pMoveCursor;
    ULONG    ulCodeLength;
    PVOID    pCursorData;
    ULONG    ulDataLength;
} MCDESCRIPTION;
typedef MCDESCRIPTION * PMCDESCRIPTION;

The fields in the MCDESCRIPTION data structure are described below:

pMoveCursor
Flat address of the MoveCursor routine in the display driver.
ulCodeLength
Length in bytes of the MoveCursor routine
pCursorData
Flat address of the data area used by the MoveCursor routine
ulDataLength
Length in bytes of the data area used by the MoveCursor routine

This routine supports calls from the system timer (at interrupt time). The strategy for the MoveCursor routine is that the pointer is checked and, if necessary, redrawn or excluded at timed intervals.

The PMDD.SYS physical device driver creates a privilege level 0 alias for the data address and passes the alias to the routine in the EAX register when MoveCursor is called at interrupt time. Therefore, all data addressing within the routine must be performed relative to this address.

At entry to the MoveCursor routine, the stack contains the following:

VOID MoveCursor(LONG abs_x, LONG abs_y, PVOID pCursorData)

Using the C calling convention, the stack contains two LONGs, which hold the X- and Y-coordinates of the cursor hot spot, and a PVOID that is a pointer to the cursor data area that is valid in the current context. All references to this data area must be done relative to the address passed in. If the X- and Y-coordinates are set to 0x80000000, this signifies a CheckCursor call.

Regular timer interrupts give the presentation driver an opportunity to check whether the pointer is valid. For example, the driver can check the following:

  • Have new X- and Y- coordinates been set?
  • Is the pointer excluded because of a drawing operation? If so, has that operation been completed?
  • Is the pointer currently visible (although it should be excluded) because it is in an area that is being redrawn?

At the end of the MoveCursor routine, a check is performed to see if a new location was given for the pointer while it was being drawn. If the pointer has moved again, it must be drawn at the new location or be excluded because it has moved into the protection rectangle. This implies that the routine needs to track both real (X,Y) and pointer (X,Y) coordinates.

Programming Considerations

Typical cursors are an arrow or a cross with an action point called the hot spot at the point of the arrow or the center of the cross. When the presentation driver draws a cursor, the origin of the image must be offset to place the action point at the required (X,Y) position. The required offset is specified in the call to GreSetCursor. Because the cursor entry point can be called at various times from many different places, the cursor routine uses semaphores to protect itself (protection is the responsibility of the presentation driver). Similarly, because cursor drawing can be a time-consuming operation, the display driver must also protect itself against re-entrance.

The display driver must resolve all interactions between cursor drawing at interrupt time and access to video hardware. While in the background, the display driver does not draw any cursor image.

Caution should be used when the display is a buffered device and the cursor is drawn into a bit map in the buffer. In this case, the display driver deletes the cursor and excludes it when a draw operation occurs at the cursor location. To do this, the driver does a "hit test" for each output operation to see if the cursor location is in the drawing area and to set a protection rectangle that is used to exclude the cursor.

Introduction to Display Driver Installation

The OS/2 2.0 Display Driver Installation utility program (DSPINSTL.EXE) provides all the facilities necessary to install and configure OS/2 display drivers. The OS/2 display driver installation installs and configures PM display drivers. It might also include the installation and configuration of WIN-OS/2 display drivers, and the installation of base video service (VIO) drivers and DOS virtual device drivers (VDDs).

Display driver installation and configuration is more complex than standard device driver installation. It typically includes the following activities:

  • Allowing the user to select OS/2 display characteristics - Specification of the type and resolution of the display driver to be installed. (See Allowing the User to Select OS/2 Display Driver Characteristics)
  • Copying display driver-related files - Copying display driver-related files from source directories (usually on diskettes) to target directories on the user's hard disk (see Copying Display Driver-Related Files).
  • Updating system configuration files - Appropriately updating various OS/2 and WIN-OS/2 configuration files to ready the new display driver for subsequent execution when the user's system is restarted (see Updating System Configuration Files).

Allowing the User to Select OS/2 Display Driver Characteristics

The user needs to specify whether the display driver to be installed will be used as the primary display adapter or as the secondary display adapter.

The user must then specify the type of display driver to install. This is important because many types of display adapter hardware can support a number of different display drivers. For instance, extended graphics array

XGA display adapter hardware can be operated using either the high-resolution XGA display driver or other lower resolution standard display drivers such as video graphics array (VGA) or enhanced graphics adapter (EGA) display drivers.

Finally, because some display drivers can support operation at more than one graphics resolution, the user might have to specify the display resolution at which the driver is to be operated. Display resolutions are typically specified by supplying the width and height of the display (in pels) and the maximum number of colors that can be simultaneously displayed. The user's choices for display resolution are often affected by the type of video hardware attached to the user's system. For example, both the size and type of the user's display and the amount of video RAM on the display adapter can affect which display resolutions can be run.

Copying Display Driver-Related Files

There are several factors that can complicate the copying of display driver-related files from source directories to target directories. First, display driver files might be sufficiently large and numerous to span more than one source diskette. This can easily occur when several display drivers that support different display resolutions are bundled together on the same diskettes (along with their associated font and resource files). Second, to save space within the source directory, it might be desirable to place packed files within the source directory. If so, the packed files should be unpacked when they are copied to the target directory. Third, the display driver packager might wish to specify file version checks that are to take place before file copying is performed. Such checks are valuable because they can prevent the inadvertent replacement of updated display driver files by older versions of the files.

Updating System Configuration Files

After display driver-related files have been copied to the user's system it is necessary to update different system configuration files to complete the installation process. Frequently, the CONFIG.SYS and OS2.INI files need to be updated to complete PM display driver installation and the SYSTEM.INI and WIN.INI files need to be updated to complete the WIN-OS/2 display driver installation. Depending on the display driver to be installed, other configuration files might also have to be updated.

Display Driver Installation Utility Program

DSPINSTL, the display driver installation utility program, is similar in some ways to the OS/2 Device Driver Installation utility program, DDINSTAL.EXE. DSPINSTL contains extensions that are specifically geared to simplify the steps that the user must perform to install and configure OS/2 display drivers. Because different types of OS/2 display drivers can have radically different installation and configuration requirements, DSPINSTL contains a set of features that allows a display driver developer to customize the installation process to meet the developer's special needs.

DSPINSTL consists of the following six major components:

  • DSPINSTL Configuration File (DSC file) Interpreter
  • Initial User Interface PM Panels - A standard set of PM panels that serve as a basic front-end user interface (see User Interface PM Panels).
  • Action Routine Interface - An interface that allows the display driver developer to (optionally) add custom control logic (see Action Routine Interface).
  • Service Functions - A set of standard service functions that can be called from within an action routine (see reference to service functions under Action Routine Interface and DSPINSTL Service Functions).
  • Command Language PM Panels - A standard set of PM panels that act as the front end to the DSPINSTL Command Language Interpreter (see Command Language Presentation Manager Panels).
  • Command Language Interpreter - The final stage of DSPINSTL that executes the installation and configuration commands that are packed in Display Driver Profile files (DSP files) (see DSPINSTL Command Language Interpreter).

DSPINSTL Configuration File Interpreter

The DSPINSTL Configuration file (DSC file) interpreter allows the display driver developer to specify, within the DSC files, the high level knowledge that characterizes one or more display driver packages. The information contained in the DSC files determines the contents of some of the fields in the standard set of PM panels. It also initializes a chain of data elements that will subsequently be passed to the DSPINSTL Command Language Interpreter that executes as the final stage of DSPINSTL operation.

Display Configuration Files

The DSC files are the key to DSPINSTL's ability to act as a generalized installation tool that can install many different types of display drivers. The display driver developer packages a set of drivers by placing the drivers on a diskette, creating one or more DSP files containing DSPINSTL installation and configuration commands. The developer then creates a configuration file entry within a DSC file that summarizes the key points concerning that display driver package. DSC files should be placed either in the directory that contains the DSPINSTL utility program or in a directory that is contained in the user's DPATH. DSPINSTL checks its directory first, and then if it cannot find a DSC file it searches the DPATH, stopping when it finds a directory that contains one or more DSC files. DSPINSTL reads all the DSC files it finds in that directory. DSC files are distinguished by a file-name extension of .DSC. A configuration file entry includes the following types of information:

  • A title string that identifies the driver within the initial DSPINSTL PM panels (Primary Video Adapter and Secondary Video Adapter). These two panels are provided so that users can explicitly select which display drivers to install.
  • The name of the dynamic link library (DLL) module (if any) that contains action routines specific to the installation of that display driver package.
  • A keyword string that identifies whether the display drivers handle a standard type of display adapter. The following is a list of supported standard-type keyword strings:
Type of Adapter Keyword Type String
Color Graphics Adapter CGA
Enhanced Graphics Adapter EGA
Video Graphics Adapter VGA
Display Adapter 8514/A 8514
Extended Graphics Adapter XGA
Super Video Graphics Adapter SVGA

These standard-type strings are provided so that DSPINSTL can create a logical association with a display driver as a default type. This association is used if the user accepts DSPINSTL's default selection in the Video Display Configuration PM panel (the initial DSPINSTL PM panel). For example, suppose the panel shows that the user's system has an 8514 adapter as its primary display. If a DSC file entry contains a standard-type string of "8514" and the user accepts the default choice by selecting the OK push button, then that file entry will be chosen automatically. If more than one DSC file entry contains standard-type strings of "8514", then DSPINSTL would display a PM panel to allow the user to resolve the ambiguity. If the user checks either the primary or secondary check box, to indicate the desire to override the default logic and explicitly choose a driver, then the PM panel that follows will include list box entries for all the entries in the DSC files that DSPINSTL has read.

  • A default chain of data elements that characterize a sequence of installation and configuration steps which, in total, constitute the entire installation and configuration process. Each chain element can include the following data:
    • A required default keyword string that will trigger the interpretation of one or more DSP files in a given source directory.
    • A required default prompt string that will be displayed in a PM panel informing the user of the purpose of the next installation step. This prompt string is included to help the user decide which device or directory to point the utility program toward to accomplish that portion of installation.
    • An optional default prompt string that is used to tell the user which diskette to insert (if the next portion of installation is being performed from a diskette). This feature allows the driver package developer to inform the user of the exact title that is written on a diskette.
    • An optional diskette volume label that allows DSPINSTL to verify that the user has inserted the correct diskette.
    • An optional display resolution string that can be used by the developer to display a default display resolution for installation. This string can be passed by an action routine to the Select_Video_Resolution service function.

Typically, there will be one data element within the chain for each diskette in the package. However, the display driver developer can use the chain as desired. For example, one data element in the chain might handle file copy commands, while the next might be used for configuration file updates. The chain of data elements is first passed to the action routines (if any) and is then interpreted by the DSPINSTL Command Language Interpreter in the last part of the process. In this manner a developer can create a default series of installation steps, dynamically modify those steps, and then have the DSPINSTL command interpreter execute all the substeps that constitute each step.

DSC files are composed of lines containing character string entries. The following syntax rules govern the lines within a DSC file:

All character strings in the file are enclosed in double quotation marks.
    The \" pair can be used to embed a double-quotation character within a character string.
    Comment lines start with an asterisk (*).

DSC files contain one or more display driver package entries. Each entry contains a header section containing general information about the display driver package. The header section is followed by one or more subsections that define the default values for a data chain element. The format of the header section is shown in the following diagram:

<Adapter Type Title string>   /* Title strings are up to 256 characters   */

<DLL Module Name string>      /* DLL module, containing action routines   */
                              /*   for that type of adapter               */

<Standard Type Key string>    /* Key string that DSPINSTL uses to identify*/
                              /*   a type of adapter that it recognizes.  */
                              /*   Can be NULL, see below for the complete*/
                              /*   set of standard keys                   */
         "1"                  /* Required parameter, must be set to 1     */
         "0"                  /* Required parameter, must be set to 0     */

<# of Parameter Sets in Entry>/* 'n'                                      */

The format of the data chain element subsection is as follows:

<Default Key String>            /* Initial key string assigned to this     */
                                /*   DSPINSTL data chain element           */

<Default General Prompt String> /* User prompt string displayed in the     */
                                /*   Specify Source Directory panel when   */
                                /*   the DSPINSTL data chain element is    */
                                /*   interpreted                           */

<Default Diskette Prompt String>/* User prompt displayed in the Insert     */
                                /*   Diskette panel displayed by the       */
                                /*   Specify Source Directory panel logic  */

<Default Volume Label>          /* Optional volume label string used by    */
                                /*   the Specify Source Directory panel    */
                                /*   logic to verify that an inserted      */
                                /*   diskette is the correct diskette      */

<Resolution String>             /* Optional string, which indicates a      */
                                /*   display driver resolution.            */
                                /*   The string can be passed to the       */
                                /*   Select_Display_Resolutions            */
                                /*   service function or can be left NULL. */
                                /*   SVGA display driver sets have one     */
                                /*   resolution to a DSP file.             */
                                /*   Resolution strings should always      */
                                /*   be of the form, ####x####x####, where */
                                /*   each #### field is a separate integer */

There is no data element parameter provided to indicate a choice of default source directory. It is always assumed to be the logical A: drive. DSPINSTL provides a Specify Source Directory PM panel that allows the user to override the default source directory. The <Default General Prompt String> is displayed in the PM panel so that the user will know the purpose of the source directory about to be searched.

If the user changes the source directory to a nonremovable device, the source files can exist in the specified directory or in a subdirectory under the specified directory. The subdirectory name must be the same as the volume label for the entry with the underscore character (_) replacing spaces. To do this, volume labels must be limited to eight characters.

The following example shows a typical SVGA display adapter parameter entry:

"XYZ SVGA video adapter"
"XYZ.DLL"
"SVGA"
"1"
"0"
"3"
"XYZ1"
"XYZ SVGA display drivers (part 1)"
"XYZ SVGA drivers diskette #1"
"XYZ 1"
"640x480x256"
"XYZ2"
"XYZ SVGA display drivers (part 2)"
"XYZ SVGA drivers diskette #2"
"XYZ 2"
"1024x786x256"
"XYZ3"
"XYZ SVGA display drivers (part 3)"
"XYZ SVGA drivers diskette #3"
"XYZ 3"
"1024x768x256"

The above example includes three resolution strings, which can be displayed in the scrolling list box in the Select Display Resolutions panel.

If DSPINSTL cannot identify the type of graphics adapter, it displays a default type of Other and also sets the default internal key to "Other". The user can then go to the Primary Video Adapter PM panel or the Secondary Video Adapter PM panel and select a display type that is included in one of the DSC file entries.

If DSPINSTL can identify the type of graphics adapter but finds no matching configuration file entry with a matching standard-type keyword string, it displays the default type-name for the adapter in the Video Display Configuration panel (such as VGA) but does not allow the user to accept the default selection. The user must use either the primary display check box or the secondary display check box in order to override default DSPINSTL processing. This will cause a secondary PM panel to be displayed that will allow the user to select a display driver package from a list that includes all the packages described in the DSC files.

User Interface PM Panels

The front-end PM panels allow the user to specify whether primary or secondary display driver installation is desired. The panels also allow the user to override the default display driver type and specify which display driver package to install (based on the set of packages defined in the relevant DSC files on the user's system).

Action Routine Interface

The action routine interface allows the display driver developer to (optionally) add custom control logic that is executed after the user makes an initial selection. Action routines are supported so that the installation process can ask the user specialized questions (through the use of PM panels) or perform internal inquiries concerning the state of the hardware or software system. For example, an action routine can be used to ask the user what display resolution should be configured. Action routines are packaged in OS/2 Dynamic Link Library files (DLL files).

The action routines tailor a display driver installation by modifying the chain of data elements that are initialized by the DSPINSTL Configuration File Interpreter. The display driver developer packages DSPINSTL action routines in a DLL file and then includes the name of the DLL file in the DSC file entry for that display driver package. The DLL itself should be placed in a directory within the user's LIBPATH or in the directory containing the DSPINSTL.EXE file.

DSPINSTL will call specifically named action routines (if they are provided in the DLL that can be specified within the controlling configuration file entry) during the installation when the user:

  • Accepts the selection of the primary display (in the initial Video Display Configuration PM panel)
  • Accepts the selection of the secondary display (in the initial Video Display Configuration PM panel)
  • Overrides the selection of the primary display and explicitly selects a primary display (through the use of a Primary Video Adapter PM panel)
  • Overrides the selection of the secondary display and explicitly selects a secondary display (through the use of a Secondary Video Adapter PM panel)

The four action routines must have the following names:

  • Default_Primary()
  • Default_Secondary()
  • Selected_Primary()
  • Selected_Secondary()

The display driver developer can provide any subset of the four action routines that is deemed appropriate. When DSPINSTL reaches one of the points at which it tries to call an action routine, it uses the DosLoadModule API to attempt to load the DLL module. If successful, it then uses DosGetProcAddr API to try to obtain the address of the action routine. If this is successful, DSPINSTL passes control to the action routine. If this is not successful, DSPINSTL continues.

DSPINSTL aids the function of the action routines by providing them with a set of service functions that enable them to perform various standard actions such as data chain maintenance. In this manner, the individual action routine does not have to be aware of the specific structure of the data element chain. Again, DSPINSTL is designed to insulate the action routine from the details of the utility program's internal structure. This greatly simplifies the creation of an action routine.

Each action routine is passed a pointer to a global DSPINSTL data structure, which contains values that can be used by the action routine. This data structure includes a revision field, which is always set to 1 by the utility program. The revision field is provided so that future revisions of DSPINSTL will be able to grow and evolve the data structure. Action routines should always check the revision field to determine how to access the data structure.

Procedure Call Interface for Action Routines

All four action routines follow the same procedure call interface, which is illustrated under Default_Primary.

DSPINSTL Service Functions

A set of standard service functions is provided to keep the action-routine developer from having to program commonly used functions. Service functions enable the user to examine and modify the DSPINSTL chain of data elements.

The global DSPINSTL data structure contains pointers to a set of DSPINSTL service functions that are available to all action routines. These service functions, listed below, are described on the pages that follow.

  • Link_Chain_Element
  • Unlink_Chain_Element
  • Next_Chain_Element
  • Select_Display_Resolutions

Link_Chain_Element

Description
Link_Chain_Element provides a standard mechanism for the linking of data chain elements within the DSPINSTL data chain.
#include <os2.h>

PDSPINSTL_CHAIN    new_element_ptr;
USHORT             create_flag;
USHORT             position_flag;
PDSPINSTL_CHAIN    existing_element_ptr;
ULONG              rc;                    /*  Return codes. */ 

rc = Link_Chain_Element(new_element_ptr,
      create_flag, position_flag, existing_element_ptr);

Parameters

new_element_ptr (PDSPINSTL_CHAIN) - input
If create_flag is set to 1, this argument will return a pointer to the new element. If create_flag is set to 0, on input this argument points to an existing DSPINSTL data chain element.
create_flag (USHORT) - input
The flag that indicates whether the caller wants the function to create a new element or merely link an element into the chain. A value of 1 indicates that a new element should be created and then linked into the chain. A value of 0 indicates that an existing element (pointed to by the new_element_ptr argument) should be linked into the chain.
position_flag (USHORT) - input
The flag that indicates where the caller wishes the data chain element to be linked into the data chain. A value of 0 places the element at the head of the chain. A value of 1 places it at the tail of the chain. A value of 2 indicates that the element should be linked in front of the chain element pointed to by the existing_element_ptr argument. A value of 3 indicates that the element should be linked after the chain element pointed to by the existing_element_ptr argument.
existing_element_ptr (PDSPINSTL_CHAIN) - input
If the position_flag is set to 2 or 3 on input, this argument points to another data element within the chain.
rc (ULONG) - returns
Return codes.

This service function returns the following values:

0 Success
1 Element could not be linked into chain
2 New chain element could not be allocated
Remarks
This function optionally can be used to allocate a new element that is then linked into the chain. The caller indicates the location in the chain where the data chain element should be linked. Elements can be linked at the head of the chain, the end of the chain, or after a specified chain element. After the function returns a pointer to a new data chain element, the action routine can then fill in the element's fields as appropriate.

Unlink_Chain_Element

Description
Unlink_Chain_Element provides a standard mechanism for unlinking data chain elements from the chain. It does not deallocate the memory associated with the element; it only unlinks it from the chain.
#include <os2.h>

PDSPINSTL_CHAIN    element_ptr;
ULONG              rc;           /*  Return codes. */

rc = Unlink_Chain_Element(element_ptr);
Parameters
element_ptr (PDSPINSTL_CHAIN) - input
A pointer to a DSPINSTL data chain element.
rc (ULONG) - returns
Return codes.

This service function returns the following values:

0 Success
1 Element could not be unlinked from chain

Next_Chain_Element

Description
Next_Chain_Element provides a standard mechanism for returning the address of specified data elements within the chain.

#include <os2.h>

PDSPINSTL_CHAIN    next_element_ptr;
USHORT             position_flag;
PDSPINSTL_CHAIN    existing_element_ptr;
ULONG              rc;                    /*  Return codes. */

rc = Next_Chain_Element(next_element_ptr,
      position_flag, existing_element_ptr);

Parameters
next_element_ptr (PDSPINSTL_CHAIN) - input
Returns a pointer to the specified chain element.
position_flag (USHORT) - input
A flag that indicates which data chain element is specified by the caller:
0 Indicates the head element of the chain
1 Indicates the tail element of the chain
2 Indicates the data element that follows the data element that is pointed to by the existing_element_ptr input argument
3 Indicates the data element that precedes the data element that is pointed to by the existing_element_ptr input argument
existing_element_ptr (PDSPINSTL_CHAIN) - input
Pointer to a data chain element. Used only if position_flag is set to 2 or 3.
rc (ULONG) - returns
Return codes.

This service function returns the following values:

0 Success
1 Next element found within the chain

Select_Display_Resolutions

Description
Select_Display_Resolutions can be used by an action routine to ask a user which display resolutions are desired as a result of this installation.
#include <os2.h>

HWND                 hWnd;
PSCREENRESOLUTION    resolutions;
ULONG                num_resolutions;
BOOL                 fmultiple;
ULONG                rc;               /*  Return codes. */

rc = Select_Display_Resolutions(hWnd,
      resolutions, num_resolutions, fmultiple);
Parameters
hWnd (HWND) - input
The handle of the main DSPINSTL window.
resolutions (PSCREENRESOLUTION) - input
A pointer to an array of display resolution structures, where:
struct resolutions_struct
{
 UCHAR resolution_string[40]; /* String to go in multiple selection list box. */
 USHORT selected;             /* Flag set by the service function.            */
                              /* If 0, this resolution was not selected,      */
                              /* if 1, this resolution was selected.          */
};
num_resolutions (ULONG) - input
The number of display resolutions in the array.
fmultiple (BOOL) - input
A flag that specifies whether the user will be allowed to select multiple resolutions (or only a single resolution). True indicates multiple selections are allowed.
rc (ULONG) - returns
Return codes.

This service function returns the following values:

0 User selected an entry and exited the panel by selecting the OK push button
0xFFFFFFFF User exited the panel by selecting the Cancel push button
Remarks
This function displays a Select Display Resolutions PM panel, which lets the user choose from a set of display resolution strings that are displayed in a scrolling list box within the panel. The various strings are passed into the function within an array of structures. A flag that is passed to the function controls whether the panel will allow the user to select multiple display resolutions or only a single resolution. In this manner, action routines can look for one choice or multiple choices. On return from the function, each structure in the array will contain a flag value that indicates whether that array element was selected by the user.

Command Language Presentation Manager Panels

During the final stage of DSPINSTL, each data chain element will trigger a separate DSPINSTL Command Language interpretation step. One of these PM panels will allow the user to optionally override the source directory that will be used for that step. Another panel will prompt the user to insert an appropriately labeled diskette. The remainder of the PM panels will prompt the user when execution errors are encountered during this final portion of DSPINSTL execution.

DSPINSTL Command Language Interpreter

The interpretation of the DSPINSTL commands in the DSPINSTL Display Driver Profile files is the final stage of the DSPINSTL process. The interpretation is performed by the DSPINSTL Command Language Interpreter. The interpreter operates by interpreting the contents of DSPINSTL Display Driver Profile files (DSP files) that contain DSPINSTL commands. DSPINSTL commands specify the basic installation and configuration operations that will be performed by the utility program. Each DSP file is tagged with a keyword string that identifies the file.

The DSPINSTL Command Language Interpreter selects DSP files for interpretation by traversing the data element chain. The chain was first initialized by the Configuration File Interpreter, and then might have been modified through the operation of action routines. Each data element corresponds to an installation/configuration "step." Among other uses, this multistep architecture allows DSPINSTL installation and configuration to be partitioned over multiple source diskettes (with each diskette handled in separate steps).

DSPINSTL provides a PM panel that allows the user to override the default value for the source directory that is to be used for a given step. The data chain element also includes a DSP file keyword string. The DSPINSTL Command Language Interpreter will interpret all DSP files in the source directory that are tagged with that keyword string.

It is the DSPINSTL commands that do the actual work of display driver installation and configuration. All the preceding DSPINSTL activities act to properly set up this final stage on a given user's system. In addition to commands that copy files and modify configuration files, there is a special RUN command that can be used to run specified programs during DSP file interpretation. Among other things, such programs can generate DSPINSTL commands that are immediately interpreted by the DSPINSTL Command Language Interpreter. This is the final manner in which the display driver developer can customize DSPINSTL execution.

DSPINSTL Command Language

The DSPINSTL command language is highly flexible and accommodates the many different kinds of operations that must be accomplished in the installation and configuration of OS/2 display drivers.

A set of DSPINSTL commands is packaged as a DSP file. Each DSP file must contain a KEY command that tags that DSP file. When a data chain element is interpreted by DSPINSTL, any DSP files in the current source directory that are tagged with that keyword are then interpreted. This is the mechanism that allows automatic execution.

The FILES command tells DSPINSTL which files to copy to the user's hard disk. Date/Time checking or file version checking can be performed as part of FILES command processing to help prevent inappropriate file copies from being done. This capability is an important DSPINSTL safety feature. The FILES command supports the installation of both packed and unpacked files. The use of packed files can greatly reduce the amount of space consumed on the display driver developer's diskettes.

The CONFIG, OS2INI, and WININI commands tell DSPINSTL to update the configuration in different types of system configuration files. There are three separate commands because the different types of OS/2 system configuration files require different styles of editing. The CONFIG command is used to update the CONFIG.SYS file. The OS2INI command is used to edit the various *.INI OS/2 system configuration files (such as OS2.INI or OS2SYS.INI). The WININI command is used to update the different WIN-OS/2 configuration files (such as WIN.INI and SYSTEM.INI). The configuration of OS/2 display drivers is particularly tricky because of the coordinated updates that are needed in different OS/2 configuration files.

The SET_DRIVER and SET_RESOLUTION commands are also configuration editing commands. In these two cases, rather than edit a specific configuration file, an OS/2 Graphics Engine function updates the system configuration. The additional level of data abstraction is necessary to support the architecture of the Graphics Engine, which is yet another complexity that is supported by the DSPINSTL command language.

DSPINSTL Commands

The DSPINSTL command language bears similarities to the DDINSTAL command language. The DSPINSTL command language contains important keyword extensions. Like DDINSTAL, the DSPINSTL command language interpreter accepts comments in the form of lines beginning with an asterisk (*).

The DSPINSTL Command Language files support the following commands:

  • KEY
  • FILES
  • CONFIG
  • OS2INI
  • WININI
  • RUN
  • SET_DRIVER
  • SET_RESOLUTION

The use of a MODE qualifier is valid on all DSPINSTL commands except :KEY. Valid MODE qualifier values are:

MODE=

  • PRIMARY - execute this command only if user has chosen to perform a primary display driver installation.
  • SECONDARY - execute this command only if user has chosen to perform secondary display driver installation.
  • DOS - execute this command only if DOS support is installed on the OS/2 system.
  • WINDOWS - execute this command only if WIN-OS/2 support is installed.

KEY

This command identifies a DSP file with a unique keyword string so that it can be automatically selected for interpretation by DSPINSTL. The final stage of DSPINSTL processing consists of one or more steps of DSP file interpretation. In each step, all the DSP files in the current source directory whose keyword strings match the keyword string for that step are interpreted.

The DSP file line that immediately follows the :KEY command line contains a key string that begins with the first nonblank character in the line and ends at the first blank character or the end of the line. There can be no embedded blanks within a key string. Key strings can be up to 64 bytes in length. Here is an example of a :KEY command line:

:KEY
XYZ_800x600x16

There must be a single :KEY command line in each DSP file.

FILES

This command specifies the files that are to be copied from the source directory to different destination directories. It performs in a manner similar to the DDINSTAL :FILES command. Like its DDINSTAL counterpart, the DSPINSTL :FILES command line is followed by a set of file copy directives. However, unlike its DDINSTAL counterpart, the DSPINSTL :FILES command uses the UNPACK utility program to copy files. Therefore, it can handle both packed and unpacked file formats.

The :FILES command can be used to replace any executable modules (programs and DLLs,) that are currently in use. The replacement occurs the next time the system is started. DSPINSTL cannot replace nonexecutable files that are locked at the time DSPINSTL is run.

To protect against inadvertently copying an older version file over a newer version file, all file copying is mediated by either one of the following forms of file version checks:

File Version Field checking
Date/Time checking
File Version Field Checking

Executable files can be tagged with a file version string in the description field of their executable file header. This field can be set during program linking. The format of a file version string is as follows:

<header> <version string> <trailer>

where:

<header> is a two-character string: @#.
<version string> is twelve characters defined as xxx:YYYYYYYY, where xxx is used to identify the vendor that created the file (for example, IBM) and YYYYYYYY is a file version number (for example, 0006.307). This file version number can be interpreted as a floating point number or as an integer.
<trailer> is the two-character string: #@.

An example of a file version string would be:

@#IBM:0006.307#@.

If both the source and target versions of a file contain file version strings, the file version checking is performed. For a file version check to be considered successful, the vendor identifiers of the source and target files must match and the file version number of the source file must be greater than or equal to the file version number of the target file. If the file version check succeeds, then the source file is copied over the target file. If not, DSPINSTL prompts the user to decide whether to replace the target file. If the source file contains a file version field, but the target file does not, then the source file is assumed to be more recent than the target file and is copied over the target file.

Date/Time Checking

DSPINSTL will not automatically copy an older version of a file over a newer version when the Date/Time of the file to be copied is less recent than the Date/Time of the file to be replaced. Instead, it prompts the user to decide whether to replace the newer version of a file with the older one.

The :FILES command line is followed by one or more lines that name the files to be copied from the source directory and also the destination directory to which they are to be copied. The format of these lines is as follows:

<source file name> <destination directory pathname>

where:

<source file name> is the name of a file within the source directory that contains the DSP file. A source file can be packed or unpacked.
<destination directory pathname> can include a logical drive letter specification. The optional logical drive letter specification is always overridden by the system's startup drive. The destination directory path name is not a complete file name. This means that the source file is never renamed when it is copied.
Note
The special term %BOOTDRIVE% can be used to replace the startup drive letter in all DSPINSTL commands that allow path names to be specified. %BOOTDRIVE% is a special drive designator that indicates the drive letter on which the OS/2 system was started.

If a destination directory is provided, the file is copied to that directory. If no destination directory is provided and the source file is a packed file, the file is copied to the directory that is specified in the source file's pack header. If there is no corresponding directory on the drive, the directory is created. If no destination directory is provided and the source file is an unpacked file, then the file is copied to the current working directory.

The following examples illustrate DSP file command lines that can follow the :FILES keyword command line:

:FILES   :MODE=PRIMARY
IBMVGA32.DL@ %BOOTDRIVE%:\OS2\DLL
BVHVGA.DLL %BOOTDRIVE%:\OS2\DLL
:FILES  :MODE=PRIMARY  :MODE=DOS
VVGA.SY@ %BOOTDRIVE%:\OS2\MDOS
Note
The @ sign (at sign) at the end of some of the source file names indicates that these are packed files (packed by the OS/2 PACK utility program).

CONFIG

This command specifies updates to the CONFIG.SYS configuration file. It performs in a manner similar to the DDINSTAL :CONFIG command. Like its DDINSTAL counterpart, the DSPINSTL :CONFIG command line is followed by a set of CONFIG.SYS statements, which are to be added to the configuration file. However, the DSPINSTL version of the :CONFIG command attempts to replace the corresponding CONFIG.SYS statements instead of merely appending to the file.

The following examples illustrate DSP file command lines that can follow the :CONFIG keyword command line:

:CONFIG  :MODE=PRIMARY
SET VIDEO_DEVICES=BIO_VGA
SET VIO_VGA=DEVICE(BVHVGA)
:CONFIG :MODE=PRIMARY :MODE=DOS
DEVICE=%BOOTDRIVE%:\OS2\MDOS\VVGA.SYS

OS2INI

This command specifies updates to an OS/2 INI system configuration file and performs in a similar manner to the DDINSTAL :OS2_INI keyword. However, it is more general in nature than DDINSTAL because it can be used to specify updates to any OS/2 INI file (such as OS2.INI or OS2SYS.INI).

Like its DDINSTAL counterpart, the DSPINSTL :INI command line is followed by a set of INI line entries, which are to be placed in the configuration file. However, the first line following the :OS2INI command line specifies the complete path name of the OS/2 INI file to be modified. Like the :FILES command, the optional drive specification within the complete path name is always overridden by the system's startup drive. If only a simple OS/2 INI file name is specified, the \OS2 directory on the system's startup drive is assumed.

The following example illustrates the DSP file command lines that can follow the :OS2INI keyword command line:

:OS2INI  :MODE=PRIMARY
OS2.INI
PM_DISPLAYDRIVERS IBMVGA32 IBMVGA32
PM_DISPLAYDRIVERS CURRENTDRIVER IBMVGA32

WININI

This command specifies updates to the WIN-OS/2 configuration file. It has no counterpart in DDINSTAL. Like the :OS2INI keyword, the :WININI key is followed by the name or complete path name of a WIN-OS/2 configuration file. If a simple file name is provided, it is assumed that the file resides in the \OS2\MDOS\WINOS2 directory on the system's startup drive.

The file name line is followed by a series of lines that will be placed in the specified WIN-OS/2 configuration file. Each WIN-OS/2 configuration line consists of three fields: <section>, <keyword>, and <value>. The section field identifies a section within the WIN-OS/2 configuration file.

In a similar manner to the :CONFIG command, an attempt is made to replace corresponding lines in the file rather than simply appending the lines to the specified section of the file. WIN-OS/2 configuration lines are typically of the form:

<keyword string> = <value string>

where the <value string> can actually be several substrings that are divided by spaces. Any field (section, keyword, value) can contain spaces if the field is enclosed in double quotation marks. The :WININI command operates by replacing lines in the specified section that match <command string> fields, or (if no match is found) by appending the new line at the end of the specified section.

The following example illustrates the DSP file command lines that can follow the :WININI command line:

:WININI :MODE=PRIMARY :MODE=WINDOWS
SYSTEM.INI
BOOT DISPLAY.DRV VGA.DRV
BOOT SDISPLAY.DRV SWINVGA.DR

RUN

This command is used to specify one or more programs to execute. The programs and their associated parameters are listed in the lines that follow the :RUN command.

Each program that is run can dynamically create DSP commands by writing them to its standard output device. When the program terminates, any DSP commands that were written to the standard output device are immediately interpreted by DSPINSTL. The dynamically created DSP commands are interpreted before any DSP file lines, which follow the :RUN program line, are interpreted. The program should use only the standard output device for the writing of DSP commands.

If a :RUN program generates output other than DSP lines, it must be redirected to another file or to NULL (see the following example).

:RUN
MYPROG.EXE >NUL 2>&1

The :RUN command ignores the return code from each of the programs that it executes. Each program specification line that follows the :RUN keyword command must adhere to the following format:

<program pathname> [<program parameters>]

The :RUN command can also be used to execute OS/2 command files (.CMD files).

SET_DRIVER

The :SET_DRIVER command is used to configure a 32-bit display driver for use by the 32-bit graphics engine. The parameters that are associated with this keyword are listed in the lines that follow the :SET_DRIVER command. These parameters are passed to the DspSetDriverInfo API that was discussed earlier in this chapter.

Each parameter is specified as a <keyword> = <value> pair.

The following list specifies the parameters that must be specified in the lines following the :SET_DRIVER command line. All the parameter values in this list are strings and must be enclosed in double quotation marks.

  • NAME = "<Name of display driver>"
  • DESC = "<String that describes driver driver (can be NULL)>"
  • PATHNAME = "<Name of display driver>"
  • PARMS = "<String containing parameters for driver (can be NULL)>"

Example:

:SET_DRIVER
NAME="IBMVGA32"
DESC="IBM VGA Display Driver"
PATHNAME="IBMVGA32"
PARMS=""

SET_RESOLUTION

The :SET_RESOLUTION command is used to inform the 32-bit graphics engine of the initial display resolution for the display driver that is being installed. This command is only necessary for display drivers that can support multiple display resolutions and use the DspDefaultResolution API to determine (during their initialization) which resolution to display. That API was described earlier in this chapter.

The parameters associated with this command are listed in the lines that follow the :SET_RESOLUTION command line. Each parameter is specified as a <keyword> = <value> pair.

The following list includes the parameters that must be specified after the :SET_RESOLUTION command line. All the parameter values in this list are numeric values and are specified as unsigned decimal numbers.

  • WIDTH = <Width of the display resolution in pels>
  • HEIGHT = <Height of the display resolution in pels>
  • COLORS = <Number of colors supported in this display resolution>
  • PLANES = <Number of planes in this display resolution>

Example:

:SET_RESOLUTION
WIDTH=1024
HEIGHT=768
COLORS=256
PLANES=1

Creating a Display Driver Installation Package

A complete display driver package will usually include the following types of files:

  • DSPINSTL utility program
  • A DLL, which includes the action routines (if action routines are used)
  • One or more .DSC configuration files (containing DSC entries for each separate driver package)
  • Display driver files (PM or WIN-OS/2 driver files)
  • Any other files to be copied (if necessary)
  • One or more DSP files (containing DSPINSTL installation and configuration commands)
  • Programs to be triggered by the :RUN commands in DSP files (as needed)

A display driver package can span multiple diskettes. If so, each diskette must include the DSP files that explain what to do with the files on the diskette. The display driver files (and related files) can be packed (by the PACK.EXE utility program). If the files are packed, their last file-name character must be set to the "&" character. DSC files, DSP files, the action routine DLL, and the DSPINSTL utility program must not be packed.