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: 

   1. 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.   

   2. 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.