Difference between revisions of "DosGetMessage (OS/2 1.x)"

From EDM2
Jump to: navigation, search
m
m
 
(One intermediate revision by one user not shown)
Line 5: Line 5:
  
 
==Parameters==
 
==Parameters==
;IvTable (PCHAR FAR *) - input : Address of a list of double-word pointers. Each pointer points to an ASCIIZ or null-terminated DBCS string (variable insertion text). 0 to 9 strings can be present.
+
;IvTable (PCHAR FAR *) - input: Address of a list of double-word pointers. Each pointer points to an ASCIIZ or null-terminated DBCS string (variable insertion text). 0 to 9 strings can be present.
;IvCount (USHORT) - input : Count of variable insertion text strings is 0-9. If IvCount is 0, IvTable is ignored.
+
;IvCount (USHORT) - input: Count of variable insertion text strings is 0-9. If IvCount is 0, IvTable is ignored.
;DataArea (PCHAR) - output : Address of the requested message. If the message is too long to fit in the caller's buffer, as much of the message text is returned as possible, with the appropriate error return code.
+
;DataArea (PCHAR) - output: Address of the requested message. If the message is too long to fit in the caller's buffer, as much of the message text is returned as possible, with the appropriate error return code.
;DataLength (USHORT) - input : Length, in bytes, of the user's storage area.
+
;DataLength (USHORT) - input: Length, in bytes, of the user's storage area.
;MsgNumber (USHORT) - input : Requested message number.
+
;MsgNumber (USHORT) - input: Requested message number.
;FileName (PSZ) - input : Address of the optional drive, path, and filename of the file where the message can be found. If messages are bound to the .EXE file using MSGBIND utility, then filename is the name of the message file from which the messages are extracted.
+
;FileName (PSZ) - input: Address of the optional drive, path, and filename of the file where the message can be found. If messages are bound to the .EXE file using MSGBIND utility, then filename is the name of the message file from which the messages are extracted.
;MsgLength (PUSHORT) - output : Address of the length, in bytes, of the message.
+
;MsgLength (PUSHORT) - output: Address of the length, in bytes, of the message.
  
 
==Return Code==
 
==Return Code==
rc (USHORT) - return
+
;rc (USHORT) - return:Return code descriptions are:
Return code descriptions are:
+
*0 NO_ERROR
* 0   NO_ERROR
+
*2 ERROR_FILE_NOT_FOUND
* 2   ERROR_FILE_NOT_FOUND  
+
*206 ERROR_FILENAME_EXCED_RANGE
* 206 ERROR_FILENAME_EXCED_RANGE  
+
*316 ERROR_MR_MSG_TOO_LONG
* 316 ERROR_MR_MSG_TOO_LONG  
+
*317 ERROR_MR_MID_NOT_FOUND
* 317 ERROR_MR_MID_NOT_FOUND  
+
*318 ERROR_MR_UN_ACC_MSGF
* 318 ERROR_MR_UN_ACC_MSGF  
+
*319 ERROR_MR_INV_MSFG_FORMAT
* 319 ERROR_MR_INV_MSFG_FORMAT  
+
*320 ERROR_MR_INV_IVCOUNT
* 320 ERROR_MR_INV_IVCOUNT  
+
*321 ERROR_MR_UN_PERFORM
* 321 ERROR_MR_UN_PERFORM
+
  
 
==Remarks==
 
==Remarks==
Line 35: Line 34:
 
The following is an example of a sample error message returned with the message ID:
 
The following is an example of a sample error message returned with the message ID:
 
  SYS0100: File not found
 
  SYS0100: File not found
 
 
DosGetMessage retrieves messages previously prepared by the utility MKMSGF to create a message file, or MSGBIND to bind a message segment to an .EXE file. DosGetMessage tries to retrieve the message from RAM in the message segment bound to the .EXE program. If the message cannot be found, DosGetMessage retrieves the message from the message file on DASD (direct access storage device, such as a diskette or fixed-disk).
 
DosGetMessage retrieves messages previously prepared by the utility MKMSGF to create a message file, or MSGBIND to bind a message segment to an .EXE file. DosGetMessage tries to retrieve the message from RAM in the message segment bound to the .EXE program. If the message cannot be found, DosGetMessage retrieves the message from the message file on DASD (direct access storage device, such as a diskette or fixed-disk).
  
 
If the file name is not a fully-qualified name, DosGetMessage searches the following directories for default drive and path:
 
If the file name is not a fully-qualified name, DosGetMessage searches the following directories for default drive and path:
* The system root directory  
+
* The system root directory
* The current working directory  
+
* The current working directory
* Directories listed in the DPATH statement (OS/2 mode only)  
+
* Directories listed in the DPATH statement (OS/2 mode only)
* Directories listed in the APPEND statement (DOS mode only).  
+
* Directories listed in the APPEND statement (DOS mode only).
 
