DDDR/2 - Installing and Configuring Display Device Drivers

From EDM2
Jump to: navigation, search
Display Device Driver Reference
Chapters
  1. 16-Bit VGA Display Driver
  2. 8514/A Display Driver
  3. 32-Bit VGA Display Driver
  4. 32-Bit Super VGA Display Driver
  5. SVGA Base Video Subsystem
  6. Physical Video Device Drivers
  7. Virtual Video Device Drivers
  8. Seamless Windows Support
  9. PM Palette Management Support
  10. Distributed Console Access Facility (DCAF)
  11. DBCS Video Driver Support
  12. Installing and Configuring Display Device Drivers
  13. Graphics Test Suites
  14. Display Test Tool
  15. VIDEOCFG.DLL Exported Functions
  16. VIDEOPMI.DLL Exported Functions
  17. VIDEO Protect-Mode Interface
Appendixes
  1. Data Types
  2. S3 Display Driver

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

The OS/2 Display Driver Installation utility program (DSPINSTL.EXE) provides all the facilities to install and configure OS/2 display drivers. In addition, DSPINSTL installs and configures Presentation Manager (PM) display drivers. It also can install and configure WIN-OS/2 (both full-screen and windowed) display drivers and install base video service (VIO) drivers and DOS virtual device drivers (VDDs).

Display-driver installation and configuration is more complex than it is for standard device drivers. Typically, display-driver installation and configuration includes the following activities:

  • Selecting the OS/2 display-driver characteristics

The user can specify the type and resolution of the display driver to be installed.

  • Copying display driver-related files

The user can copy 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 the system configuration files

The user can update some of the OS/2 and WIN-OS/2 configuration files to prepare a new display driver for subsequent execution when the user's system is restarted. (See Updating System Configuration Files.)

These activities are described in detail in the following overview of display-driver installation and configuration.

Overview

In some ways, DSPINSTL is similar to the OS/2 Device Driver Installation utility program, DDINSTAL.EXE, but DSPINSTL contains some extensions specifically designed to simplify the steps the user must perform to install and configure OS/2 display drivers. Different types of OS/2 display drivers can have radically different installation and configuration requirements; therefore, DSPINSTL has a set of features that enables you to customize the installation process to meet the user's needs.

Selecting OS/2 Display-Driver Characteristics

The user must specify whether the display driver being installed will be used for a primary or secondary display adapter. The user must then specify the type of display driver to install, 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 a high-resolution XGA display driver or a lower-resolution standard display driver such as Video Graphics Array (VGA) or Enhanced Graphics Adapter (EGA).

Some display drivers can support more than one graphics resolution, so the user might have to specify the display resolution at which the driver is to be operated. Typically, display resolutions are specified by supplying the width and height of the display (in pels) and the maximum number of colors that can be displayed simultaneously.

The user's choices for display resolution often are governed 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 affect which display resolutions will run.

Copying Display Driver-Related Files

Several factors can complicate the copying of display driver-related files from source directories to target directories. Display-driver files might be sufficiently large and numerous to fill more than one source diskette. This can easily occur when several display drivers, supporting different display resolutions, are bundled together on the same diskettes (along with their associated font and resource files).

To save space in the source directory, it might be desirable to use packed files. If so, however, the packed files must be unpacked when they are copied to the target directory. The display driver packager can specify file version checks to be made before the files are copied, because the checks can prevent the inadvertent replacement of updated display-driver files by older versions.

Updating System Configuration Files

After display driver-related files are copied to the user's system, the display-driver developer must update the different system configuration files to complete the installation. Frequently, the CONFIG.SYS and OS2.INI files must be updated to complete Presentation Manager display-driver installation, and the SYSTEM.INI and WIN.INI files must be updated to complete WIN-OS/2 display-driver installation. Depending on the driver being installed, other configuration files might also need updating.

DSPINSTL Installation Script Example

The installation of display drivers on OS/2 is done, in most cases, using IBM's display configuration tool DSPINSTL.EXE. When installing SVGA support, DSPINSTL.EXE calls a DOS program, SVGA.EXE, to create an SVGADATA.PMI file. The .PMI file is a data file containing all the information about the SVGA display adapter installed. DSPINSTL.EXE also uses SCREEN01.SYS for its detection; SVGA.EXE has some limited dependencies on SCREEN01.SYS as well. Because of these dependencies, installing BBS drivers is a two part process, as discussed below.

