The Application Program Interface

The high-level application-program, DGADCHLA, handles communication between the Connect:Direct® for z/OS® API and any application program that provides IBM® Connect:Direct with command strings for batch processing. You can write an application program following the rules described in the following sections.

You can also process IBM Connect:Direct command strings by using the DGADBATC batch interface program. For more information on using DGADBATC, refer to Sample Job Stream to Run the Batch Interface.


You can design user-written applications that have an interface to IBM Connect:Direct. You can write the applications in any computer language, including PL/I, Assembler, and COBOL. The following samples are in the $CD.SDGASAMP library:

Application Name Description
DGAXSAMP Assembler language user-written application
DGAXPLIS PL/I language user-written program
DGAXCOBS COBOL language user-written program
Important: All API programs run in 31-bit mode and they must call DGADCHLA in 31-bit mode. You can either link your program as AMODE 31, or establish 31-bit addressability before calling DGADCHLA. See the sample program DGAXSAMP for an example of establishing 31-bit addressability and returning to 24-bit addressability after the call to DGADCHLA. Also execute DGADCHLA with a BASSM rather than a BALR. Macro GENCALL is provided in the sample library to perform a BASSM. See the sample program DGAXSAMP for an example.
Attention: When calling DGADCHLA from an application that uses multiple subtasks to invoke the API simultaneously, it is recommended that an APIINIT call be made from the application main task or a permanent subtask prior to attaching the API subtasks. The APIINIT call will anchor and initialize DCB storage for standard print/trace DDs used by all API subtasks. This will prevent possible ABEND conditions caused by CLOSE or I/O requests from subtasks that did not initially OPEN those DCBs. APIINIT should only be issued once by the application and will cause SCIB025I messages to be written to the DDs identified in SDGAMAC member DGA$SYAT, if they are present. APIINIT is specified as the ninth parameter and all other parameters will be ignored for that call.