## Display Device Driver Reference for OS/2

[prev][next][parent][TOC]

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