SVGA BBS Installations

Follow these steps to install BBS drivers:

Installation Part 1
  1. Replace both the base video and SVGA.EXE files.
  2. Copy the .DSC file used by DSPINSTL.EXE to the \OS2\INSTALL directory.
  3. Reboot the system.

You must reboot because you replaced the base video (SCREEN01.SYS and SCREEN02.SYS).

Installation Part 2
  1. After the reboot is completed, run DSPINSTL.EXE and select the correct display driver to install.
Installation will then proceed as normal.
2.When installation is completed, reboot again for the changes to take affect.

There is no standard way for IHVs to install Part 1 of the BBS installation process. Each vendor has their own command file that copies some files and tells the user to reboot and run DSPINSTL.EXE. In many cases, the video drivers that ship with the BBS diskette may work on OS/2 Warp, Version 3.0 only, not on OS/2 Version 2.1. In other words, it is currently difficult for vendors to install their drivers on different versions of OS/2.

There are two areas that need to be addressed:

  1. Create a standard way to accomplish part 1 of the installation of video drivers.
  2. Provide tools, such as a TESTVER.EXE and PRODUCT.EXE, along with a sample SETUP.CMD file for version-specific BBS installations.

The TESTVER program is used to test the version of the operating system installed. The PRODUCT program is used to inform the user what to do next at the end of part 1 of the BBS Installation process. PRODUCT is a PM program that brings up a dialog that can be customized by IHVs.

SETUP.CMD File Example

This example uses DSPINSTL.EXE to install part 1 of the BBS driver-installation process. The SETUP.CMD file is new. DSPINSTL.EXE was changed in OS/2 Warp, Version 3, to handle some new command-line parameters. As a result, DSPINSTL.EXE is now able to function more generically as an installation tool, not specific to display drivers.

The new command-line parameters in OS/2 Warp, Version 3, are case-insensitive and are as follows:

/PD:<path\dsc file name>                       - Primary .DSC file to install 
/SD:<path\dsc file name>                       - Secondary .DSC file to install 
/RES:<resolution for display driver to default to>
/u                                             - Run unattended

Existing command-line parameters are case-insensitive and are as follows:

/PK:<primary adapter type>
/SK:<secondary adapter type>
/S:<source path>
/T:<target drive>
/L1:<path to log file>

The sample SETUP.CMD file is shown below:

     Sample SETUP.CMD
     -------------------

     @if not exist echo.on ECHO OFF
     IF .%1. == .. GOTO USAGE
     IF .%2. == .. GOTO USAGE
     set src=%1
     set trg=%2
     set log=%trg%\os2\install\display.log
     set ver=3.0,2.11,2.1
     %src%\testver > %log%
     IF ERRORLEVEL 300 set dsc=%src%\v3.dsc&& GOTO VER_OK
     IF ERRORLEVEL 211 set dsc=%src%\pre_v3.dsc GOTO VER_OK
     IF ERRORLEVEL 210 set dsc=%src%\pre_v3.dsc GOTO VER_OK
     GOTO VER_NOT_OK
     :VER_OK
     set apath=%path%
     set  path=%src%;%path%
     if .%3. == .. set cid=&& goto skipcid
     set cid=/u
     :skipcid
     %src%\dspinstl.exe /s:%src% /t:%trg%\ /pd:%dsc% /l:%log% %cid%
     %src%\product.exe %src% %trg% %cid%
     set  path=%apath%
     GOTO END
     :VER_NOT_OK
     @ECHO This fixpack is intended for OS/2 versions %ver% only !
     @ECHO This fixpack is intended for OS/2 versions %ver% only ! >> %log%
     goto end
     :USAGE
     ECHO.
     ECHO Usage: %0 [SOURCE_PATH:] [BOOTDRIVE:] {[CID]}
     ECHO.
     ECHO Use the optional CID parameter for CID installs
     :END

As you can see from the sample SETUP.CMD, it is intended to be installed on OS/2 Warp, Version 3.0, and OS/2 Versions 2.11 and 2.1. When installing SETUP.CMD on OS/2 Warp, Version 3.0, use the V3.DSC file. When installing SETUP.CMD on OS/2 Versions 2.11 or 2.1, use PRE_V3.DSC file.

Examples of both V3.DSC and PRE_V3.DSC are shown below:

  • V3.DSC Example
