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

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

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

• Accepts the selection of the primary display (in the initial Video Display Configuration PM panel)

• Accepts the selection of the secondary display (in the initial Video Display Configuration PM panel)

• Overrides the selection of the primary display and explicitly selects a primary display (through the use of a Primary Video Adapter PM panel)

• Overrides the selection of the secondary display and explicitly selects a secondary display (through the use of a Secondary Video Adapter PM panel)

The four action routines must have the following names:

• Default_Primary()

• Default_Secondary()

• Selected_Primary()

• Selected_Secondary()

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

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

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