Default Primary

This action routine is invoked when the user accepts the primary display selection of the Video Display Configuration PM panel. The other three DSPINSTL action routines have identical calling sequences and return codes.

Syntax

Default_Primary(hWnd, dsp_stuc_ptr);

Parameters

hWnd (HWND) - input

The handle of the main DSPINSTL window.

dsp_stuc_ptr (PDSPINSTL_DATA) - input

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 the string that will be displayed in the Specify Source Directory PM panel that allows the user to override the default source directory for a given DSPINSTL step. The source directory name string, therefore, acts as the default source directory for that step. The string's inclusion in the global data structure provides the ability to modify the default source directory name to all action routines.

There are three service routines that 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

The various strings that are found in DSPINSTL data elements are typically initialized from string values found in DSPINSTL configuration file entries.

Return Code

rc (ULONG) - returns

Return codes.

Action routines return the following values:

0 - Indicates that no problems were encountered and DSPINSTL should proceed forward.

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. Note that the Cancel return code is supported so that DSPINSTL can back out of its current execution path.

0xFFFFFFFE - Is a reserved return code

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

Remarks

Action routines can perform whatever computation is necessary to modify the DSPINSTL data chain for eventual execution. Typically, action routines modify a key field within a data element, or they might add or subtract 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, persistent state setting should be performed by the commands within DSP files rather than by action routines.

The action routine communicates with the DSPINSTL utility program by setting the data chain element key values. Therefore, 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. (See DSPINSTL Service Functions).

Example Code

#include <os2.h>

HWND              hWnd;
PDSPINSTL_DATA    dsp_stuc_ptr;
ULONG             rc;            /*  Return codes. */

rc = Default_Primary(hWnd, dsp_stuc_ptr);