DosInsertMessage inserts variable text-string information into a message that resides within program memory.

In the following code fragment, the message resides in a program string variable named Message. The message is the string "%1 Error at Station %2". The application calls DosInsertMessage 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    ucMsgInput[40] = "%1 Error at Station %2";     /* The input message */
    ULONG    ulMsgInLength;              /* Length of input message              */
    UCHAR    ucDataArea[80];             /* Message buffer (returned)            */
    ULONG    ulDataLength;               /* Length of updated message buffer     */
    ULONG    ulMsgLength;                /* Length of updated 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                         */

    ulMsgInLength = strlen(ucMsgInput);     /* Length of input message         */

    ulDataLength = 80;                      /* Data buffer that will receive   */
                                            /* the complete message is 80      */
                                            /* bytes in size                   */

    ulrc = DosInsertMessage(ucIvTable,
                            ulIvCount,
                            ucMsgInput,
                            ulMsgInLength,
                            ucDataArea,
                            ulDataLength,
                            &ulMsgLength);

    if (ulrc != 0) {
        printf("DosInsertMessage 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.