Data Set I/O API

This appendix describes how to read and write a record using the Data Set I/O API in a C application.

1. Overview

Using the Data Set I/O API provided by OpenFrame, applications written in C can perform read/write operations on data sets allocated by JCL DD statements.

It is recommended that the FCD Handling API library be used to perform read/write operations (I/O) on data sets opened by a main COBOL application within a sub-program written in C.

To write a program using the Data Set I/O API, you must include the tcppfh.h header file from the OpenFrame binary in the program and link the libtcppfh.so library during compilation.

The Data Set I/O API can be categorized as follows:

  • File Open/Close

    API Description

    tcfh_open()

    Opens a data set to process a record.

    tcfh_close()

    Closes the data set opened to process a record.

  • Record Access

    API Description

    tcfh_start()

    Moves the internal record pointer for sequential processing.

    tcfh_read()

    Reads a record from the data set.

    tcfh_write()

    Writes a record to the data set.

    tcfh_rewrite()

    Modifies the content of a record in the data set.

    tcfh_delete()

    Deletes a record from the data set.

  • PDS Member Handling

    API Description

    tcfh_bldl()

    Creates the list of PDS directories.

    tcfh_bldl_info()

    Reads the list of PDS directories.

    tcfh_find_by_bldl()

    Accesses members of PDS by using the directory list of data sets.

    tcfh_find_by_name()

    Accesses members of PDS by using the member name of the data set.

    tcfh_stow()

    Adds, replaces, deletes, changes, or initializes members of PDS.

2. File Open/Close

2.1. tcfh_open()

Opens a data set to process a record. Opening a data set allocated by JCL DD statement is a preparatory step to process I/O, such as reading or writing actual records.

  • Prototype

    int tcfh_open(tcfh_file_t *file, int open_mode, int flags);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be opened.

    open_mode (IN)

    Data set open mode.

    • INPUT

    • OUTPUT

    • INOUT

    • EXTEND

    flags (IN)

    Data set open option.

    • NO REWIND

    • VB MOVE: When opening a VB data set, the RDW is not included in the record length.

  • Return Value

    If successfull, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    To open a data set, you must provide the pointer to the file structure that contains information about the data set. This file structure is defined in the tcppfh.h header file.

    /* -------------------------- file I/O block --------------------------- */

typedef struct tcfh_file_s {
    char        file_name[8+2];     /* file name - SELECT clause */
    char        file_status[2];     /* file status - I/O interface */
    uint8_t     organization;       /* organization - SELECT clause */
    uint8_t     access_mode;        /* access mode - SELECT clause */
    uint8_t     open_mode;          /* open mode - tcfh_open() */
    uint8_t     misc_flags;         /* miscellaneous - SELECT clause */
    /* 64 bit separating line */
    char        file_path[256];     /* file path - tcfh_open() */
    /* 64 bit separating line */
    int32_t     file_handle;        /* file handle - tcfh_open() */
    int32_t     relative_key;       /* relative key - C(C++) program */
    /* 64 bit separating line */
    int16_t     key_length;         /* key length - DCL statement */
    int16_t     key_loc;            /* key position - DCL statement */
    int16_t     rec_size;           /* record size - DCL statement */
    int16_t     cur_reclen;     /* current record length - I/O interface */
    ...
} tcfh_file_t;

    The following is a list of entries that need to be specified in the file structure.

    Entry Description

    file_name

    DD name defined in JCL.

    organization

    Data set structure.

    • 0 : sequential

    • 1 : relational

    • 2 : index

    acess_mode

    Access mode.

    • 0 : sequential

    • 1 : direct

    • 2 : both

    When the data set is opened, the open mode must be specified as a parameter in the tcppfh_open() API. Supported data set open modes are as follows:

    Macro OPEN mode Description

    TCFH_OPEN_INPUT

    0

    INPUT mode.

    TCFH_OPEN_OUTPUT

    1

    OUTPUT mode.

    TCFH_OPEN_INOUT

    2

    INPUT/OUTPUT mode.

    TCFH_OPEN_EXTEND

    3

    EXTEND mode.

    When a data set is successfully opened, the values of entries (file_status, file_path, and file_handle) are set in the file structure.

