Using Operational Descriptors

Sometimes it is necessary to pass a parameter to a procedure even though the data type is not precisely known to the called procedure, (for example, different types of strings). In these instances you can use operational descriptors to provide descriptive information to the called procedure regarding the form of the parameter. The additional information allows the procedure to properly interpret the string. You should only use operational descriptors when they are expected by the called procedure.

Many ILE bindable APIs expect operational descriptors. If any parameter is defined as 'by descriptor', then you should pass operational descriptors to the API. An example of this is the ILE CEE API CEEDATM (Convert Seconds to Character Timestamp). The second and third parameters require an operational descriptor.

Note:

Currently, the ILE RPG compiler only supports operational descriptors for character and graphic types. Operational descriptors are not available for arrays or tables, or for data of type numeric, date, timestamp, basing pointer or procedure pointer. In addition, operational descriptors are not available for data structures for non-protototyped calls made using CALLB. However, for prototyped calls, data structures are considered to be character data, and operational descriptors are available.

Operational descriptors have no effect on the parameters being passed or in the way that they are passed. When a procedure is passed operational descriptors which it does not expect, the operational descriptors are simply ignored.

You can request operational descriptors for both prototyped and non-prototyped parameters. For prototyped parameters, you specify the keyword OPDESC on the prototype definition. For non-prototyped parameters, you specify (D) as the operation code extender of the CALLB operation. In either case, operational descriptors are then built by the calling procedure and passed as hidden parameters to the called procedure. Operational descriptors will not be built for omitted parameters.

You can retrieve information from an operational descriptor using the ILE bindable APIs Retrieve Operational Descriptor Information (CEEDOD) and Get Descriptive Information About a String Argument (CEESGI).

Note that operational descriptors are only allowed for bound calls. Furthermore, for non-prototyped calls, an error message will be issued by the compiler if the 'D' operation code extender is specified on a CALL operation.

Figure 68 shows an example of the keyword OPDESC.

Figure 68. Requesting Operational Descriptors for a Prototyped Procedure

      *-------------------------------------------------------------
      *  Len returns a 10-digit  integer value.  The parameter
      * is a character string passed by read-only reference.
      * Operational descriptors are required so that Len knows
      * the length of the parameter.
      *  OPTIONS(*VARSIZE) is required so that the parameter can
      *  be less than 32767 bytes.
      *-------------------------------------------------------------
     D Len             PR            10I 0 OPDESC
     D                            32767A   OPTIONS(*VARSIZE) CONST

For an example of how to use operational descriptors see Sample Service Program. The example consists of a service program which converts character strings which are passed to it to their hexadecimal equivalent. The service program uses operational descriptors to determine the length of the character string and the length to be converted.

[ Top of Page | Previous Page | Next Page | Contents | Index ]