SplMessageBox

SplMessageBox creates and displays a message box.

The message queue will be created (and destroyed) if necessary. In OS/2 2.1, this API may return Retry automatically if the PM message box is displayed for more than three minutes.

Syntax

Response = SplMessageBox(pszAddress, flErrorInfo, flErrorData, pszText, pszCaption, idWindow, fsStyle);

Parameters

pszAddress (PSZ) - input

Pointer to a string containing the logical address of the device, such as LPT1.

flErrorInfo (ULONG) - input

Error information.

One of the following flags must be set to identify where the error occurred:

• SPLINFO_QPERROR Spooler queue processor error
• SPLINFO_DDERROR Presentation driver error
• SPLINFO_SPLERROR Spooler error
• SPLINFO_OTHERERROR Any other error

One of the following flags is also set to indicate the severity of the error:

• SPLINFO_INFORMATION Information only, no error.
• SPLINFO_WARNING Warning.
• SPLINFO_ERROR Recoverable error.
• SPLINFO_SEVERE Severe, unrecoverable error.
• SPLINFO_USERINTREQD This flag is optional. It shows that recovery requires action from the user.

flErrorData (ULONG) - input

Length of the data in bytes.

Error data:

• SPLDATA_PRINTERJAM Printer is jammed, offline, or not turned on
• SPLDATA_FORMCHGREQD Form change required
• SPLDATA_CARTCHGREQD Font cartridge change required
• SPLDATA_PENCHGREQD Pen change required
• SPLDATA_DATAERROR Data error, such as missing file
• SPLDATA_UNEXPECTERROR Unexpected DOS error
• SPLDATA_OTHER Any other error

pszText (PSZ) - input

Pointer to the text string for the message box.

pszCaption (PSZ) - input

Pointer to a string containing a meaningful title for the message box.

The text is centered in the title bar. If more than 40 characters are supplied, excess characters at the beginning and end of the string are not displayed.

idWindow (ULONG) - input

Window ID of the message box window.

fsStyle (ULONG) - input

Bit array specifying the contents and function of the message box.

Return Code

Response (ULONG) - returns

Return codes.

This function returns a ULONG value (sResponse) that indicates the user's response.

MBID_ENTER ENTER push button was selected MBID_OK OK push button was selected MBID_CANCEL CANCEL push button was selected MBID_ABORT ABORT push button was selected MBID_RETRY RETRY push button was selected MBID_IGNORE IGNORE push button was selected MBID_YES YES push button was selected MBID_NO NO push button was selected MBID_ERROR Function not successful; an error occurred.

Remarks

SplMessageBox creates a message queue if the current thread does not have one.

SplMessageBox is similar to WinMessageBox.

Example Code

#include <os2.h>

PSZ      pszAddress;   /*  Pointer to a string containing the logical address of the device, such as LPT1. */
ULONG    flErrorInfo;  /*  Error information. */
ULONG    flErrorData;  /*  Length of the data in bytes. */
PSZ      pszText;      /*  Pointer to the text string for the message box. */
PSZ      pszCaption;   /*  Pointer to a string containing a meaningful title for the message box. */
ULONG    idWindow;     /*  Window ID of the message box window. */
ULONG    fsStyle;      /*  Bit array specifying the contents and function of the message box. */
ULONG    Response;     /*  Return codes. */

Response = SplMessageBox(pszAddress, flErrorInfo,
             flErrorData, pszText, pszCaption,
             idWindow, fsStyle);