DosGetMessage retrieves a message from a system message file, and inserts variable text-string information into the message.
In the following code fragment, the message file is "D:\MESSAGE\AUTOMSG.MSG". The third message within the message file contains the string "%1 Error at Station %2". The application calls DosGetMessage to convert this message into the string "Automation Failure Error at Station 69B".
#define INCL_DOSMISC /* Miscellaneous values */
#include <os2.h>
#include <stdio.h>
UCHAR *ucIvTable[2]; /* Table of variables to insert */
ULONG ulIvCount; /* Number of variables */
UCHAR ucDataArea[80]; /* Message buffer (returned) */
ULONG ulDataLength; /* Length of buffer */
ULONG ulMsgNumber; /* Number of the message */
UCHAR ucFileName[40]; /* Message file path-name string */
ULONG ulMsgLength; /* Length of message (returned) */
UCHAR ucField1[20]; /* String to substitute into variable */
/* field %1 of the message */
UCHAR ucField2[20]; /* String to substitute into variable */
/* field %2 of the message */
APIRET ulrc; /* Return code */
strcpy(ucField1,
"Automation Failure"); /* Define the field with which to */
/* perform the first substitution */
strcpy(ucField2,
"69B"); /* Define the field with which to */
/* perform the second substitution */
ucIvTable[0] = ucField1; /* Set up the array of pointers to */
ucIvTable[1] = ucField2; /* substitute strings */
ulIvCount = 2; /* Two variable message fields in message */
ulDataLength = 80; /* Data buffer that will receive the */
/* complete message is 80 bytes in size */
ulMsgNumber = 3; /* Specify the third message in the */
/* message file */
strcpy(ucFileName,
"D:\\MESSAGE\\AUTOMSG.MSG");
/* Path name of the message file */
ulrc = DosGetMessage(ucIvTable,
ulIvCount,
ucDataArea,
ulDataLength,
ulMsgNumber,
ucFileName,
&ulMsgLength);
if (ulrc != 0) {
printf("DosGetMessage error: return code = %ld",
ulrc);
return;
}
On successful return, the DataArea buffer contains the complete message
(with the two variable fields appropriately updated), and the MsgLength
variable contains the length of the message that was placed into the
DataArea buffer.
If an error occurs (that is, if the return code does not equal 0), a message that is related to the error will be placed in the message buffer. See the DosGetMessage API reference in Control Program Programming Reference for a description of the default messages that can be placed into the user's buffer if an error occurs during the processing of these requests.