Using procedure and function pointers

Procedure pointers are data items defined with the USAGE IS PROCEDURE-POINTER clause. Function pointers are data items defined with the USAGE IS FUNCTION-POINTER clause. In this information, pointer refers to either a procedure-pointer data item or a function-pointer data item. You can set either of these data items to contain entry addresses of, or pointers to, these entry points:

• Another COBOL program that is not nested. For example, to have a user-written error-handling routine take control when an exception condition occurs, you must first pass the entry address of the routine to CEEHDLR, a condition-management Language Environment® callable service, so that the routine is registered.
• A program written in another language. For example, to receive the entry address of a C function, call the function with the CALL RETURNING statement. It will return a pointer that you can either use as a function pointer or convert to a procedure pointer by using a form of the SET statement.
• An alternate entry point in another COBOL program (as defined in an ENTRY statement).

The SET statement sets the pointer to refer either to an entry point in the same program object as your program, to a separate program object, or to an entry point that is exported from a DLL, depending on the DYNAM|NODYNAM and DLL|NODLL compiler options. Therefore, consider these factors when using these pointer data items:

• If you compile a program with the NODYNAM and NODLL options and set a pointer item to a literal value (to an actual name of an entry point), the value must refer to an entry point in the same program object. Otherwise the reference cannot be resolved.
• If you compile a program with the NODLL option and either set a pointer item to an identifier that will contain the name of the entry point at run time or set the pointer item to a literal and compile with the DYNAM option, then the pointer item, whether a literal or variable, must point to an entry point in a separate program objectlink. The entry point can be either the primary entry point or an alternate entry point named in an ALIAS binder (linkage-editor) statement.
• If you compile with the NODYNAM and DLL options and set a pointer item to a literal value (the actual name of an entry point), the value must refer to an entry point in the same program object or to an entry-point name that is exported from a DLL module. In the latter case you must include the DLL side file for the target DLL module in the link-edit of your program object.
• If you compile with the NODYNAM and DLL options and set a pointer item to an identifier (a data item that contains the entry point name at run time), the identifier value must refer to the entry-point name that is exported from a DLL module. In this case the DLL module name must match the name of the exported entry point.

If you set a pointer item to an entry address in a dynamically called program object, and your program subsequently cancels that dynamically called module, then that pointer item becomes undefined. Reference to it thereafter is not reliable.

Procedure pointer and function pointer calls are supported for AMODE 24 applications. However, the addressing mode cannot be switched for these calls, so the called and calling programs must have the same addressing mode at execution time.

COBOL entry points with the AMODE ANY attribute can be entered in either AMODE 31 or AMODE 24. However, the AMODE value that is in effect when the program is entered for the first time must also be in effect for all subsequent reentries of the program during the current Language Environment enclave.

        77  DATA-FUNCTION-PTR USAGE FUNCTION-POINTER.
        77  DATA-PTR REDEFINES DATA-FUNCTION-PTR USAGE POINTER.

        SET DATA-FUNCTION-PTR TO ENTRY "DATAONLY"
        SET ADDRESS OF DATA TO DATA_PTR

        77  DATA-PTR USAGE POINTER.

        CALL "DATAONLY" RETURNING DATA-PTR
        SET ADDRESS OF DATA TO DATA-PTR

        DATAONLY CSECT
                 USING  *,15
                 LA     15,DATA
                 BR     14
        *
        DATA     DC     ...
        ...
                 END

The revised method also works with earlier COBOLs.

Calls to procedure and function pointers must be from a module with a Language Environment stack frame, as will be the case for any high-level programming language. If such a call is to be made from an assembler module, an LE stack frame must be provided by using the CEEENTRY and CEETERM macros, along with the associated register content requirements.