home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / FILEDLG6.ZIP / ERRMSG.ZIP / ERRMSG.TXT < prev    next >
Text File  |  1990-11-14  |  8KB  |  208 lines
  1. .context List Categories
  2. .list
  3. Standard error handler
  4. .context Standard error handler
  5. .list
  6. ErrMessageBox   Standard PM error message function.
  7. ERRORMSG        Record structure used in a user defined error message list.
  8. .context ERRORMSG
  9. .context PERRORMSG
  10. .ref ErrMessageBox
  11. #define INCL_WINDIALOGS
  12. #include <os2.h>
  13. #include <errmsg.h>
  14.  
  15. typedef struct {
  16.     USHORT  usCode;         // error code
  17.     USHORT  flStyle;        // message box style (see explanation below)
  18.     PSZ     pszMsg;         // ptr to error message text
  19.     } ERRORMSG;
  20.  
  21. typedef ERRORMSG FAR * PERRORMSG;
  22.  
  23. The \bERRORMSG\p structure defines the record structure used in a user defined
  24. error message list used by the \bErrMessageBox\p function.
  25.  
  26. \bParameters  Description\p
  27. ────────────────────────────────────────────────────────────────────────────
  28. \busCode\p      Error code.
  29.  
  30. \bflStyle\p     Specifies the type of message-box window created. This parameter
  31.             consists of a button flag, an icon flag, a default button flag,
  32.             and any number of special flags. The following four lists
  33.             describe the available flags which can be combined using the OR
  34.             operator together for this parameter:
  35.  
  36.             \bButtons              Meaning\p
  37.             ────────────────────────────────────────────────────────────────
  38.             \iMB_ABORTRETRYIGNORE\p  Message box contains Abort, Retry, and
  39.                                  Ignore push buttons.
  40.  
  41.             \iMB_ENTER\p             Message box contains an Enter push button.
  42.  
  43.             \iMB_ENTERCANCEL\p       Message box contains Enter and Cancel push
  44.                                  buttons.
  45.  
  46.             \iMB_OK\p                Message box contains an OK push button.
  47.  
  48.             \iMB_OKCANCEL\p          Message box contains OK and Cancel push
  49.                                  buttons.
  50.  
  51.             \iMB_RETRYCANCEL\p       Message box contains Retry and Cancel push
  52.                                  buttons.
  53.  
  54.             \iMB_YESNO\p             Message box contains Yes and No push
  55.                                  buttons.
  56.  
  57.             \iMB_YESNOCANCEL\p       Message box contains Yes, No, and Cancel
  58.                                  push buttons.
  59.  
  60.             \bIcon                Meaning\p
  61.             ────────────────────────────────────────────────────────────────
  62.             \iMB_ICONASTERISK\p     Message box contains asterisk icon.
  63.  
  64.             \iMB_ICONEXCLAMATION\p  Message box contains exclamation-point
  65.                                 icon.
  66.  
  67.             \iMB_ICONHAND\p         Message box contains hand icon.
  68.  
  69.             \iMB_ICONQUESTION\p     Message box contains question-mark icon.
  70.  
  71.             \iMB_NOICON\p           Message box does not contain an icon.
  72.  
  73.             \bDefault button  Meaning\p
  74.             ────────────────────────────────────────────────────────────────
  75.             \iMB_DEFBUTTON1\p   First button is the default (first button is
  76.                             always the default unless MB_DEFBUTTON2 or
  77.                             MB_DEFBUTTON3 is specified).
  78.  
  79.             \iMB_DEFBUTTON2\p   Second button is the default.
  80.  
  81.             \iMB_DEFBUTTON3\p   Third button is the default.
  82.  
  83.             \bSpecial flags   Meaning\p
  84.             ────────────────────────────────────────────────────────────────
  85.             \iMB_APPLMODAL\p    Message box is application modal.
  86.  
  87.             \iMB_SYSTEMMODAL\p  Message box is system modal.
  88.  
  89.             \iMB_HELP\p         Message box contains Help push button.
  90.  
  91.             \iMB_MOVEABLE\p     Message box is movable.
  92.  
  93. \bpszMsg\p      Points to the error message text.
  94.  
  95.  
  96. \bSee Also\p
  97.  
  98.     \bErrMessageBox\p
  99. .context ErrMessageBox
  100. .ref ERRORMSG,PERRORMSG,WinMessageBox,WinFlashWindow,WM_HELP
  101. #define INCL_WINDIALOGS
  102. #include <os2.h>
  103. #include <errmsg.h>
  104.  
  105. .paste Syntax
  106. USHORT \bErrMessageBox\p( \ihwndOwner\p,\ipszCaption\p,\iusErrorCode\p,
  107.                       \iperrormsg\p,\icErrMsgCnt\p,[argument]... )
  108. HWND \ihwndOwner\p;         /* owner window handle                          */
  109. PSZ \ipszCaption\p;         /* message box window title                     */
  110. USHORT \iusErrorCode\p;     /* error code                                   */
  111. PERRORMSG \iperrormsg\p;    /* pointer to user defined error list           */
  112. USHORT \icErrMsgCnt\p;      /* number of items in user defined error list   */
  113. .end
  114.  
  115. The \bErrMessageBox\p function creates, displays, and operates a message-box
  116. window that displays the error message associated with a given error
  117. code.
  118.  
  119. \bParameters  Description\p
  120. ────────────────────────────────────────────────────────────────────────────
  121. \ihwndOwner\p   Identifies the owner window of the message-box window. The owner
  122.             window is activated when ErrMessageBox returns.
  123.  
  124. \ipszCaption\p  Points to the title of the message-box window. If this parameter
  125.             is NULL, "Error" (the default title) is displayed. The maximum
  126.             length of the text is device-dependent. If the text is too long,
  127.             it will be clipped.
  128.  
  129. \iusErrorCode\p Contains the error code.
  130.  
  131. \iperrormsg\p   Points to the user defined error message list. If this
  132.             parameter is NULL then the error message list appropriate
  133.             to the error code will be used (SysErrMsg or PMErrMsg).
  134.  
  135.             The following error message lists are predefined:
  136.  
  137.                 SysErrMsg    : system error messages for error codes
  138.                                less that 0x1000 or above or equal to
  139.                                0x8000.
  140.  
  141.                 PMErrMsg     : PM error messages for error codes between
  142.                                0x1000 and 0x8000.
  143.  
  144.                 HlpMgrErrors : Help manager error messages.
  145.  
  146. \icErrMsgCnt\p  Contains the number of items in the user defined error message
  147.             list. This parameter is ignored if perrormsg is NULL.
  148.  
  149. \iargument\p    Optional list of arguments that are passed to the
  150.             vsprintf function in order to allow error messages to have
  151.             variable contents. NOTE THAT THIS FUNCTION REQUIRES THAT ALL
  152.             POINTER ARGUMENTS (SUCH AS POINTERS TO STRINGS) MUST BE FAR
  153.             POINTERS.
  154.  
  155. \bReturn Value\p
  156.  
  157. The return value indicates the user's response to the message. It can be one
  158. of the following vlaues:
  159.  
  160.     \bValue        Meaning\p
  161.     ────────────────────────────────────────────────────────────────────────
  162.     \iMBID_ABORT\p   Abort button was selected.
  163.  
  164.     \iMBID_CANCEL\p  Cancel button was selected.
  165.  
  166.     \iMBID_ENTER\p   Enter button was selected.
  167.  
  168.     \iMBID_IGNORE\p  Ignore button was selected.
  169.  
  170.     \iMBID_NO\p      No button was selected.
  171.  
  172.     \iMBID_OK\p      OK button was selected.
  173.  
  174.     \iMBID_RETRY\p   Retry button was selected.
  175.  
  176.     \iMBID_YES\p     Yes button was selected.
  177.  
  178.     \iMDID_ERROR\p   The WinMessageBox function failed--an error occurred.
  179.  
  180. If a message box has a Cancel button, MBID_CANCEL is returned if the ESCAPE
  181. key is pressed or if the Cancel button is selected. If the message box has
  182. no Cancel button, pressing the ESCAPE key has no effect.
  183.  
  184. \bComments\p
  185.  
  186. If a message-box window is created as part of the processing of a dialog
  187. window, the dialog window should be made the owner of the message-box
  188. window.
  189.  
  190. If a system modal message-box window is created to tell the user that the
  191. system is running out of memory, the strings passed into this function
  192. should not be taken from a resource file because an attempt to load the
  193. resource file may fail due to lack of memory. Such a message-box window can
  194. safely use the hand icon (MB_ICONHAND), however, because this icon is always
  195. memory-resident.
  196.  
  197. If the message box contains a help pushbutton, the message box window
  198. identifier will be set to the error code value.
  199.  
  200. The total length of the error message string after it has been formatted
  201. and stored by vsprintf must not exceed 512 characters (including the
  202. terminating NULL character).
  203.  
  204.  
  205. See Also
  206.  
  207.     \bERRORMSG\p, \bWinMessageBox\p, \bWinFlashWindow\p, \bWM_HELP\p
  208.