V3.DSC
* Title
"V3 files"

* Action routine DLL
""

* Type key
"OTHER"

* # additional parameters specific to SVGA
"0"

* # of chain elements
"1"

***********************
* chain element = key, general prompt, diskette prompt, vol label, resolution
***********************
"V3PREREQS"
"Prerequisite files"
"BBS Diskette 1"
"WD2431 1"
""
  • PRE_V3.DSC Example
PRE_V3.DSC
* Title
"Pre-V3 files"

* Action routine DLL
""

* Type key
"OTHER"

* # additional parameters specific to SVGA
"0"

* # of chain elements
"1"

***********************
* chain element = key, general prompt, diskette prompt, vol label, resolution
***********************
"PREV3PREREQS"
"Prerequisite files"
"BBS Diskette 1"
"WD2431 1"
""

DSPINSTL Architecture

DSPINSTL consists of the following major components:

  • DSPINSTL Configuration File Interpreter
  • Initial User Interface PM Panels

A set of standard Presentation Manager panels that serve as a basic front- end user interface. (See User Interface PM Panels for details.)

  • Action Routine Interface

A function that provides the optional addition of custom-control logic. (See Action Routine Interface for more information.)

  • Service Functions

A set of standard service functions that can be called from within an action routine. (See DSPINSTL Service Functions.)

  • Command Language PM Panels

A set of standard PM panels that act as the front end to the DSPINSTL Command Language Interpreter as described in Command Language PM Panels.

  • Command Language Interpreter

The final stage of DSPINSTL, which executes the installation and configuration commands packed in the display-driver profile (DSP) files. (See DSPINSTL Command Language Interpreter for details)

DSPINSTL Configuration File Interpreter

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

Display configuration files are identifiable by a file-name extension of ".DSC". 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.

A set of display drivers can be packaged in any of the following ways:

Writing them to a diskette
Creating one or more display (DSP) files containing DSPINSTL installation and configuration commands
Creating a configuration file entry in a DSC file summarizing the key points concerning that display driver package
DSC files must be placed either in the directory containing the DSPINSTL utility program or in a directory contained in the user's DPATH. DSPINSTL checks its own directory first; then, if it cannot find a DSC file, it searches the DPATH, stopping when it finds a directory containing one or more DSC files. DSPINSTL reads all the DSC files it finds into that directory.

A configuration file entry includes the following information:

A title string identifying the driver in the initial DSPINSTL PM panels, " Primary Video Adapter" and "Secondary Video Adapter". These two panels enable the users to explicitly select which display drivers to install.
The name of the Dynamic Link Library (DLL) module, if any, containing action routines specific to the installation of that display-driver package.
A keyword string identifying whether the display drivers can handle a standard type of display adapter.

The following table lists the supported keyword strings:

Type of Adapter Keyword 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 keyword strings enable DSPINSTL to create a logical association with a display driver as a default type. The 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, the panel shows that the user's system has an 8514/A adapter as its primary display. If a DSC file entry contains a string of 8514, that file entry is chosen automatically if the user accepts the default choice by selecting the OK push button, without checking either the primary display or secondary display check boxes.

If more than one DSC file entry contains standard-type strings of 8514, DSPINSTL displays a PM panel to permit the user to resolve the ambiguity. If the user checks one of the two check boxes to indicate the desire to override the default logic and explicitly choose a driver, the PM panel that follows includes list-box choices for all the entries in the DSC files that DSPINSTL reads.

A default chain of data elements characterizing a sequence of installation and configuration steps that, in total, constitute the entire installation and configuration process. Each chain element can include the following data:
-A required default keyword string that triggers the interpretation of one or more DSP files in a given source directory.
-A required default prompt string, displayed in a PM panel, informing the user of the purpose of the next installation step. This prompt string helps the user decide which device or directory to point the utility program toward to accomplish that part of the installation.
-An optional default prompt string that tells the user which diskette to insert (assuming the next part of the installation is being performed from a diskette). This feature enables the display-driver packager to inform the user of the exact title that is written on a diskette.
-An optional diskette volume label that enables DSPINSTL to verify that the user has inserted the correct diskette.
-An optional display resolution string that can be used 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 in the chain for each diskette in the package. However, as the display-driver developer, you can use the data elements in the chain any way you want. For example, one data element might handle file copy commands, while the next might be used for configuration file updates.