2.2. tcfh_close()

Closes the data set opened for record processing. Closing a data set is the process of terminating the physical connection between an application and a data set after finishing I/O operations.

  • Prototype

    int tcfh_close(tcfh_file_t *file, int flags);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be closed.

    flags (IN)

    Option for closing data sets.

    • WITH LOCK

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    The following are some helpful tips about the tcfh_close() command.

    • Pass the file structure pointer provided by tcfh_open() API through the 'file' parameter of the tcfh_close() API.

    • A data set that is successfully closed through the tcfh_close() API can be reopened by using the tcfh_open() API.

3. Record Access

3.1. tcfh_start()

Moves the internal record pointer to the next record to start reading from a relative data set or indexed data set. For a relative data set, the next location is set by specifying a relative record number in the relative_key field of the file structure. For an indexed data set, it is set by specifying the key value in the 'key' parameter of the tcfh_start() API.

  • Prototype

    int tcfh_start(tcfh_file_t *file, char *key, int keylen, int flags);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    key (IN/OUT)

    Key value for an indexed data set.

    keylen (IN)

    Key length for an indexed data set.

    flags (IN)

    Data set START option.

    • EQUAL

    • GTEQ

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    Consider the following when using the START command.

    • Data set must be opened in INPUT or INOUT mode to perform the START command.

    • To verify the status of the file structure, the START command must be executed first.

    • For an RRDS data set, the file structure’s relative key field is used as RRN.

3.2. tcfh_read()

Reads a data set’s record sequentially or randomly by specifying a key.

For random record access of a relative data set, the relative record number is specified in the relative_key field of the file structure, and the key value of an indexed data set is specified in the 'key' parameter of the tcfh_read() API.

The TCFH_READ_NEXT macro in the 'flags' parameter of the tcfh_read() API is specified for sequential record access and the TCFH_READ_DEFAULT macro for random record access.

When using the READ command to read from a data set with variable length records, the record length can be obtained by checking the file structure’s cur_reclen field. The record length is the length of record data copied to the buffer specified in the 'buf' parameter of the tcfh_read() API. This is the length of the data portion of the record excluding RDW.

  • Prototype

    tcfh_read(tcfh_file_t *file, char *key, int keylen, char *buf, int buflen,
          int flags);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    key (IN/OUT)

    Key value for an indexed data set.

    keylen (IN)

    Key length for an indexed data set.

    buf (OUT)

    Buffer that stores the data record.

    buflen (IN)

    Size of the data record buffer.

    flags (IN)

    Data set READ option.

    • DEFAULT

    • NEXT

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    Consider the following when using the READ command.

    • The data set must be opened in either INPUT or INOUT mode to run the READ command.

    • After running the command, the file_status of the file structure can be used to check the status of the file.

    • For an RRDS data set, the relative_key field of the file structure is used as the RRN.

    • The length of the record data that is read can be determined by reading the cur_reclen field of the file structure.

3.3. tcfh_write()

Writes a new record into a data set. For a sequential data set, the record is added at the end. For a relative data set, the record is inserted at the location given by the relative record number specified in the file structure’s relative_key field. For an indexed data set, a record is stored in the key order specified in the 'key' parameter of the tcfh_write() API.

