DosInsertMessage

Description

Inserts variable text-string information into a message.

Syntax

#define INCL_DOSMISC
#include <os2.h>

PCHAR    *pTable;  /* A pointer table. */
ULONG     cTable;  /* The number of variable insertion text strings. */
PSZ       pszMsg;  /* The address of the input message. */
ULONG     cbMsg;   /* The length, in bytes, of the input message. */
PCHAR     pBuf;    /* The address of the caller's buffer area where the system returns
                      the requested message. */
ULONG     cbBuf;   /* The length, in bytes, of the caller's buffer area. */
PULONG    pcbMsg;  /* The length, in bytes, of the updated message returned. */
APIRET    ulrc;    /* Return Code. */

ulrc = DosInsertMessage(pTable, cTable, pszMsg,
         cbMsg, pBuf, cbBuf, pcbMsg);

Parameters

pTable (PCHAR *) - input

A pointer table.

Each pointer filets to an ASCIIZ string or a double-byte character-set (DBCS) string ending in nulls. A maximum of nine strings can be present.

cTable (ULONG) - input

The number of variable insertion text strings.

Possible values range from 0 to 9. If cTable is 0, pTable is ignored.

pszMsg (PSZ) - input

The address of the input message.

cbMsg (ULONG) - input

The length, in bytes, of the input message.

pBuf (PCHAR) - output

The address of the caller's buffer area where the system returns the requested message.

If the message is too long to fit in the caller's buffer, then as much of the message text as possible is returned, with the appropriate error return code.

cbBuf (ULONG) - input

The length, in bytes, of the caller's buffer area.

pcbMsg (PULONG) - output

The length, in bytes, of the updated message returned.

Return Code

ulrc (APIRET) - returns

DosInsertMessage returns one of the following values:

• 0 NO_ERROR
• 87 ERROR_INVALID_PARAMETER
• 316 ERROR_MR_MSG_TOO_LONG
• 320 ERROR_MR_INV_IVCOUNT

Remarks

DosInsertMessage inserts variable text-string information into a message.

DosInsertMessage differs from DosGetMessage in that it does not retrieve a message. It is particularly useful when messages are loaded early, before actual insertion text strings are known.

If cTable is greater than 9, DosInsertMessage returns an error indicating that cTable is out of range. A default message also is placed into the caller's buffer. Refer to DosGetMessage for details about default messages.

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

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

Example Code

This example demonstrate the insertion of the variable text into a message.

#define INCL_DOSMISC    /* Miscellaneous values */
#define INCL_DOSERRORS  /* DOS Error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>

int main(VOID) {
UCHAR   *IvTable[3] = {0};                   /* Table of variables to insert */
UCHAR   MsgInput[30] = "Processing for %1: %2 has %3. ";
UCHAR   DataArea[80]= "";                    /* Output message area */
ULONG   MsgLength   = 0;                     /* Length of returned message */
APIRET  rc          = 0;                     /* Return code */
int     LoopCtr     = 0;                     /* for loop counter */

IvTable[0] = "function";
IvTable[1] = "DosInsertMessage";
IvTable[2] = "started";

               /* Insert strings in proper variable fields */

rc = DosInsertMessage(IvTable,             /* Message insert pointer array */
                      3,                   /* Number of inserts */
                      MsgInput,            /* Input message */
                      strlen(MsgInput),    /* Length of input message */
                      DataArea,            /* Output area for message */
                      sizeof(DataArea),    /* Size of output area */
                      &MsgLength);        /* Length of output message created */
if (rc != NO_ERROR) {
   printf("DosInsertMessage error: return code = %u\n", rc);
   return 1;
}

printf("%s\n", DataArea);   /* Print the resulting message */

return NO_ERROR;
}

Related Functions

• DosGetMessage
• DosPutMessage
• DosQueryMessageCP