This is part of Family API which allow to create dual-os version of program runs under OS/2 and DOS

Note: This is legacy API call. It is recommended to use 32-bit equivalent

DosInsMessage

This call inserts variable text string information into the body of a message. This is useful when messages are loaded before insertion text strings are known.

Syntax

DosInsMessage (IvTable, IvCount, MsgInput, MsgInLength, DataArea, DataLength,MsgLength)

Parameters

IvTable (PCHAR FAR *) - input : List of double-word pointers. Each pointer points to an ASCIIZ or null terminated DBCS string (variable insertion text). 0 to 9 strings can be present.

IvCount (USHORT) - input : 0-9 is the count of variable insertion text strings. If IvCount is 0, IvTable is ignored.

MsgInput (PSZ) - input : Address of the input message.

MsgInLength (USHORT) - input : Length, in bytes, of the input message.

DataArea (PCHAR) - output : Address of the user storage that returns the updated message. If the message is too long to fit in the caller's buffer, as much of the message text as possible is returned with the appropriate return code.

DataLength (USHORT) - input : Length, in bytes, of the user's storage area.

MsgLength (PUSHORT) - output : Address of the length, in bytes, of the updated message.

Return Code

rc (USHORT) - return

Return code descriptions are:

0 NO_ERROR

316 ERROR_MR_MSG_TOO_LONG

320 ERROR_MR_INV_IVCOUNT

Remarks

DosInsMessage returns an error indicating that IvCount is out of range when IvCount is greater than 9. A default message is also placed in the caller's buffer. Refer to DosGetMessage for details on the default messages. If the numeric value of x in the %x sequence for %1through%9 is less than or equal to IvCount, then text insertion, by substitution for %x, is performed for all occurrences of %x in the body of the message. Otherwise text insertion is ignored and the %x sequence is returned unchanged in the message. Text insertion is performed for all text strings defined by IvCount and IvTable.

Variable data insertion does not depend on a blank character delimiter nor are blanks automatically inserted.

Example Code

C Binding

#define INCL_DOSMISC USHORT rc = DosInsMessage(IvTable, IvCount, MsgInput, MsgInLength, DataArea, DataLength, MsgLength); PCHAR FAR * IvTable; /* Table of variables to insert */ USHORT IvCount; /* Number of variables */ PSZ MsgInput; /* Address of input message */ USHORT MsgInLength; /* Length of input message */ PCHAR DataArea; /* Updated message (returned) */ USHORT DataLength; /* Length of updated message buffer */ PUSHORT MsgLength; /* Length of updated message (returned) */ USHORT rc; /* return code */

MASM Binding

EXTRN DosInsMessage:FAR INCL_DOSMISC EQU 1 PUSH@ OTHER IvTable ;Table of variables to insert PUSH WORD IvCount ;Number of variables PUSH@ ASCIIZ MsgInput ;Input message string PUSH WORD MsgInLength ;Length of input message PUSH@ OTHER DataArea ;Updated message (returned) PUSH WORD DataLength ;Length of updated message buffer PUSH@ WORD MsgLength ;Length of updated message (returned) CALL DosInsMessage

Returns WORD

Note

Text based on http://www.edm2.com/index.php/DosInsMessage

Family API
DOS	Process Manager	DosBeep DosExit DosSleep DosExecPgm
File Manager	DosChDir DosChgFilePtr DosClose DosDelete DosDupHandle DosMkDir DosMove DosQCurDir DosQCurDisk DosSetFileMode DosOpen DosQFileInfo DosRead DosQFileMode DosQFSInfo DosQVerify DosRmDir DosSelectDisk DosFindClose DosFindFirst DosFindNext DosSetFileInfo DosSetVerify DosWrite DosFileLocks DosSetFHandState DosNewSize DosBufReset DosQFHandState DosSetFSinfo DosShutdown
Memory Manager	DosFreeSeg DosSubAlloc DosSubFree DosSubSet DosAllocHuge DosAllocSeg DosReallocHuge DosReallocSeg DosGetHugeShift DosCreateCSAlias
NLS	DosCaseMap DosGetCtryInfo DosGetDBCSEv DosSetCtryCode DosGetCollate DosGetMessage DosInsMessage DosPutMessage
Date and Time	DosSetDateTime DosGetDateTime
Devices	DosDevConfig DosDevIOCtl DosDevIOCtl2
Signals	DosHoldSignal DosSetSigHandler
Misc	BadDynLink DosGetEnv DosGetMachineMode DosGetVersion DosError DosErrClass DosSetVec
KBD	KbdCharIn KbdFlushBuffer KbdGetStatus KbdSetStatus KbdStringIn KbdPeek
VIO	VioGetBuf VioGetConfig VioGetCurPos VioGetCurType VioGetPhysBuf VioReadCellStr VioReadCharStr VioScrollUp VioScrollDn VioScrollLf VioScrollRt VioScrUnLock VioSetCurPos VioSetCurType VioSetMode VioGetMode VioShowBuf VioWrtCellStr VioWrtCharStr VioWrtCharStrAtt VioWrtNAttr VioWrtNCell VioWrtNChar VioWrtTTY VioScrLock VioPopUp
Tools	BIND
Modules	DOSCALLS.DLL VIOCALLS.DLL KBDCALLS.DLL MSG.DLL
Libraries	API.LIB OS2386.LIB FAPI.LIB DOSCALLS.LIB SUBCALLS.LIB