Linking by dynamic calls

When you develop your z/OS® application to call HTTP APIs from COBOL or PL/I, ensure that you use dynamic linkage where possible, between the z/OS application code and the Host API load module supplied with IBM® z/OS Connect.

zosConnect-3.0 Applies to zosConnect-3.0.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

Why use dynamic linkage?

Using dynamic linkage is always preferred because it enables your program to use, without relinking, the most current version of the Host API load module and the associated transport modules delivered through regular z/OS Connect product maintenance. When static linkage is used, you must relink your z/OS application program to benefit from the latest maintenance.

Note: With the zosConnect-2.0 feature, CICS® PL/I programs that used BAQCSTUB required static linking but CICS PL/I programs that use the zosConnect-3.0 feature Host API verbs can now be dynamically linked.

When can dynamic linkage be used?

Dynamic linkage can be applied to the Host API module <hlq>.SBAQLIB1(BAQHAPIC) for CICS applications, and <hlq>.SBAQLIB(BAQHAPIW) for IMS and z/OS applications, and <hlq>.SBAQLIB2 (BAQHAPIT) for IMS applications that use the IMS Transaction Manager Resource Adapter.

How to make dynamic calls

Follow Table 1 to find out how to make dynamic calls based on your environment and the application programming language used.
Table 1. Methods to make dynamic calls
Environment Language Programming instructions
CICS COBOL Use the CALL identifier statement  1   3 . For detailed instructions, see Using CALL identifier to make dynamic calls in COBOL.
CICS PL/I For detailed instructions, see Making dynamic calls from PL/I applications.
z/OS applications COBOL Two methods are available:
Note:
  •  1  CALL identifier, where identifier is a data item that contains the name of a nonnested subprogram at run time, always results in the target subprogram being loaded when it is called.
  •  2  CALL literal, where literal is the explicit name of a nonnested target subprogram, can be resolved either statically or dynamically.
  •  3  Use copybook BAQHCONC that defines a number of 77 Level variables, one per Host API verb. For example, BAQ-INIT-NAME for BAQINIT.

Making dynamic calls from COBOL applications

To help ensure that your COBOL application uses dynamic linkage with the Host API load module, you can use one of the following methods:

Using CALL identifier to make dynamic calls in COBOL
Using the CALL identifier statement is an explicit method for the COBOL programmer to use dynamic linkage.
Note: For CICS COBOL applications, this method is the only one supported.
An example of using this explicit dynamic link convention for COBOL is shown: 

       B-INIT SECTION.
       B-010.
      * Initialise the Host API
           CALL BAQ-INIT-NAME USING BY REFERENCE BAQ-ZCONNECT-AREA.
 
      * Check for bad initialization
           IF NOT BAQ-SUCCESS THEN
              MOVE BAQ-ZCON-COMPLETION-CODE TO WS-CC9
              MOVE BAQ-ZCON-REASON-CODE TO WS-RC9
              STRING WS-PROGRAM
                 '--INIT failed'
                 '-CC-' WS-CC9
                 '-RC-' WS-RC9
                 DELIMITED BY '>'
                 INTO WS-DISPLAY-MSG
 
              DISPLAY WS-DISPLAY-MSG
              DISPLAY BAQ-ZCON-RETURN-MESSAGE
             
              STOP RUN
           END-IF.
 
       B-999.
           EXIT.
Using CALL literal and DYNAM to make dynamic calls in COBOL (non-CICS)
If your COBOL application specifies the CALL target as a literal string, 'BAQINIT', static linkage is used. To force your z/OS application to use dynamic linkage, you must set the DYNAM compile option to YES when you compile your application.
Note: This method is not supported for CICS COBOL applications when you use the z/OS Connect API requester feature because the Host API uses the CICS translator but the CICS translator cannot be used with the DYNAM option.
An example of using a static link convention for COBOL:

* Invoke the z/OS Connect Host API by using static linkage 
  CALL 'BAQINIT' USING BY REFERENCE BAQ-ZCONNECT-AREA.

For more information about how to use DYNAM, see the A launch icon to indicate a link opens a new tab or window. in the Enterprise COBOL for z/OS documentation.

Making dynamic calls from PL/I applications

To ensure that your PL/I application uses dynamic linkage with the Host API, you must declare the Host API verb as EXTERNAL together with the ENTRY OPTIONS attribute NODESCRIPTOR. Then use a FETCH statement to dynamically load the Host API verb, and then use a CALL statement to invoke the verb. This method is considered best practice for PL/I applications when you use the API requester feature and is handled for you when you include the provided BAQHCONP include file.

An example of using this dynamic link convention for PL/I is shown:
// API requester Host API required copy books 
%include BAQHAREP; 
%include BAQHCONP; 

// BAQ Call return code 
DCL baq_rc UNSIGNED FIXED BIN(32); 

// Initialise the Host API 
baq_rc = BAQINIT(BAQ_ZCONNECT_AREA);
If the PL/I application needs to set any pointers to the null value, use the SYSNULL() function. For example, if the PL/I application is calling an endpoint operation that does not require request data, set the following values before calling BAQEXEC.
  BAQ_REQ_BASE_ADDRESS = SYSNULL(); 
  BAQ_REQ_BASE_LENGTH = 0;
If the PL/I application is calling an endpoint operation that does not expect response data, set the following values before calling BAQEXEC.
  BAQ_RESP_BASE_ADDRESS = SYSNULL(); 
  BAQ_RESP_BASE_LENGTH = 0;