This call retrieves a message from a message file and inserts variable information into the body of the message.
DosGetMessage
IvTable (PCHAR FAR *) - input
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:
o
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:
o
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.