Retrieves or finds the DCB information allocated by a JCL DD statement by giving the DD name. If the tdcb_get_handle() API is executed, some DCB information, which is organized in the shared memory by JCL, is reorganized in the local memory area to allow for later access.

If allocation information is successfully retrieved, the allocation handle is returned, not a negative number. The returned allocation handle is subsequently used for DCB information querying or attribute modifying functions.

Discards the allocation information retrieved through the tdcb_get_handle() API. In other words, the DCB information built in the local memory area is discarded. Therefore, the tdcb_get_handle() API must be called again to get back the DCB information of the same DD.

It is not necessary to discard the allocation information obtained through the tdcb_get_handle() API, but if this API is repeatedly called for the same DD, an error message is displayed warning that the DD information is already organized in the local memory area.

If a DD, whose allocation information is not released by the tdcb_discard_handle() API in a C module, is opened in a COBOL module, the same warning message appears because an API similar to the tdcb_get_handle() API is called internally.

Prints the allocation information returned by the tdcb_get_handle() API.

The printed allocation information includes the following details:

DD_Name, JOB_Name, Allocation_Date, Allocation_Time, Concatenation_Count
+ [Sequence_Number] Slot_Number, DCB_Type, DCB_Name, DISPOSITION

Retrieves the DCB type and the number of sequential concatenations from the allocation information, which was returned by the tdcb_get_handle() API.

The following macros for the DCB types are defined in the tdcb.h header file:

#define TDCB_DCB_TYPE_NONE              0x00    /* Unknown */
#define TDCB_DCB_TYPE_NVSM              0x01    /* Non-VSAM */
#define TDCB_DCB_TYPE_TSAM              0x02    /* VSAM */
#define TDCB_DCB_TYPE_ISAM              0x03    /* ISAM */

The OpenFrame system provides a method to combine two or more non-VSAM data sets, which can be searched contiguously like a single data set. This is called sequential concatenation. The number of sequential concatenations represents the number of connected data sets.

The OpenFrame system does not support sequential concatenation of VSAM data sets. If the DCB type is TSAM, the 'count' parameter is not the number of sequential concatenations, but the total number of base clusters and alternate indexes that are connected to them.

Retrieves the maximum and average lengths of logical records from the allocation information returned by the tdcb_get_handle() API.

For non-VSAM data sets that are not sequentially concatenated or are of fixed length, the maximum and average record lengths are identical. However, in the case of sequentially concatenated non-VSAM data sets or variable length VSAM data sets, the lengths can be different.

For variable length non-VSAM data sets, the record length is the LRECL value that is set when allocating the data set in JCL. This is the logical record length including the length of the RDW.

Retrieves the DSORG and RECFM attributes of the non-VSAM data set from the allocation information, which was returned by the tdcb_get_handle() API.

The DSORG attribute of non-VSAM data sets specifies the organization of the data set. Available values for DSORG are as follows:

The RECFM attribute of non-VSAM data sets specifies the format or characteristic of the record. Available values for RECFM are as follows:

For example, if a data set supports fixed-length records and I/O in units of blocks, its RECFM attribute is specified as RECFM=FB. And if a data set is made of variable length records and includes ANSI control characters, its RECFM attribute is specified as RECFM=VA.

For sequentially concatenated non-VSAM data sets, the first data set's DSORG and RECFM attributes are returned. (In principle, mainframe does not allow sequential concatenation between non-VSAM data sets that have different basic attributes.)

For VSAM data sets, depending on the length type, DSORG=PS and RECFM=FB are returned for fixed length records and DSORG=PS and RECFM=VB for variable length records.

To retrieve the DSORG attribute from the allocation information, a string buffer pointer of 8 bytes or more in size must be specified as the 'dsorg' parameter. To retrieve the RECFM attribute, a string buffer pointer of eight bytes or more in size must be specified in the 'recfm' parameter. If a user string buffer is specified, the DSORG and RECFM attributes are copied to the user buffer with a NULL terminating character.

Retrieves the data set name and member name of a DCB component from the allocation information which was returned by the tdcb_get_handle() API. The DCB component represents a data set in the allocation information of sequentially concatenated non-VSAM data sets, or a base cluster or an alternate index in the VSAM allocation information.

To retrieve the allocated data set name, specify a string buffer pointer of at least 45 bytes in the 'dsname' parameter. This string buffer pointer is then copied to the user buffer with a NULL terminating character added.

You can retrieve the name of a PDS or PDSE data set member only. To retrieve the name, specify a string buffer pointer of at least 9 bytes in the 'member' parameter. The string buffer pointer is then copied to the user buffer with a NULL terminating character added.

Retrieves the volume serial information of a DCB component from the allocation information that was returned by the tdcb_get_handle() API. The DCB component represents a data set in the allocation information of sequentially concatenated non-VSAM data sets, or a base cluster or an alternate index in the VSAM allocation information.

