Defining and Using Functions › Writing an External Function in COBOL, PL/I, or Assembler

Writing an External Function in COBOL, PL/I, or Assembler

You can write the program associated with a function in COBOL, PL/I or Assembler. This requires the function to be defined with PROTOCOL IDMS. When called, the program is passed a fixed parameter list consisting of the parameters specified in the function definition, as well as additional parameters used for communication between CA IDMS and the function.

Whenever a function is invoked, CA IDMS calls the program associated with the function to service the request. The function responds by processing the input parameters. An error condition can optionally be set in SQLSTATE.

CA IDMS performs transaction and session management automatically in response to requests that the originating application issues. Changes to the database made by a function are committed or rolled out together with other changes made within the SQL transaction. No special action is required of the function in order to ensure that this occurs.

The next section discusses writing a function in detail.

For an example of a function written in COBOL, see Sample COBOL Function.

Calling Arguments

The following sets of arguments are passed when a function is called:

• One argument for each of the parameters specified on the function definition, passed in the order in which the parameters were declared. These arguments vary from function to function; they are used to pass values to the function.
• One argument to contain the return value of the function. The implicit name for this argument is USER_FUNC.
• One argument for each null indicator associated with a parameter specified in the function definition, passed in the order in which the parameters were declared. These arguments vary from function to function; they are used to pass values to the function.
• One argument for the null indicator associated with the return value of the function (the null indicator for the USER_FUNC parameter).
• A set of common arguments used for communications between CA IDMS and the function. This set of arguments, shown in the following table, is the same for all functions.

Parameter Arguments

On entry to the program associated with a function, the value of the arguments corresponding to the parameters defined in the CREATE FUNCTION statement are as follows:

• Non-null parameters contain one of the following:
  • The parameter values specified on the function reference
  • The data type-specific default value if WITH DEFAULT was specified in the function definition, and no value was specified in the function invocation
• All other parameters contain nulls (that is, the null indicator for the parameter is negative).

On exit, the program associated with the function is expected either to have set the value of the parameter USER_FUNC, holding the functions return value and the corresponding indicator appropriately, or to have set an SQLSTATE value indicating no-more-rows. If the indicator parameter is set to -1, CA IDMS ignores the value of the USER_FUNC parameter.

Local Work Area

Another parameter passed on each call to a function is a local work area.

CA IDMS allocates the local work area just before calling the function and frees it immediately after the function exits. When the local work area is allocated, it is initialized to binary zeros.

Global Work Area

A global work area is a storage area that can be shared across one or more functions or other SQL routines within a transaction. Each global work area has an associated key that is one of the following:

• Four-character identifier specified on the GLOBAL WORK AREA clause
• Fully-qualified name of the function if no identifier was specified

All SQL routines executing within a transaction and having the same global storage key share the same global work area.