en:docs:fapi:dosinsmessage

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
en:docs:fapi:dosinsmessage [2018/08/31 09:11] – created prokusheven:docs:fapi:dosinsmessage [2021/12/05 10:01] (current) – prokushev
Line 1: Line 1:
 +{{page>en:templates:fapiint}}
 +
 +====== 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. 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== +===== Syntax ===== 
- DosInsMessage (IvTable, IvCount, MsgInput, MsgInLength, DataArea, DataLength,MsgLength)+ 
 +<code c> 
 +DosInsMessage (IvTable, IvCount, MsgInput, MsgInLength, DataArea, DataLength,MsgLength) 
 +</code> 
 + 
 +===== 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 =====
  
-==Parameters== +rc ([[USHORT]]) - return
-;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: Return code descriptions are:
-* 0    NO_ERROR 
-* 316  ERROR_MR_MSG_TOO_LONG 
-* 320  ERROR_MR_INV_IVCOUNT 
  
-==Remarks== +  * 0    NO_ERROR 
-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+  * 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. %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.  Variable data insertion does not depend on a blank character delimiter nor are blanks automatically inserted. 
  
-==Example Code== +===== Example Code ===== 
-===C Binding=== + 
-<PRE>+==== C Binding ==== 
 + 
 +<code c>
 #define INCL_DOSMISC #define INCL_DOSMISC
  
Line 44: Line 57:
  
 USHORT           rc;            /* return code */ USHORT           rc;            /* return code */
-</PRE>+</code>
  
-===MASM Binding=== +==== MASM Binding ==== 
-<PRE>+ 
 +<code asm>
 EXTRN  DosInsMessage:FAR EXTRN  DosInsMessage:FAR
 INCL_DOSMISC      EQU 1 INCL_DOSMISC      EQU 1
Line 59: Line 73:
 PUSH@  WORD    MsgLength     ;Length of updated message (returned) PUSH@  WORD    MsgLength     ;Length of updated message (returned)
 CALL   DosInsMessage CALL   DosInsMessage
 +
 +</code>
  
 Returns WORD Returns WORD
-</PRE> 
  
-====== Note ======+===== Note =====
  
 Text based on [[http://www.edm2.com/index.php/DosInsMessage]] Text based on [[http://www.edm2.com/index.php/DosInsMessage]]