C$RESOURCE

Use C$RESOURCE to load a resource file and get a resource handle or to destroy the resource handle and free any memory associated with it. The AcuBench Screen Designer saves changes made to an ActiveX control in a "state" resource file. The runtime uses the information in this resource file when displaying the ActiveX control.

After an ActiveX control is displayed you may destroy the resource handle used to initialize it. The ActiveX control only references this resource handle during the first DISPLAY or MODIFY which sets the initial-state property (usually the first display). In general, you should destroy resource handles to free memory after all ActiveX controls that use them have been displayed.

Usage

CALL "C$RESOURCE" 
    USING OP-CODE, parameters
    GIVING RESOURCE-HANDLE

Parameters

OP-CODE Numeric parameter Op-code indicates the desired operation. The file "activex.def" contains level 78 symbolic names for these operations.
Parameters Vary depending on the op-code chosen. These are described in the Comments section below.
RESOURCE-HANDLE PIC 9(9) RESOURCE-HANDLE holds the return value of C$RESOURCE. Values less than or equal to zero indicate errors. This is only used by the CRESOURCE-LOAD operation.

Comments

There are two operations available in C$RESOURCE:

  1. load a resource file and return a resource handle
  2. destroy a resource handle and free its associated memory

To use C$RESOURCE, you pass an op-code as the first parameter, followed by one additional parameter. The op-code determines which operation is performed and the meaning of the additional parameter.

Currently, there are two operations:

CRESOURCE-LOAD

This operation loads a resource file from disk and returns a resource handle. It takes one additional parameter:

NAME     This is an alphanumeric literal or data item that is the file name of the resource file. This must be a resource file generated by AcuBench. The file usually ends with .res.
Note: When you are running in a thin client environment, and a file name beginning with "@[DISPLAY]" is passed to this routine, it will attempt to access the file in the display host's file system. It does not download the file from the server.

CRESOURCE-DESTROY 

This operation destroys a resource handle and releases its memory. It takes one additional parameter:

RES-HANDLE    This is a resource handle returned by CRESOURCE-LOAD.
Note: The behavior of this library routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the documentation on FILENAME_SPACES in Appendix H, Configuration Variables for information about the terminating character for path names.

Example

CALL "C$RESOURCE" USING CRESOURCE-LOAD, "PROGRAM1.RES" 
   GIVING RES-HANDLE.
IF RES-HANDLE > 0 THEN
   DISPLAY MSCHART LINE 10 COLUMN 10 LINE 5 SIZE 40 
      INITIAL-STATE = (RES-HANDLE, "MSCHART-1-INITIAL-STATE")
      HANDLE IN MSCHART-1
   CALL "C$RESOURCE" USING CRESOURCE-DESTROY, RES-HANDLE
END-IF