DosGetMessage retrieves a message from the specified system message file, and inserts variable text-string information into the message.

If cTable is greater than 9, DosGetMessage returns an error indicating that cTable is out of range.

If the numeric value of x in the %x sequence for %1 to %9 is less than or equal to cTable, then text insertion, through 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 cTable and pTable.

Variable data insertion does not depend on blank character delimiters, nor are blanks automatically inserted.

For warning and error messages, the 7-character message ID (3-character component ID concatenated with a 4-digit message number) followed by a colon and a blank character is returned as part of the message text. DosGetMessage determines the type of message based on the message classification generated in the output file of MKMSGF.

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

SYS0002: The system cannot find the file specified

DosGetMessage retrieves messages previously prepared by MKMSGF to create a message file, or by MSGBIND to bind a message segment to an .EXE file. First, DosGetMessage tries to retrieve the message from memory 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 fully qualified, DosGetMessage searches the following directories for the default drive and path:

• The system root directory
  
• The current working directory
  
• Directories listed in the DPATH (protect-mode) statement
  
• Directories listed in the APPEND (DOS session) statement.

If a message cannot be retrieved because of a DASD error or a file-not-found condition, the system places an error message into the user's buffer area.

The following error conditions cause the system to place an error message into the user's buffer area:

• Unable to format the system message

  An error message is returned as a result of an invalid parameter (for example, invalid message number or invalid cTable).

• Unable to read the system message file

  An error message is returned when the system message file cannot be read (for example, because of a DASD error or an invalid message-file format).

• Unable to find the system message file

  An error message is returned when the system message file cannot be found.

The presence of the message in memory (EXE bound) or on DASD is not apparent to the caller, and is handled by DosGetMessage. In both cases, you refer to the message by message number and file name.

For DosGetMessage to be called from an input/output privilege level (IOPL) code segment, the following statement must be in the program's definition (.DEF) file:

SEGMENT '_MSGSEG' CLASS 'MSGSEGCODE' IOPL CONFORMING

In OS/2 Version 2.00, the message segment or object is packed with other application code. If the size of the code segment or object and the bound messages exceeds 64KB, then the message segment or object may be isolated from the application program code by placing the following statement into the program's definition (.DEF) file:

SEGMENT  '_MSGSEG' CLASS 'CODE' LOADONCALL    (16-bit application)


SEGMENT  '_MSGSEG32' CLASS 'CODE' LOADONCALL  (32-bit application)