When using the WRITE command to write to a data set with variable length records, the length of record is specified by the 'buflen' parameter of the tcfh_write() API. The record length is the length of record data in the buffer specified in the 'buf' parameter of the tcfh_write() API. This is the length of the data portion of the record excluding RDW.

  • Prototype

    tcfh_write(tcfh_file_t *file, char *key, int keylen, char *buf, int buflen,
           int flags);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    key (IN/OUT)

    Key value for an indexed data set.

    keylen (IN)

    Key length for an indexed data set.

    buf (OUT)

    Buffer that contains the data record.

    buflen (IN)

    Size of the data record buffer.

    flags (IN)

    Data set WRITE option.

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    Consider the following when using the WRITE command.

    • The data set must be opened in OUTPUT, INOUT, or EXTEND mode to use the WRITE command.

    • If the data set is opened in INOUT mode, sequential write operations cannot be performed.

    • After the command is executed, the file_status of the file structure can be used to check the status of the file.

    • For an RRDS data set, the relative_key field of the file structure is used as the RRN.

3.4. tcfh_rewrite()

Modifies an existing record in a data set. For a relative data set, the record given by the relative record number specified in the file structure’s relative_key field is modified. For an indexed data set, a record that fits the key order specified in the 'key' parameter of the tcfh_rewrite() API is modified.

When using the REWRITE command to modify a record in a data set with variable length records, the length of the record to be modified is specified by the 'buflen' parameter of the tcfh_rewrite() API. The record length is the length of record data in the buffer specified in the 'buf' parameter of the tcfh_rewrite() API. This is the length of the data portion of the record excluding RDW.

  • Prototype

    tcfh_rewrite(tcfh_file_t *file, char *key, int keylen, char *buf, int buflen,
             int flags);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    key (IN)

    Key value for an indexed data set.

    keylen (IN)

    Key length for an indexed data set.

    buf (IN)

    Buffer that contains the data record.

    buflen (IN)

    Size of the data record buffer.

    flags (IN)

    Data set REWRITE option.

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    Consider the following when using the REWRITE command.

    • The data set must be opened in INOUT mode to use the REWRITE command.

    • For sequential accesses, the record to be modified must be read with READ first before REWRITE.

    • After running the command, the file_status of the file structure can be used to check the status of the file.

    • For an RRDS data set, the relative_key field of the file structure is used as the RRN.

3.5. tcfh_delete()

Deletes a record from a data set for either a relative data set or an indexed data set. For a relative data set, the record given by the relative record number specified in the file structure’s relative_key field is deleted. For an indexed data set, a record that matches the key order specified in the 'key' parameter of the tcfh_delete() API is deleted.

  • Prototype

    int tcfh_delete(tcfh_file_t *file, char *key, int keylen, int flags);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    key (IN)

    Key value for an indexed data set.

    keylen (IN)

    Key length for an indexed data set.

    flags (IN)

    Data set DELETE option.

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    Consider the following when using the DELETE command.

    • The data set must be opened in INOUT mode to use the DELETE command.

    • For sequential accesses, the record to be deleted must be READ before DELETE.

    • After running the command, the file_status of the file structure can be used to check the status of the file.

    • For an RRDS data set, the relative_key field of the file structure can be used as the RRN.

4. PDS Member Handling

4.1. tcfh_bldl()

Creates the list of PDS directories.

  • Prototype

    int tcfh_bldl(tcfh_file_t *file, char *filter);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    filter (IN)

    Filter for members to include in the PDS list. If you want to create a list of all members of the data set, use an Asterisk (*) or a null value. If you want to create a list only with members that begin with the letters "ABC", set this parameter to "ABC".

  • Return Value

    If successful, the number of members in the directory list is returned. If an error occurs, a negative error code is returned.

  • Note

    The followings are some helpful tips about the BLDL command:

    • After running the command, the file_status of the file structure can be used to check the status of the file.

4.2. tcfh_bldl_info()

Reads the list of PDS directories. This command can be used after executing the tcfh_bldl() command first.

The TCFH_READ_NEXT macro in the 'flags' parameter of the tcfh_read() API is specified for sequential record access and the TCFH_READ_DEFAULT macro is specified for random record access.

