DDDR/2 - Installing and Configuring Display Device Drivers

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: The user can specify the type and resolution of the display driver to be installed. 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.) 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.)
 * Selecting the OS/2 display-driver characteristics
 * Copying display driver-related files
 * Updating the 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

You must reboot because you replaced the base video (SCREEN01.SYS and SCREEN02.SYS).
 * 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.
 * 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:                      - Primary .DSC file to install /SD:                      - Secondary .DSC file to install /RES: /u                                            - Run unattended Existing command-line parameters are case-insensitive and are as follows: /PK: /SK: /S: /T: /L1:

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
 * PRE_V3.DSC Example

DSPINSTL Architecture
DSPINSTL consists of the following major components: A set of standard Presentation Manager panels that serve as a basic front- end user interface. (See User Interface PM Panels for details.) A function that provides the optional addition of custom-control logic. (See Action Routine Interface for more information.) A set of standard service functions that can be called from within an action routine. (See DSPINSTL Service Functions.) 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. 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
 * Initial User Interface PM Panels
 * Action Routine Interface
 * Service Functions
 * Command Language PM Panels
 * Command Language Interpreter

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: 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:   /* Title strings are up to 256 characters. */

     /* DLL module, containing action routines    */ /*  for that type of adapter                */

   /* 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:            /* Initial key string assigned to this     */ /*  DSPINSTL data-chain element           */

 /* User prompt string displayed in the    */ /* Specify Source Directory panel when    */ /* the DSPINSTL data-chain element is     */ /* interpreted                            */

/* User prompt displayed in the Insert    */ /* Diskette panel displayed by the        */ /* Specify Source Directory panel logic   */

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

            /* 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  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. 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. 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. 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. 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. 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:

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: where:

  is a 2-character 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.

  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:  where:

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

 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)

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)

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:, and. 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: = where the 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 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: [ ] 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 = 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 = ""
 * DESC = ""
 * 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 = 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.