Function LoadResource() Foundation
Loads a resource from a linked resource file or from a DLL.
LoadResource( <nResId>|<cResId>, [<nDll|cDll>], [<nRestype>|<cResType>], <nLanguageId|cLanguageId> ) --> xResource
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 |
|
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().
<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 |
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:
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.
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.
// 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
// 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
// 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
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.