Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Changes►                                             ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSMISC
 
USHORT DosInsMessage(ppchVTable, usVCount, pszMsg, cbMsg, pchBuf, cbBuf,
    pcbMsg)
PCHAR FAR * ppchVTable;    /* pointer to table of character pointers    */
USHORT usVCount;           /* number of pointers in table               */
PSZ pszMsg;                /* pointer to input message                  */
USHORT cbMsg;              /* number of bytes in input message          */
PCHAR pchBuf;              /* pointer to buffer for updated message     */
USHORT cbBuf;              /* number of bytes in buffer                 */
PUSHORT pcbMsg;            /* pointer to variable for length of message */
 
The DosInsMessage function copies a specified message to a buffer. Unlike
the DosGetMessage function, DosInsMessage does not retrieve a message.
DosInsMessage is often used when messages are loaded before the
insertion-text strings are known.
 
The DosInsMessage function is a family API function.
 
Parameter   Description
────────────────────────────────────────────────────────────────────────────
 
ppchVTable  Points to a table of pointers to null-terminated strings that
            can be inserted into the message. Up to nine strings can be
            given.
 
usVCount    Specifies the number of strings in the table. This parameter can
            be any value from 0 through 9. If this parameter is zero, the
            ppchVTable parameter is ignored. If this parameter is greater
            than 9, the function returns an error value indicating that the
            usVCount parameter is out of range.
 
pszMsg      Points to a null-terminated string that specifies the message to
            process.
 
cbMsg       Specifies the length (in bytes) of the message.
 
pchBuf      Points to the buffer that receives the message.
 
cbBuf       Specifies the length (in bytes) of the buffer that receives the
            message.
 
pcbMsg      Points to the variable that receives the number of bytes copied
            to the buffer.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_MR_INV_IVCOUNT
     ERROR_MR_MSG_TOO_LONG
 
Comments
 
As it copies a message, the DosInsMessage function replaces any symbol in
the form %x (where x is a digit from 1 through 9) with one of the strings
pointed to in the table pointed to by the ppchVTable parameter. For example,
the function replaces all symbols of the form %1 with the first string
pointed to in the table. If there is no corresponding string in the table,
DosInsMessage copies the %x sequence to the buffer. If the message is too
long to fit in the buffer, the DosGetMessage function truncates the message
and returns an error code.
 
Restrictions
 
In real mode, the following restriction applies to the DosInsMessage
function:
 
♦  There is no method of identifying the boot drive. The system assumes that
   the message file is in the root directory of the current drive.
 
See Also
 
DosGetMessage, DosPutMessage
 
                                      ♦