The chain of data elements first is passed to the action routines; then, it is interpreted by the DSPINSTL Command Language Interpreter in the last part of the process. In this manner, you can create a default series of installation steps, dynamically modify those steps, and have the DSPINSTL Command Interpreter execute all the sub-steps within each step you created.

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

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

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

<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 following shows the format of the data-chain element subsection:

<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 indicating a default source directory choice; it is always assumed to be the logical A: drive. DSPINSTL provides a "Specify Source Directory" PM panel that enables the user to override the default source directory. The <Default General Prompt String> is displayed in that panel so the user knows 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 directly or in a sub- directory under the specified directory. The sub-directory name must be the same as the volume label for the entry, with underscore characters (_) replacing spaces. Volume labels are limited to 8 characters.

The following example is a typical Super VGA 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 that 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 sets the default internal key to Other. The user then can go to the "Primary Video Adapter" or "Secondary Video Adapter" Presentation Manager panels 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 (such as VGA) in the "Video Display Configuration" panel but does not permit the user to accept the default selection. The user must use either the primary display check box or the secondary display check box to override default DSPINSTL processing. This causes display of a secondary PM panel that permits 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 enable the user to specify whether primary or secondary display-driver installation is desired. The panels also permit 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 enables you to add optional custom-control logic that is executed after the user makes an initial selection. Action routines are supported so that the installation process can ask specialized questions of the user, through 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 to configure. Action routines are packaged in OS/2 DLL files.

Action routines tailor a display-driver installation by modifying the chain of data elements initialized by the DSPINSTL Configuration File Interpreter. You package DSPINSTL action routines in a DLL file, then include the name of the DLL file in the DSC file entry for that display-driver package. The DLL itself must be put in a directory within the user's LIBPATH or in the directory containing the DSPINSTL.EXE file.

DSPINSTL can call specified action routines (if they are provided in a DLL that can be named in the controlling configuration file entry) at four particular points during the beginning of the installation process:

When the user accepts DSPINSTL's selection in the initial "Video Display Configuration" PM panel of the primary display
When the user accepts DSPINSTL's selection in the initial "Video Display Configuration" PM panel of the secondary display
When the user overrides DSPINSTL's selection of the primary display by explicitly selecting a primary display on the "Primary Video Adapter" PM panel
When the user overrides DSPINSTL's selection of the secondary display by explicitly selecting a secondary display on the "Secondary Video Adapter" PM panel

The four action routines must have the following names:

Default_Primary()
Default_Secondary()
Selected_Primary()
Selected_Secondary().

You can provide any subset of the four action routines that you deem appropriate. When DSPINSTL reaches a point at which it tries to call an action routine, it uses DosLoadModuleto attempt loading of the DLL module. If successful, DSPINSTL then uses DosGetProcAddrto obtain the address of the action routine. If this is successful, DSPINSTL passes control to the action routine. If the attempt to obtain the address of the action routine is unsuccessful, DSPINSTL continues.

DSPINSTL assists the action routines by providing a set of service functions that enables them to perform various actions such as data-chain maintenance. Because of this assistance, an individual action routine does not have to be aware of the specific structure of a data-element chain. DSPINSTL insulates action routines from the details of the utility program' s internal structure, which greatly simplifies action-routine creation.

Each action routine is passed a pointer to a global DSPINSTL data structure that contains values the action routine can use. This data structure includes a Revisionfield (whose value always is set to 1 by the utility program) so that future revisions of DSPINSTL are able to grow and evolve the data structure. Action routines always must check the Revisionfield to determine how to access the data structure.

Procedure Call Interface for Action Routines

The four action routines follow the same procedure call interface, which is illustrated in Default_Primary Action Routine (below).

Default_Primary Action Routine

ULONG Default_Primary (hWnd, dsp_struc_ptr)

The Default_Primary action routine is invoked when the user accepts the primary display selection of the "Video Display Configuration" Presentation Manager panel.

Parameter Data Type Description
hWnd HWND Handle of the main DSPINSTL window
dsp_struc_ptr PDSPINSTL_DATA Pointer to the DSPINSTL data structure (see the following structure definition).

The global DSPINSTL data structure is defined as follows:

