The keyword ICONRESOURCE

This section is written & Copyright by Christian Langanke (see EMail Addresses) Please send any comments or additions to Christian.

---------- * ----------

All comments on the keyword ICONRESOURCE apply as well to the keyword ICONNRESOURCE.

When loading icons from resource DLLs using the keyword ICONRESOURCE, you can specify the DLL in two different ways:

• module name only: ICONRESOURCE=60,PMWP;
  Such a DLL must be already loaded via (BEGIN/END)LIBPATH.

  This approach is mostly used with system resource DLLs coming with OS/2 WARP.

• full pathname with extension: ICONRESOURCE=123,D:\TEST\MYRES.DLL;
  Such a DLL must be already loaded into memory under WARP 3 and must not be loaded under WARP 4 (see comments below) in order to use it with the ICONRESOURCE keyword.

  This approach is recommended to be used where C/C++ programs or REXX scripts create WPS objects with WinCreateObject/SysCreateObject calls using icons from within application resource DLLs. For that such DLLs need not to reside in a directory being contained in the LIBPATH statement, which is convenient for DLLs only being used within one application.

See further notes on DLLS at the end of this page about loading DLLs.

Problems with using the keyword ICONRESOURCE under WARP 3

Under WARP 3 using the keyword ICONRESOURCE will only succeed when using DLLs being already loaded by the Workplace Shell (like PMWP.DLL) or another process. This applies both to DLLs being referenced with their module name only (such as PMWP) as well as to DLLs being referenced with full pathname and file extension.

To achive this, any module being specified to load an icon from must explicitely be loaded before, either by another process or a REXX script itself. Otherwise the specified icon resource will not be useable, which will result in creating objects not showing up with the desired icon. While it is easy to load a DLL from within a C/C++ program, this is rather complicated from within a REXX script.

The following methods allow to load a resource DLL from within REXX:

• use an external REXX extension DLL. This requires an additional DLL to be shipped with the REXX script, which I would recommend to avoid, if you do not need such external DLL in the same or another REXX script of the same application for other purposes anyway.

• load the DLL with the built-in method RxFuncAdd. This requires to have at least one REXX compliant C-function within the resource DLL, which must be registered and called by the REXX script to let the REXX runtime effectively load the resource DLL.

  Search http://hobbes.nmsu.edu for the ICONRESOURCE package (iconresource*.zip) of C.Langanke@TeamOS2.de, which contains the source and the compiled version of such a DLL plus a sample REXX script showing you the handling of the resource DLL (see also ICONRESOURCE)
  A REXX programmer can use the precompiled resource DLL of this package without recompiling the C source by just adding resources with the resource compiler coming with plain OS/2 WARP 3 and 4.

Problems with using the keyword ICONRESOURCE under WARP 4

In contrast to WARP 3, under WARP 4 a resource DLL being referenced by the ICONRESOURCE keyword MUST NOT be in memory, if a fully qualified path is being specified. The DLLs seems implicitely to be loaded by WARP 4 and be freed afterwards. Only a DLL specified without path and extension (such as PMWP), that has been loaded via (BEGIN/END)LIBPATH, may already be in memory to be used with the ICONRESOURCE keyword.

General notes about (resource) DLLs:

• A DLL loaded via module name only is loaded into a public DLL namespace. The system can load only one DLL with the same name into this namespace. When loading a second DLL from within a different directory (e.g. with the "." entry in the LIBPATH or with BEGIN/ENDLIBPATH), no error is returned, but still only the first DLL is being used !

• A DLL loaded via full pathame and extension is loaded into a namespace being private per process. The system can load different DLLs with the same name, but from different directories.

• The filename extension for DLLs being loaded via the full pathname does not necessarily need to be .DLL, any other extension will do fine. This does not apply to DLLs being loaded via (BEGIN/END)LIBPATH, herefore the extension MUST be .DLL. Thus a DLLs extension, which does not need to be loaded via LIBPATH can always safely be changed to any extension from one to three characters.

• Modifying the name part of a DLL is not that harmless, as under some circumstances the name of the DLL must be identical to the module name being stored in the EXE header of the DLL:

  • If a DLL is only be used to load resources or functions of a DLL are being linked to dynamically, the name of the DLL can be changed without a problem (at least according to my testings, please send mail to C.Langanke@TeamOS2.de if you found out something different). Note that the name needs to be 8.3 FAT filesystem compliant since WARP 3 !.

  • If a DLL contains functions, that other programs link statically to, the name of the DLL MAY NOT be simply renamed. You have to use appropriate tools (like DLLRNAME.EXE from IBM compilers), which path the module name to the new name for you. Such tools usually restrict you to choose an name of either the same or shorter length, so that the EXE header needs not to be completely rewritten.

  ---

  [Back: The keyword ICONPOS]
  [Next: The keyword ICONVIEWPOS]