+
 
If a message cannot be retrieved because of a DASD error or file not found condition, a default message is placed in the user's buffer area. A message is placed in the buffer area based on the following error conditions:
 
If a message cannot be retrieved because of a DASD error or file not found condition, a default message is placed in the user's buffer area. A message is placed in the buffer area based on the following error conditions:
* The message number cannot be found in the message file.  
+
* The message number cannot be found in the message file.
* The message file cannot be found.  
+
* The message file cannot be found.
* The system detected a disk error trying to access the message file, or the message file format is incorrect.  
+
* The system detected a disk error trying to access the message file, or the message file format is incorrect.
* IvCount is out of range.  
+
* IvCount is out of range.
* A system error occurred trying to allocate storage.  
+
* A system error occurred trying to allocate storage.
 
+
 
When these conditions occur, the default message allows the application program to issue a message and prompt that enables recovery opportunity.
 
When these conditions occur, the default message allows the application program to issue a message and prompt that enables recovery opportunity.
  
Line 60: Line 56:
 
Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction applies to DosGetMessage when coding for the DOS mode:
 
Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction applies to DosGetMessage when coding for the DOS mode:
  
If the message file name is not a fully qualified name, DosGetMessage searches the root directory of the default drive for the message file, instead of the root directory of the startup drive.  
+
If the message file name is not a fully qualified name, DosGetMessage searches the root directory of the default drive for the message file, instead of the root directory of the startup drive.
==Example Code==
+
 
===C Binding===
+
==Bindings==
 +
===C===
 
<PRE>
 
<PRE>
 
#define INCL_DOSMISC
 
#define INCL_DOSMISC
Line 69: Line 66:
 
                             MsgNumber, FileName, MsgLength);
 
                             MsgNumber, FileName, MsgLength);
  
PCHAR FAR *     IvTable;       /* Table of variables to insert */
+
PCHAR FAR *   IvTable;     /* Table of variables to insert */
USHORT           IvCount;       /* Number of variables */
+
USHORT       IvCount;     /* Number of variables */
PCHAR           DataArea;     /* Message buffer (returned) */
+
PCHAR         DataArea;   /* Message buffer (returned) */
USHORT           DataLength;   /* Length of buffer */
+
USHORT       DataLength; /* Length of buffer */
USHORT           MsgNumber;     /* Number of the message */
+
USHORT       MsgNumber;   /* Number of the message */
PSZ             FileName;     /* Message file path name string */
+
PSZ           FileName;   /* Message file path name string */
PUSHORT         MsgLength;     /* Length of message (returned) */
+
PUSHORT       MsgLength;   /* Length of message (returned) */
  
USHORT           rc;           /* return code */
+
USHORT       rc;         /* return code */
 
</PRE>
 
</PRE>
  
===MASM Binding===
+
===MASM===
 
<PRE>
 
<PRE>
 
EXTRN  DosGetMessage:FAR
 
EXTRN  DosGetMessage:FAR
 
INCL_DOSMISC      EQU 1
 
INCL_DOSMISC      EQU 1
  
PUSH@  OTHER  IvTable       ;Table of variables to insert
+
PUSH@  OTHER  IvTable     ;Table of variables to insert
PUSH  WORD    IvCount       ;Number of variables
+
PUSH  WORD    IvCount     ;Number of variables
PUSH@  OTHER  DataArea     ;Message buffer (returned)
+
PUSH@  OTHER  DataArea   ;Message buffer (returned)
PUSH  WORD    DataLength   ;Length of buffer
+
PUSH  WORD    DataLength ;Length of buffer
PUSH  WORD    MsgNumber     ;Number of the message
+
PUSH  WORD    MsgNumber   ;Number of the message
PUSH@  ASCIIZ  FileName     ;Message file path name string
+
PUSH@  ASCIIZ  FileName   ;Message file path name string
PUSH@  WORD    MsgLength     ;Length of message (returned)
+
PUSH@  WORD    MsgLength   ;Length of message (returned)
 
CALL  DosGetMessage
 
CALL  DosGetMessage
  
Line 97: Line 94:
 
</PRE>
 
</PRE>
  
[[Category:Dos]]
+
[[Category:Dos16]]

Latest revision as of 23:19, 25 January 2020

This call retrieves a message from a message file and inserts variable information into the body of the message.

Syntax

DosGetMessage (IvTable, IvCount, DataArea, DataLength, MsgNumber, FileName, MsgLength)

Parameters