struct dspinstl_global_data
{
ULONG rev_num;                     /* Global DSPINSTL data structure revision number         */
PFN Link_Chain_Element_Ptr;        /* Address of the Link_Chain_Element service function     */
PFN Unlink_Chain_Element_Ptr;      /* Address of the Unlink_Chain_Element service function   */
PFN Next_Chain_Element_Ptr;        /* Address of the Next_Chain_Element service function     */
PFN Reserved_PTR1;                 /* Reserved                                               */
PFN Select_Display_Resolutions_Ptr;/* Address of Select_Display_Resolutions service function */
PFN Reserved_PTR2;                 /* Reserved                             */
PFN Reserved_PTR3;                 /* Reserved                             */
PFN Reserved_PTR4;                 /* Reserved                             */
PDSPINSTL_GLOBAL_DATA              /* Pointer to head of data element chain*/
PDSPINSTL_CHAIN_head               /* Pointer to head of data element chain*/
BOOL Reserved_Book                 /* Reserved                             */
PSZ pszSourceDirectory             /* Source directory name (ASCIIZ string)*/
ULONG ulSizeSource                 /* Size of source directory name buffer */
};

The source directory name string is displayed in the "Specify Source Directory" Presentation Manager panel that enables the user to override the default source directory for a given DSPINSTL step. As a result, the source directory name string acts as the default source directory for that step. The string's inclusion in the global data structure enables the user to modify the default source directory name to all action routines.

Remarks

Action routines can perform whatever computation and decision-making is necessary to modify the DSPINSTL data chain for eventual execution. Typically, action routines modify a key field within a data element, or they can add or subtract data-chain elements.

Generally, action routines should not change external system values, such as OS2.INI entries, because there is no guarantee that the user will not end the installation process after the action routine returns. Therefore, it is recommended that the persistent statesetting be performed by the commands in DSP files rather than by action routines.

An action routine communicates with the DSPINSTL utility program by setting the data-chain element key values. If an action routine sets several alternative key values in different chain elements, an equivalent set of DSP files (at least one for each alternative key value) must be provided in the eventual source directories or diskettes.

Note
The other DSPINSTL action routines have identical calling sequences and return codes. For that reason, the details of the procedure call interface for Default_Secondary(), Selected_Primary(), and Selected_ Secondary() are not included here.

Three service routines are provided to manipulate the data element chain. The following data structure characterizes a DSPINSTL data element:

struct dspinstl_chain_element
{
 ULONG rev_num;        /* DSPINSTL data chain element revision number    */

 PDSPINSTL_CHAIN next; /* Pointer to next DSPINSTL data chain element    */

 PSZ key;              /* Pointer to keyword string associated with this */
                       /*   chain element                                */

 PSZ general_prompt;   /* Pointer to the prompt string to be written in  */
                       /*   the Specify Source Directory panel when this */
                       /*   chain element is interpreted.  A NULL value  */
                       /*   indicates that the previous source directory */
                       /*   should be used again and that this panel     */
                       /*   should be bypassed for this chain element.   */

 PSZ diskette_prompt;  /* Pointer to the prompt string to be written in  */
                       /*   the Insert Diskette prompt panel             */

 PSZ volume_label;     /* Pointer to the (optional) diskette volume      */
                       /*   label string that is used to verify the      */
                       /*   correct identity of a DSP diskette           */

 PSZ resolution_string;/* Optional string that indicates a display driver*/
                       /*   resolution.  The string can be passed to     */
                       /*   Select_Display_Resolutions or left NULL      */
};
Note
Typically, the various strings found in DSPINSTL data elements are initialized from string values found in DSPINSTL configuration file entries.
Return Codes

Action routines return the following values:

0 Indicates that no problems were encountered and DSPINSTL should proceed.
0xFFFFFFFF Indicates that the action routine is returning a Cancel indication, which might be triggered by the user pressing a Cancel push button within a PM panel that was invoked by the action routine. Notice that the Cancel return code is supported so that DSPINSTL can back out of its current execution path.
0xFFFFFFFE A reserved return code.

All other non-zero values are interpreted as OS/2 system error codes.

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 in the pages that follow.

Link_Chain_Element
Unlink_Chain_Element
Next_Chain_Element
Select_Display_Resolutions

Link_Chain_Element

ULONG Link_Chain_Element (new_element_ptr, create_flag, position_flag, existing_element_ptr)

