WinLoadString

This function loads a string from a resource.

Syntax

WinLoadString(hab, Resource, idString, lBufferMax, pszBuffer)

Parameters

hab (HAB) - input

Anchor-block handle.

Resource (HMODULE) - input

Resource identity containing the string.

NULLHANDLE

Use the application's own resources file.

Other

Module handle returned by the DosLoadModule or DosQueryModuleHandle call referencing a dynamic-link library containing the resource.

idString (ULONG) - input

String identifier.

It must be greater or equal to 0 and less or equal to 0xFFFF.

lBufferMax (LONG) - input

Size of buffer.

The maximum length of a string is 256 characters.

pszBuffer (PSZ) - output

Buffer that is to receive the string.

Returns

lLength (LONG) - returns

The length of the string returned.

This excludes the terminating null, and has the following values

Error

Other

A maximum value of (lBufferMax-1).

Errors

Possible returns from WinGetLastError

PMERR_RESOURCE_NOT_FOUND (0x100A)

The specified resource identity could not be found.

Remarks

This function loads a string resource identified by the idString and the Resource parameters into the pszBuffer parameter, and appends a terminating null character.

RT_STRING resources (string resources) contain up to 16 strings each The resource ID is calculated from the idString passed to this function as follows:

resource ID = (idString / 16) + 1

To save storage on disk and in memory, applications should number their string resources sequentially, starting at some multiple of 16.

Example Code

This example loads a string from RES.DLL using the resource handle from DosLoadModule.

#define INCL_WINWINDOWMGR       /* Window Manager Functions     */
#define INCL_DOSMODULEMGR       /* Module Manager Functions     */
#include <os2.h>
#define STRING_ID 1

LONG    lLength;        /* length of string                     */
HAB     hab;            /* anchor-block handle                  */
HMODULE hmodDLL;        /* Handle of resource module            */
ULONG   idString = STRING_ID; /* String identifier              */
LONG    lBufferMax = 10;/* Size of buffer                       */
char    pszString1[10]; /* first string                         */
CHAR    LoadError[100]; /* object name buffer for DosLoad       */
ULONG   rc;             /* return code                          */

/* obtain resource handle */
rc = DosLoadModule(LoadError, sizeof(LoadError), "RES.DLL",
                   &hmodDLL);

/* load string from resource */
if (rc == 0)
   lLength = WinLoadString(hab, hmodDLL, idString, lBufferMax,
                            pszString1);

Definition

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

HAB        hab;         /*  Anchor-block handle. */
HMODULE    Resource;    /*  Resource identity containing the string. */
ULONG      idString;    /*  String identifier. */
LONG       lBufferMax;  /*  Size of buffer. */
PSZ        pszBuffer;   /*  Buffer that is to receive the string. */
LONG       lLength;     /*  The length of the string returned. */

lLength = WinLoadString(hab, Resource, idString, lBufferMax, pszBuffer);

Related Functions

• WinCompareStrings
• WinNextChar
• WinPrevChar
• WinSubstituteStrings
• WinUpper
• WinUpperChar