IvTable (PCHAR FAR *) - input
Address of a list of double-word pointers. Each pointer points to an ASCIIZ or null-terminated DBCS string (variable insertion text). 0 to 9 strings can be present.
IvCount (USHORT) - input
Count of variable insertion text strings is 0-9. If IvCount is 0, IvTable is ignored.
DataArea (PCHAR) - output
Address of the requested message. If the message is too long to fit in the caller's buffer, as much of the message text is returned as possible, with the appropriate error return code.
DataLength (USHORT) - input
Length, in bytes, of the user's storage area.
MsgNumber (USHORT) - input
Requested message number.
FileName (PSZ) - input
Address of the optional drive, path, and filename of the file where the message can be found. If messages are bound to the .EXE file using MSGBIND utility, then filename is the name of the message file from which the messages are extracted.
MsgLength (PUSHORT) - output
Address of the length, in bytes, of the message.

Return Code

rc (USHORT) - return
Return code descriptions are:
  • 0 NO_ERROR
  • 2 ERROR_FILE_NOT_FOUND
  • 206 ERROR_FILENAME_EXCED_RANGE
  • 316 ERROR_MR_MSG_TOO_LONG
  • 317 ERROR_MR_MID_NOT_FOUND
  • 318 ERROR_MR_UN_ACC_MSGF
  • 319 ERROR_MR_INV_MSFG_FORMAT
  • 320 ERROR_MR_INV_IVCOUNT
  • 321 ERROR_MR_UN_PERFORM

Remarks

If IvCount is greater than 9, DosGetMessage returns an error that indicates IvCount is out of range. If the numeric value of x in the %x sequence for %1through%9 is less than or equal to IvCount, text insertion by substitution for %x, is performed for all occurrences of %x in the message. Otherwise text insertion is ignored and the %x sequence is returned in the message unchanged. Text insertion is performed for all text strings defined by IvCount and IvTable.

Variable data insertion is not dependent on blank character delimiters nor are blanks automatically inserted.

For warning and error messages, the message ID (seven alphanumeric characters consisting of three upper case characters as the component ID, concatenated with a four-digit message number) followed by a colon and a blank character are returned to the caller as part of the message text. (DosGetMessage determines the type of message based on the message classification generated in the output file of the MKMSGF utility.)

The following is an example of a sample error message returned with the message ID:

SYS0100: File not found

DosGetMessage retrieves messages previously prepared by the utility MKMSGF to create a message file, or MSGBIND to bind a message segment to an .EXE file. DosGetMessage tries to retrieve the message from RAM in the message segment bound to the .EXE program. If the message cannot be found, DosGetMessage retrieves the message from the message file on DASD (direct access storage device, such as a diskette or fixed-disk).

If the file name is not a fully-qualified name, DosGetMessage searches the following directories for default drive and path:

  • The system root directory
  • The current working directory
  • Directories listed in the DPATH statement (OS/2 mode only)
  • Directories listed in the APPEND statement (DOS mode only).

If a message cannot be retrieved because of a DASD error or file not found condition, a default message is placed in the user's buffer area. A message is placed in the buffer area based on the following error conditions:

  • The message number cannot be found in the message file.
  • The message file cannot be found.
  • The system detected a disk error trying to access the message file, or the message file format is incorrect.
  • IvCount is out of range.
  • A system error occurred trying to allocate storage.

When these conditions occur, the default message allows the application program to issue a message and prompt that enables recovery opportunity.

The residency of the message in RAM (EXE bound) or on DASD is transparent to the caller and handled by DosGetMessage. In either case the message is referenced by message number and file name.

In order for DosGetMessage to be properly resolved, an application must be linked with DOSCALLS.LIB.

Family API Considerations

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction applies to DosGetMessage when coding for the DOS mode:

If the message file name is not a fully qualified name, DosGetMessage searches the root directory of the default drive for the message file, instead of the root directory of the startup drive.

Bindings

C

#define INCL_DOSMISC

USHORT  rc = DosGetMessage(IvTable, IvCount, DataArea, DataLength,
                             MsgNumber, FileName, MsgLength);

PCHAR FAR *   IvTable;     /* Table of variables to insert */
USHORT        IvCount;     /* Number of variables */
PCHAR         DataArea;    /* Message buffer (returned) */
USHORT        DataLength;  /* Length of buffer */
USHORT        MsgNumber;   /* Number of the message */
PSZ           FileName;    /* Message file path name string */
PUSHORT       MsgLength;   /* Length of message (returned) */

USHORT        rc;          /* return code */

MASM

EXTRN  DosGetMessage:FAR
INCL_DOSMISC      EQU 1

PUSH@  OTHER   IvTable     ;Table of variables to insert
PUSH   WORD    IvCount     ;Number of variables
PUSH@  OTHER   DataArea    ;Message buffer (returned)
PUSH   WORD    DataLength  ;Length of buffer
PUSH   WORD    MsgNumber   ;Number of the message
PUSH@  ASCIIZ  FileName    ;Message file path name string
PUSH@  WORD    MsgLength   ;Length of message (returned)
CALL   DosGetMessage

Returns WORD