Syntax, linkage, and programming considerations

Linkage stub method

(Recommended) Use the linkable stub routine GDKCSS from SYS1.CSSLIB to bind your object code. GDKCSS assumes a Language Environment already exists. If you want CDA to create and tear down a Language Environment for you, use GDKCSSNL to bind with your object code. If you attempt to use the z/OS Cloud Data Access services on a previous release of z/OS that does not support the z/OS Cloud Data Access Services, this method results in the service call receiving a return code of X'F02' (GDKK_UNSUPPORTED_RELEASE).

Dynamic Link Library

(Recommended for AMODE31 C language callers) Use the GDKDLL31 side file found in SYS1.SIEASID when binding your object code. GDKDLL31 assumes that you are already in a Language Environment in AMODE 31, and the calling language is XLC. At runtime, the GDKDLL31 dynamic load library found in SYS1.SIEALNKE will be found and used by the appropriate API. When Binding your C code into a program, ensure that DYNAM=DLL is specified as a IEWL parameter.

Recommended for AMODE64 C language callers) Use the GDKDLL64 side file found in SYS1.SIEASID when binding your object code. GDKDLL64 assumes that you are already in a Language Environment in AMODE 64, and the calling language is XLC. At runtime, the GDKDLL64 dynamic load library found in SYS1.SIEALNKE will be found and used by the appropriate API. When Binding your C code into a program, ensure that DYNAM=DLL and AMODE=64 is specified as a IEWL parameter.

Direct linkage method

Code the linkage to the z/OS DFSMSdfp Cloud Data Access services directly. This can be done if the program first confirms that the level of z/OS contains the CDA APIs.

The macros that define those names are:

• SYS1.MACLIB(CVT)
• SYS1.MACLIB(IHADFA)

The following example shows the assembler linkage:

L        R05,CVTPTR         
L        R10,CVTDFA(,R05)   
L        R12,DFADFVAD(,R10) 
L        R05,240(,R12) 
L        @15,8+4*GDK_serv_xxxxx(,R05)
BASR     @14,@15

In the example, xxxxx represents the last five letters of the service you want to call. This requires that the GDKKASM assembler macro be included. If you attempt to call the Cloud Data Access APIs on a previous release of z/OS that does not support the APIs, this method may result in the application receiving an abend X'019'.

If using the Direct Linkage method, some APIs require an existing Language Environment. To facilitate better performance when using the I/O APIs via the Direct Linkage method, it is assumed that a Language Environment exists. It is also assumed that one will not be created or destroyed upon entry or exit to the API. A Language Environment preinitialization environment can be used (PIPI) for this requirement.

API Entry Offset from DFVCDAVT	API Name	Language Environment Requirement
12 (C)	GDKDEL	YES
16 (10)	GDKGET	YES
20 (14)	GDKGETP	YES
24 (18)	GDKLIST	YES
28 (1C)	GDKWRITE	YES
32 (20)	GDKKEYAD	NO
36 (24)	GDKKEYDL	NO
40 (28)	GDKKEYGR	NO
44 (2C)	GDKKEYSR	NO
48 (30)	GDKMSGTR	NO
52 (34)	GDKGEN	YES
56 (38)	GDKGENN	NO
60 (3C)	GDKINIT	YES
64 (40)	*	*
68 (44)	GDKTERM	YES
72 (48)	*	*
76 (4C)	GDKVALD	YES
80 (50)	GDKVALDN	NO
84 (54)	GDKQUERY	YES
88 (58)	GDKQRYN	NO
92 (5C)	GDKMSGTL	YES
96 (60)	GDKLISTL	YES
100 (64)	GDKKYSRL	YES

#pragma linkage(HWTHxxxx_CALLTYPE,OS)

• Register 1 must contain the address of a parameter list that is a list of consecutive words, each containing the address of a parameter to be passed. The last word in this list must have a 1 in the high-order (sign) bit.
• Register 13 must contain the address of an 18-word save area.
• Register 14 must contain the return address.
• Register 15 must contain the entry point address of the service being called.
• If the caller is running in AR ASC mode, access registers 1, 13, 14, and 15 must all be set to zero.
• On return from the service, general and access registers 2 - 14 are restored (registers 0, 1 and 15 are not restored).

OMVS segment

(Required) The CDA APIs use z/OS Web Enablement Toolkit services, which use TCP/IP sockets and Cryptographic Services System SSL services. Because these services require a z/OS UNIX (POSIX) environment, the CDA APIs run with a Language Environment POSIX(ON) environment. A POSIX(ON) environment requires the user ID associated with the address space using the CDA API services to have an OMVS segment defined and associated with it. See the appropriate security product documentation, as applicable to your installation, for instructions on how to define an OMVS segment to a user.

z/OS UNIX limit of processes with a POSIX(ON) environment and its effect on concurrent connections:

z/OS UNIX limits the number of concurrent POSIX(ON) environments that can be defined to a single address space. Since each CDA API call attempts to initialize a new POSIX(ON) environment (because of the environmental requirements listed earlier), each connection gets implicitly dubbed by Language Environment. (Dub means to make a z/OS address space known to z/OS UNIX System Services. Once dubbed, an address space is considered to be a process.) If multiple connections are wanted from the same application (address space), a consideration of the dubbing configuration for the address space in which the CDA API service is running may be necessary.

The dubbing behavior that z/OS UNIX takes is customizable by using the z/OS UNIX set dub default service (BPX1SDD or BPX4SDD). If the dub default for the address space is set to DUBPROCESS, this allows concurrent subtasks to each have their own POSIX(ON) environment, which allows multiple connections from within the same address space, provided that each subtask has at most one connection.

z/OS Language Environment Heap runtime option considerations:

The CDA API service obeys the current Language Environment Runtime HEAP option for storage management. Applications can customize the HEAP storage option for their execution environment as needed. IBM does not recommend using a primary heap size that is smaller than 32K.

z/OS Language Environment Runtime Environment REUSE (RTEREUS) option consideration:

COBOL applications running in Information Management System (IMS) should not use the RTEREUS(ON) runtime option. For more information, see RTEREUS (COBOL only) in z/OS Language Environment Customization.

TCP/IP stack and security product control

A CDA API application connecting to a server is limited by security profiles and definitions that are already in effect on the system where the application resides. Powerful controls, such as z/OS Communications Server NetAccess, in conjunction with security profiles defined using the SERVAUTH class, can be used to control network access authority, TCP/IP stack access authority, port access authority, and more. These security definitions can be configured to be as granular as required by an installation. For more information, see z/OS Communications Server: IP Configuration Guide and z/OS Communications Server: IP Configuration Reference.

log-level

Can be used to indicate the logging level during CDA API processing. CDA API logging is written to stderr. When executing in a JCL environment, stderr is defined by the C MSGFILE environment variable. The default is a DD named SYSOUT. For more information, see Config file.

web-toolkit-logging

Requests logging from the z/OS Client Web Enablement Toolkit. Output is written to stdout. Specify true to request logging. The special key, unredacted may be specified to request unredacted output in the log.