WinLoadMessage

This function loads a message from a resource, copies the message to the specified buffer, and appends a terminating null character.

Syntax

WinLoadMessage(hab, hmodMod, ulId, lcchMax, pBuffer);

Parameters

hab (HAB) - input

Anchor-block handle.

hmodMod (HMODULE) - input

Module handle.

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.

ulId (ULONG) - input

Message identifier.

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

lcchMax (LONG) - input

Specifies the size of buffer.

The maximum length of a string is 256 character.

pBuffer (PSZ) - input

Points to the buffer that receives the message.

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 (lcchMax-1).

Remarks

Message resources contain up to 16 messages each. The resource ID is calculated from the id parameter value passed to this function as follows:

resource ID = (id / 16) + 1

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

Example Code

This example loads an error message from ERR.DLL using the resource handle from DosLoadModule and uses the message in a message box.

#define INCL_WINWINDOWMGR       /* Window Manager Functions     */
#define INCL_DOSMODULEMGR       /* Module Manager Functions     */
#define INCL_WINDIALOGS         /* Window Dialog Mgr Functions  */
#include <os2.h>
#define ERRMSG_ID 1

LONG    lLength;        /* length of string                     */
HAB     hab;            /* anchor-block handle                  */
HMODULE hmodDLL;        /* Handle of resource module            */
LONG    lBufferMax = 100;/* Size of buffer                      */
char    pszErrMsg[100]; /* error message                        */
CHAR    LoadError[100]; /* object name buffer for DosLoad       */
ULONG   rc;             /* return code                          */
HWND    hwnd;           /* window handle                        */

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

/* load message from resource */
if (rc == 0)
   {
   /* load error message string */
   lLength = WinLoadMessage(hab, hmodDLL, ERRMSG_ID, lBufferMax,
                            pszErrMsg);

   /* display error message box */
   WinMessageBox(HWND_DESKTOP,
       hwnd,                      /* client-window handle   */
       pszErrMsg,                 /* message                */
       "Error message",           /* title of the message   */
       0,                         /* message box id         */
       MB_NOICON | MB_OK);        /* icon and button flags  */
   }

Definition

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

HAB        hab;      /*  Anchor-block handle. */
HMODULE    hmodMod;  /*  Module handle. */
ULONG      ulId;     /*  Message identifier. */
LONG       lcchMax;  /*  Specifies the size of buffer. */
PSZ        pBuffer;  /*  Points to the buffer that receives the message. */
LONG       lLength;  /*  The length of the string returned. */

lLength = WinLoadMessage(hab, hmodMod, ulId,
            lcchMax, pBuffer);

Related Functions

• WinLoadString