This service function provides a standard mechanism for linking data-chain elements in the DSPINSTL data chain. Optionally, this function can be used to allocate a new element, which then is linked into the chain. The caller indicates where in the chain 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 fill in the element's fields as appropriate.

Parameter Data Type Description
new_element_ptr PDSPINSTL_CHAIN Pointer. See details below.
create_flag USHORT Flag. See details below.
position_flag USHORT Flag. See details below.
existing_element_ptr PDSPINSTL_CHAIN Pointer to an existing data chain element. See details below.

new_element_ptr If create_flag is set to 1, this argument returns 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 Flag that indicates whether the caller wants the function to create a new element, or 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 new_ element_ptr) should be linked into the chain.

position_flag Flag that indicates where the caller wants 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 end of the chain. A value of 2 indicates that the element should be linked in front of the chain element pointed to by existing_element_ptr. A value of 3 indicates that the element should be linked after the chain element pointed to by existing_element_ptr.

existing_element_ptr If position_flag is set to 2 or 3 on input, this argument points to another data element in the chain.

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.

Unlink_Chain_Element

ULONG Unlink_Chain_Element (element_ptr)

This service function provides a standard mechanism for unlinking data-chain elements from the chain. It does not deallocate the memory associated with the element.

Parameter Data Type Description
element_ptr PDSPINSTL_CHAIN Pointer to a DSPINSTL data-chain element

This service function returns the following values:

0 Success.
1 Element could not be unlinked from chain.

Next_Chain_Element

ULONG Next_Chain_Element (next_element_ptr,position_flag existing_element_ptr)

This service function provides a standard mechanism for returning the address of specified data elements within the chain.

Parameter Data Type Description
next_element_ptr PDSPINSTL_CHAIN Returns a pointer to the specified chain element.
position_flag USHORT Flag. See details below.
existing_element_ptr PDSPINSTL_CHAIN Pointer to an existing data chain element. Used only if position_flag is set to 2 or 3.

position_flag A flag that indicates which data-chain element was specified by the caller, as follows:

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 pointed to by the existing_element_ptr input argument.
3 Indicates the data element that precedes the data element pointed to by the existing_element_ptr input argument.

This service function returns the following values:

0 Success
1 Next element found within the chain

Select_Display_Resolutions

ULONG Select_Display_Resolutions (hWnd, resolutions, num_resolutions)

The Select_Display_Resolutions service function is used by an action routine to determine which display resolutions are desired by the user as a result of this installation. The service function displays a "Select Display Resolutions" Presentation Manager panel that lets the user choose from display-resolution strings displayed in a scrolling list box within the panel.

The strings are passed to the function in an array of structures. A flag that is passed to the function controls whether the panel permits the user to select multiple or single display resolutions. On return from the function, each structure in the array contains a flag value that indicates whether that array element was selected by the user.

Parameter Data Type Description
hWnd HWND Handle of the main DSPINSTL window.
resolutions struct resolutions_struct Pointer to an array of display-resolution structures. See details below.
num_resolutions ULONG Number of display-resolution structures in the array.
fmultiple BOOL Flag that specifies whether the user is permitted to select multiple display resolutions. True indicates that multiple selections are permitted.

The resolutions parameter points 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.          */
};

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.

The action routine must create the array of display-resolution structures. It can use knowledge about the video hardware on the user's system to limit the resolution structures to only those that can be supported on the existing hardware.

Command Language PM Panels

During the final phase of DSPINSTL execution, each data-chain element triggers a separate DSPINSTL command-language interpretation step, using the command-language PM panels. One of these panels enables the user, optionally, to override the source directory to be used for this step. Another panel prompts the user to insert an appropriately labeled diskette. The remainder of the PM panels prompt the user when execution errors are encountered during this phase.

DSPINSTL Command Language Interpreter

The DSPINSTL Command Language Interpreter is used in the final phase of the DSPINSTL process. It interprets the contents of DSPINSTL display-driver profile (.DSP) files containing DSPINSTL commands. DSPINSTL commands specify the basic installation and configuration operations to be performed by the utility program. Each DSP file is tagged with a keyword string that identifies the file. To select a DSP file for interpretation, the DSPINSTL Command Language Interpreter traverses the data-element chain.

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

DSPINSTL Command Language

The DSPINSTL Command Language is highly flexible so that it can accommodate the many different operations that must be performed during 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 to tagthat DSP file. Then, when a data-chain element is interpreted by DSPINSTL, all DSP files in the current source directory that are tagged with that keyword are interpreted. This mechanism permits automatic execution.