When using the READ command to read from a data set with variable length records, the record length can be obtained by checking the file structure’s cur_reclen field. The record length is the length of record data copied to the buffer specified in the 'buf' parameter of the tcfh_read() API. This is the length of the data portion of the record excluding RDW.

  • Prototype

    int tcfh_bldl_info(tcfh_file_t *file, int number, tcfh_membstat_t *stat);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    number (IN)

    Path to the directory.

    stat (OUT)

    Key length for an index data set.

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    To retrieve the member information, you must specify a pointer to the file structure, where the member information is stored. The file structure is defined in the tcfh.h header file.

    /* -------------------------- file I/O block --------------------------- */

typedef struct tcfh_membstat_s {
    char            member[64];
    int64_t         size;
    char            lastmoddt[8+2];   /* last modified date */
    char            lastmodtm[6+2];   /* last modified time */
} tcfh_membstat_t;

    The information provided in the file structure is as follows:

    Item Description

    member (OUT)

    Name of the member in PDS.

    size (OUT)

    Size of the Unix file where the member is specified.

    lastmoddt (OUT)

    Last modification date of the member.

    lastmodtm (OUT)

    Last modification time of the member.

4.3. tcfh_find_by_bldl()

Accesses members of PDS. This command can be used after executing the tcfh_bldl() command first.

  • Prototype

    int tcfh_find_by_bldl(tcfh_file_t *file, int num);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    num (IN)

    Key value for an index data set.

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    The following are some helpful tips about the FIND command:

    • After running the command, the file_status of the file structure can be used to check the status of the file.

4.4. tcfh_find_by_name()

Accesses members of PDS. This command can be used regardless of the use of tcfh_bldl().

  • Prototype

    int tcfh_find_by_name(tcfh_file_t *file, char *name);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    name (IN)

    Name of the member to be accessed.

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    The followings are some helpful tips about the FIND command.

    • After running the command, the file_status of the file structure can be used to check the status of the file.

4.5. tcfh_stow()

Adds, replaces, deletes, changes, or initializes members of PDS.

  • Prototype

    int tcfh_stow(tcfh_file_t *file, char *name, int flags);

  • Parameters

    Parameter Description

    file (IN/OUT)

    File structure that stores information about the data set to be processed.

    name (IN)

    Name of the member to be processed. When changing a member name, a slash (/) is used to split the name into before and after modification. (Example: "BEFORE/AFTER")

    flags (IN)

    Data set STOW option.

    • TCFH_STOW_ADD

    • TCFH_STOW_DELETE

    • TCFH_STOW_CHANGE

    • TCFH_STOW_REPLACE

    • TCFH_STOW_INITIALIZE

  • Return Value

    If successful, 0 is returned. If an error occurs, a negative error code is returned.

  • Note

    Consider the following when using the STOW command.

    • The WRITE command must precede when adding or replacing a member.

    • After running the command, the file_status of the file structure can be used to check the status of the file.

5. File Status Code

After performing read/write on a data set, check the current status of the data set in the file_status field of the file structure that contains information about the data set. The file_status field contains the status code on the data set.

The following describes the status codes of a data set.

Code Description

00

Job executed successfully.

02

For an index file, duplicate keys found in a data set where duplicate keys are allowed.

10

There is no next record. (That is, EOF read)

22

For an index file or relational file, a duplicate key error has occurred.

23

The record corresponding to the key cannot be found. (A member cannot be found in case of the FIND command.)

37

The specified open mode is not supported.

38

Attempted to open a file that is already closed with lock.

39

Attribute of the data set is invalid.

41

Attempted to open a file that is already open.

42

Attempted to close a file that is already closed.

43

READ does not precede the REWRITE or DELETE command in the sequential mode.

44

The length of record to be rewritten is not the same as that of the existing one.

47

READ or START command executed when the mode is not INPUT or INOUT.

48

WRITE command executed when the mode is not OUTPUT, INOUT, or EXTEND.

49

DELETE or REWRITE command executed when not in INOUT mode.

99

System error occurred.