WinSubstituteStrings

This function performs a substitution process on a text string, replacing specific marker characters with text supplied by the application.

Syntax

WinSubstituteStrings(hwnd, pszSrc, lDestMax, pszDest)

Parameters

hwnd (HWND) - input

Handle of window that processes the call.

pszSrc (PSZ) - input

Source string.

This is the text string that is to have substitution performed.

lDestMax (LONG) - input

Maximum number of characters returnable.

This is the maximum number of characters that can be returned in pszDest. It must be greater than 0.

pszDest (PSZ) - output

Resultant string.

This is the text string produced by the substitution process.

The string is truncated if it would otherwise contain more than lDestMax characters. When truncation occurs, the last character of the truncated string is always the null-termination character.

Returns

lDestRet (LONG) - returns

Actual number of characters returned.

This is the actual number returned in pszDest, excluding the null-termination character. The maximum value is (lDestMax-1). It is zero if an error occurred.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001)

An invalid window handle was specified.

Remarks

When a string of the form "%n" (where n is in the range 0 through 9) occurs in the source string, a WM_SUBSTITUTESTRING message is sent to the specified window. This message returns a text string to use as a substitution for "%n" in the destination string, which is otherwise an exact copy of the source string.

If "%%" occurs in the source, "%" is copied to the destination, but no other substitution occurs. If "%x" occurs in the source, where x is not a digit or "%", the source is copied unchanged to the destination. The source and destination strings must not overlap in memory.

This function is particularly useful for displaying variable information in dialogs, menus, and other user-interface calls. Variable information can include such things as file names, which cannot be statically declared within resource files.

This function is called by the system while creating child windows in a dialog box. It allows the child windows to perform textual substitutions in their window text.

Example Code

This example shows how the substitution process works when the WinSubstituteStrings call is made.

#define INCL_WINDIALOGS
#include <OS2.H>

static MRESULT ClientWindowProc(HWND hwnd,ULONG msg,MPARAM mp1,MPARAM mp2);
test()
{
  HWND hwnd;
  char source[] = "This is the source string: %1";
  char result[22];
  MPARAM mp1;
  ULONG  msg;

  /* This function performs a substitution process on a text string, */
  /* replacing specific marker characters with text supplied         */
  /* by the application.                                             */
  WinSubstituteStrings(hwnd,
                       source,
                       sizeof(result),
                       result);

  /* WM_SUBSTITUTESTRING message is sent to the window  */
  /* defined by hwnd.                                         */
}
static MRESULT ClientWindowProc( HWND hwnd, ULONG  msg, MPARAM mp1, MPARAM mp2 )
{
  switch(msg)
  {
    case WM_SUBSTITUTESTRING:
    switch( (ULONG)mp1)
    {
      case 1:
      return(MRFROMP("A"));
      break;
    }
    break;
  }
}

Definition

#define INCL_WINDIALOGS /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HWND    hwnd;      /*  Handle of window that processes the call. */
PSZ     pszSrc;    /*  Source string. */
LONG    lDestMax;  /*  Maximum number of characters returnable. */
PSZ     pszDest;   /*  Resultant string. */
LONG    lDestRet;  /*  Actual number of characters returned. */

lDestRet = WinSubstituteStrings(hwnd, pszSrc, lDestMax, pszDest);

Related Functions

• WinCompareStrings
• WinLoadString
• WinNextChar
• WinPrevChar
• WinUpper
• WinUpperChar

Related Messages

• WM_SUBSTITUTESTRING