To retrieve the volume serial information of the allocated DCB component, specify a string buffer pointer of at least 9 bytes in the 'volser' parameter. The string buffer pointer is then copied to the user buffer with a NULL terminating character added.

Retrieves various miscellaneous attributes or flags of a DCB component from the allocation information returned by the tdcb_get_handle() API. The DCB component represents a data set in the allocation information of sequentially concatenated non-VSAM data sets, or a base cluster or an alternate index in the VSAM allocation information.

The DCB component's various miscellaneous attributes represent the following macros defined in the tdcb.h header file:

#define TDCB_LRECL_NOT_SET              0x01
#define TDCB_RECFM_NOT_SET              0x04
#define TDCB_BLKSIZE_NOT_SET            0x08
#define TDCB_KEYLEN_NOT_SET             0x40
#define TDCB_IS_TAPE_DATASET            0x10
#define TDCB_IS_OPEN_INDICATOR          0x20

Descriptions for each macro are as follows:

Retrieves the block size and record length of a DCB component from the allocation information returned by the tdcb_get_handle() API. The DCB component represents a data set in the allocation information of sequentially concatenated non-VSAM data sets, or a base cluster or an alternate index in the VSAM allocation information.

For variable length non-VSAM data sets, the record length is the LRECL value that is set when allocating the data set in JCL. This is the logical record length including the length of the RDW is used.

If the record length information of the allocated DCB component is not necessary, set the 'reclen' parameter to NULL.

Retrieves the key location and key length from the allocation information returned by the tdcb_get_handle() API. The DCB component represents a data set in the allocation information of sequentially concatenated non-VSAM data sets, or a base cluster or alternate index in the VSAM allocation information.

If the key information of the allocated DCB component does not exist (for example, when the allocated data set is a non-VSAM data set and its DSORG is PS or PO), 0 is returned for the key location and key length.

Retrieves the VSAM data set type and AIX attribute of a VSAM DCB component from the allocation information returned by the tdcb_get_handle() API. The DCB component represents a data set in the allocation information of sequentially concatenated non-VSAM data sets, or a base cluster or an alternate index in the VSAM allocation information.

The following macros are defined for VSAM data set types in the tdcb.h header file:

#define TDCB_VSAM_TYPE_ESDS             0x01    /* ESDS */
#define TDCB_VSAM_TYPE_KSDS             0x02    /* KSDS */
#define TDCB_VSAM_TYPE_RRDS             0x04    /* RRDS */
#define TDCB_VSAM_TYPE_VRDS             0x05    /* VRDS */

The following macros are defined for the AIX attribute in the tdcb.h header file.

#define TDCB_RGATTR_EAIX                0x01
#define TDCB_RGATTR_KAIX                0x02
#define TDCB_RGATTR_UPGRADE             0x04

Descriptions for each macro are as follows:

Sets the logical record length of a DCB component in the allocation information returned by the tdcb_get_handle() API. The DCB component here represents a data set in the allocation information of sequentially concatenated non-VSAM data sets.

Before setting the logical record length by using the tdcb_set_lrecl() API, it is recommended to check that the DCB component's logical record length is already set in a catalog or JCL by using the tdcb_get_flags() API .

For variable length non-VSAM data sets, the record length is set when allocating the data set in JCL. This is the logical record length including the length of the RDW.

Sets the RECFM attribute of a specified DCB component in the allocation information returned by the tdcb_get_handle() API. The DCB component here represents a specified data set in the allocation information of sequentially concatenated non-VSAM data sets.

Before setting the RECFM attribute by using the tdcb_set_recfm() API, it is recommended to check that the DCB component's RECFM attribute is already specified in a catalog or JCL by using the tdcb_get_flags() API.

Sets the block size of a DCB component in the allocation information returned by the tdcb_get_handle() API. The DCB component here represents a data set in the allocation information of sequentially concatenated non-VSAM data sets.

Before setting the block size by using the tdcb_set_blksize() API, it is recommended to check that the DCB component's block size is already specified in a catalog or JCL by using the tdcb_get_flags() API.

Sets the key length and key location of a DCB component in the allocation information returned by the tdcb_get_handle() API. The DCB component here represents a data set in the allocation information of sequentially concatenated non-VSAM data sets.

Before setting the key length and key location by using the tdcb_set_keylen() API, it is recommended to check that the DCB component's key length is already specified in a catalog or JCL by using the tdcb_get_flags() API.

Allows an application to execute dynamic allocation on a data set, which is not defined through JCL, to access the data set.

Once dynamic allocation is executed on a data set using tdcb_allocate(), OPEN and I/O can be performed on the data set.

Concatenates a data set to the DD statement using a handle returned by tdcb_allocate().

Closes a data set on which dynamic allocation was executed using tdcb_allocate(), and then executes deallocation on the data set. The oferror command shows an error code.