The FILES command tells DSPINSTL which files to copy to the user's hard disk. Date/time checking and file-version checking can be performed as part of the FILES command processing; this helps prevent inappropriate copying of files, an important DSPINSTL safety feature. The FILES command supports the installation of both packed and unpacked files. Packed files can reduce greatly the amount of space consumed on the display-driver developer's diskettes.

The CONFIG, OS2INI, and WININI commands tell DSPINSTL how to update the configuration in the different types of system configuration files. Three separate commands are used because the different types of OS/2 system configuration files require different editing styles. Configuration of OS/2 display drivers is particularly tricky because of the coordinated updates needed in the different OS/2 configuration files.

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).

SET_DRIVER and SET_RESOLUTION also are configuration editing commands. With these two commands, rather than editing a specific configuration file, an OS/2 graphics engine (Gre) function updates the system configuration. This additional level of data abstraction is necessary to support the architecture of the graphics engine, which is yet another complexity supported by the DSPINSTL Command Language.

DSPINSTL Commands

The DSPINSTL Command Language is similar to the DDINSTAL Command Language, in that the DSPINSTL Command Language Interpreter accepts comments in the form of lines beginning with an asterisk (*). However, the DSPINSTL Command Language contains important keyword extensions.

USAGE NOTE
All keywords must be in uppercase and preceded by a full colon (:), as shown in the following list of commands.

The DSPINSTL Command Language files support the following commands:

KEY
FILES
CONFIG
DEL_CONFIG_LINE
AUTO_EXEC
OS2INI
TITLE
WININI
RUN
SET_DRIVER
SET_RESOLUTION.

A MODE qualifier is valid on all DSPINSTL commands except :KEY. Valid MODE qualifier values and their descriptions are shown in the following list:

PRIMARY Execute this command only if the user is performing a primary display-driver installation.
SECONDARY Execute this command only if the user is performing a secondary display-driver installation.
DOS Execute this command if DOS support is installed on the OS/2 system.
WINDOWS Execute this command if WIN-OS/2 support is installed.

KEY Command

The KEY command identifies a DSP file with a unique keyword string so that it automatically can be selected for interpretation by DSPINSTL. The final phase 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 format of the KEY command line is :KEY.

The DSP file line immediately following the KEY command line contains a keyword 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 in a keyword string. Keyword strings can be up to 64 bytes in length. The following is an example of a KEY command line.

:KEY
XYZ_800x600x16

There must be only one :KEY command line in each DSP file.

FILES Command

The FILES command specifies the files that are to be copied from the source directory to different destination directories. It performs similarly 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 DDINSTAL, the DSPINSTL FILES command uses the UNPACK utility program to copy files, so that it can handle both packed and unpacked file formats.

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

The format of the FILES command line is :FILES.

To protect against inadvertently copying an old version of a file over a newer version, all file copying is mediated by one of two different forms of file-version checks, as listed below:

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 headers, which can be set during program linking. The following is an example of a file-version string:

<header> <version string> <trailer>

where:

<header> is a 2-character string: @#.

<version string> is 12 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). The file-version number can be interpreted as a floating point number or an integer.

<trailer> is the 2-character string: #@.

An example of a file-version string is:

@#IBM:0006.307#@.

If both the source and target versions of a file contain file-version strings, file-version checking is performed. For a file-version check to be considered successful, the vendor IDs 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, 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, the source file is assumed to be more recent than the target file and is copied over the target file.

Date/Time Checking

DSPINSTL does not automatically copy an old 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 the file with the older version.

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

<source file name> <destination directory pathname>

where:

<source file name> is the name of a file in the source directory that contains the DSP file. A source file can be packed or unpacked.

<destination directory pathname> can include an optional logical drive letter specification that always is overridden by the system's startup drive. The destination directory path name is not a complete file name, which 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 permit path names to be specified. %BOOTDRIVE%is a special drive designator that indicates the letter of the drive 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 packed, the file is copied to the directory specified in the source file's pack header. If there is no corresponding directory on the drive, a directory is created. If no destination directory is provided and the source file is unpacked, the file is copied to the current working directory.

The following examples illustrate DSP file command lines that can follow the FILES 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
Some of the source-file names are immediately followed by the "@" sign, indicating that these are packed files (packed by the OS/2 PACK utility program).

