Functions and Directives Functions and Directives

Function LoadResource() Foundation

Loads a resource from a linked resource file or from a DLL.

Syntax
LoadResource( <nResId>|<cResId>, [<nDll|cDll>], [<nRestype>|<cResType>], <nLanguageId|cLanguageId> ) --> xResource
Parameters
<nResId|cResId>
<nResId> is a numeric resource ID. The same number must be used to link a resource to an EXE or DLL file using ARC.EXE. <cResId> is a named resource ID of the type character. The same name number must be used in the ARC file. Note: <cResId> is case-sensitive. Because the lookup of a named resource depends on the operating system, we recommend to use upper case letters both in the ARC file and the <cResId> parameter.
<cDll|nDll>
This optional parameter must be used when the requested resource is linked into a DLL file rather than into the EXE file. If this parameter is omitted, the resource is searched for in the main executable file. If a character string is passed for <cDll>, it must contain the file name of the DLL. If passed as a numeric, the value of <nDll> must be a valid DLL handle as it is returned by the DllLoad() function, or a #define constant from DLL.CH listed in the next table:
Predefined constants for <nDll>
Constant Description
XPP_MOD_EXE *) The current EXE file
XPP_MOD_NLS The Xbase++ nation DLL XppNat.dll
XPP_MOD_RT1 The Xbase++ runtime DLL XppRt1.dll
XPP_MOD_UI1 The Xbase++ runtime DLL XppUi1.dll
XPP_MOD_UI2 The Xbase++ runtime DLL XppUi2.dll
  1. default
<nResType|cResType>
<nResType> is an optional numeric value to tell what resource type should be loaded. Its either RES_STRING, RES_RAWSTRING, RES_VERSION or RES_VERSIONFIXED. The default value is RES_STRING. If the resource is of the type USERDEF, the type must be passed as character (<cResType>). Note that <cResType> is case-sensitive. Because the lookup of a named resource type depends on the operating system, we recommend to use upper case letters both in the ARC file and the <cResType> parameter.
<nLanguageId|cLanguageId>
The optional parameter <nLanguageId|cLanguageId> is used to determine the language of the resource. The language identifier is either a composite numeric value built of the primary and the sublanguage identifiers or a language code string according to ISO 639-1. The use of the string identifiers is recommended, because the numeric values are operating system dependent.
Return

The function returns the content of the requested resource. If the resource could not be found, NIL will be returned. The error condition can be determined using DosError().

Return values
<nResType> data type Description
RES_STRING C String resource as CHARACTER converted to the current CHARSET coding
RES_RAWSTRING C String resource as CHARACTER not converted
RES_VERSION A Version information in a two-dimensional ARRAY
RES_VERSIONFIXED A fixed version information in a one-dimensional ARRAY
<userdef> C data as defined in the resource file

Description

LoadResource() loads resource data created using a resource compiler like ARC.EXE and that is linked to the main executable file (EXE) or a dynamic library (DLL). If resources of a DLL are to be loaded, the DLL must already be accessible, either by linking the DLL to the main executable file or by loading the DLL using the DllLoad() function.

The main reason for storing data in resource files rather than hardcoding them in application's code is that the application can be configured later without the need to recompile and link. An example for this is multiple-language support. Another reason is to be able to request data from the application without running it, or simply to be able to deliver all required data within one single file.

If a version resource is requested the resource identifier is assumed to be numeric 1 because there is only one VERSION resource allowed per file. If <nResId> equals to RES_VERSION the return value is a two-dimensional array. The sub-arrays have the following string elements:

Version Information array (RES_VERSION)
SubArray element Meaning
RES_VERSION_KEY version key name as CHARACTER
RES_VERSION_VALUE version value as CHARACTER

If RES_VERSIONFIXED is requested, the one-dimensional array consists of numeric elements. The sole purpose of having the version numbers as numerical values is to be able to safely compare the values for a version check.

Fixed Version Information returned array (RES_VERSIONFIXED)
Array element Meaning
RES_PRODVER_LS lower 32 bit of the product version number
RES_PRODVER_MS higher 32 bit of the product version number
RES_FILEVER_LS lower 32 bit of the file version number
RES_FILEVER_MS higher 32 bit of the file version number
RES_FILETIME_LS lower 32 bit of the file time
RES_FILETIME_MS higher 32 bit of the file time

For an explanation of the VERSION resource, see Alaska Resource Compiler.

Examples
Loading character data from a resource DLL 
// In the example, the resource ID 1000 was linked to 
// a DLL called "msgs.dll". The content will be displayed. 

PROCEDURE Main 
   LOCAL cValue 

   // retrieve resource, the DLL must be linked to the 
   // EXE file or be loaded using DllLoad() before 
   cValue := LoadResource(1000,"msgs.dll") 

   // display the value 
   ? cValue 
RETURN
About-Box using version resources 
// Use version resources to display information 
// about the product/file 
#include "dll.ch" 
PROCEDURE Main 
   LOCAL aVersion 
   LOCAL cMsg 

   // retrieve resource, the DLL must be linked to the 
   // EXE file or be loaded using DllLoad() before 
   aVersion := LoadResource(1, XPP_MOD_EXE, RES_VERSION) 
   cMsg := "" 
   AEval(aVersion, {|e| cMsg += e[RES_VERSION_KEY] +": "+; 
                                e[RES_VERSION_VALUE] +";"}) 
   cMsg[-1]:=" " 
   Alert(cMsg,,"B+/W,W+/G") 
RETURN 

// use this ARC file to define the version resource 
// compile with arc and link the .res-file to the .exe 
#ifdef __ARC__ 
  VERSION 
      "CompanyName"      = "Stock Analysts Inc." 
      "ProductName"      = "SA-Quick " 
      "ProductVersion"   = " 5.0" 
      "FileVersion"      = " 5.001.893" 
      "FileDescription"  = "Analyze stock markets" 
      "InternalName"     = "SAQ5" 
      "LegalCopyright"   = "Copyright   Stock Analysts Inc. 2001" 
      "OriginalFilename" = "SAQ.DLL" 
#endif
Loading localized user-defined resources 
// In the example, a user-defined resource will be loaded. 
PROCEDURE Main 
   LOCAL cValue 
   LOCAL cLangId 

   // this hypothetic function would retrieve the language 
   // of the client, for example the web browser 
   cLangId := ClientLangId() 
   // now retrieve some fixed data depending on the language 
   cValue := LoadResource("TITLE", XPP_MOD_EXE,"HTML", cLangId) 

   // use the value for further processing 
   ? cValue 
RETURN 

// use this ARC file to define the version resource 
// compile with arc and link the .res-file to the .exe 
#ifdef __ARC__ 
   LANGUAGE="en" 
   USERDEF HTML 
        TITLE = "This is the page title" 
   LANGUAGE="de" 
   USERDEF HTML 
        TITLE = "Das ist der Seitentitel." 
   LANGUAGE="neutral" 
   USERDEF HTML 
        TITLE = "This is the page title" 
#endif
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.