CONFIG Command

The CONFIG command specifies updates to the CONFIG.SYS file, functioning similarly to the DDINSTAL CONFIG command. Like its DDINSTAL counterpart, the DSPINSTL CONFIG command line is followed by a set of CONFIG.SYS statements that are to be added to the configuration file. However, the DSPINSTL CONFIG command attempts to replace corresponding CONFIG.SYS statements instead of appending them to the file.

The format of the CONFIG command line is :CONFIG.

The following examples illustrate DSP file command lines that can follow the CONFIG 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

DEL_CONFIG_LINE Command

This command is used to delete specific lines in a CONFIG.SYS file.

The format of the DEL_CONFIG_LINE command line is :DEL_CONFIG_LINE.

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

 :DEL_CONFIG_LINE  :MODE=PRIMARY
 SET VIDEO_DEVICES=BIO_VGA
 SET VIO_VGA=DEVICE(BVHVGA)

 :DEL_CONFIG_LINE :MODE=PRIMARY :MODE=DOS
 DEVICE=%BOOTDRIVE%:\OS2\MDOS\VVGA.SYS

AUTO_EXEC Command

This command is used to update the AUTOEXEC.BAT file.

OS2INI Command

The OS2INI command specifies updates to an OS/2 INI system configuration file, functioning similarly to the DDINSTAL OS2INI keyword. However, the DSPINSTL OS2INI command 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).

The format of the OS2INI command lines is :OS2INI.

Like its DDINSTAL counterpart, the DSPINSTL OS2INI command line is followed by a set of INI line entries, which are added to the configuration file. 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 in the complete path name always is 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 examples illustrate the DSP file command lines that can follow the OS2INI command line:

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

TITLE Command

This command is not used.

WININI

The WININI command specifies updates to the WIN-OS/2 configuration file. It has no counterpart in DDINSTAL. Like the OS2INI keyword, the WININI keyword 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 format of the WININI command lines is :WININI.

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>. Section identifies a section in the WIN-OS/2 configuration file.

Similar to that for the CONFIG command, an attempt is made to replace corresponding lines in the file rather than appending the lines to the specified section of the file. Typically, WIN-OS/2 configuration lines are of the form:

<keyword string> = <value string>

where the <value string> actually can be several sub-strings divided by spaces. Any of the fields (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 examples illustrate 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 Command

The RUN command is used to specify one or more programs to execute. The specified programs and their associated parameters are listed in the lines following the RUN command.

The format of the RUN command line is :RUN.

Each program that is run can create DSP commands dynamically by writing them to that program's standard output device. When the program terminates, any DSP commands written to the output device are interpreted immediately by DSPINSTL. The dynamically created DSP commands are interpreted before the DSP file lines following the RUN program line are interpreted. The program must use only its standard output device for writing DSP commands.

If a RUN-specified program generates output other than DSP lines, it must be redirected to another file or to NULL. (See the example below.)

:RUN
 MYPROG.EXE >NUL 2>&1

The RUN command ignores the return code from the programs 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 also can be used to execute OS/2 command files (.CMD).

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 associated with this keyword will be listed in the lines that follow the SET_DRIVER command. These parameters are passed to the DspSetDriverInfo function.

The format of the SET_DRIVER command line is :SET_DRIVER. Each parameter is specified as a <keyword> = <value> pair.

The following lists 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 display driver (can be NULL)>"
PATHNAME = "<Name of display driver>"
PARMS = "<String containing parameters for driver (can be NULL)>"

Following is an example of how to specify the parameter values used with the SET_DRIVER keyword command:

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

SET_RESOLUTION

The SET_RESOLUTION command informs the 32-bit graphics engine of the initial display resolution for the display driver being installed. This command is used only for display drivers that can support multiple display resolutions and that use the DspDefaultResolution function to determine, during initialization, which resolution to display.

The format of the SET_RESOLUTION command line is: SET_RESOLUTION.

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

The following lists 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>

Following is an example of how to specify the parameters associated with the SET_RESOLUTION keyword command:

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

Creating a Display-Driver Installation Package

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

DSPINSTL utility program
DLL, including the action routines (if action routines are used)
One or more DSC configuration files (containing DSC entries for each driver package)
Display driver files (PM or WIN-OS/2)
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.