gtpc2m3jC/C++ Language Support User's Guide

gdsnc-Get Data Set Entry

This function initializes an entry control block (ECB) data level or data event control block (DECB) with the data necessary to access a general data set or a volume of a general data set.

The function opens or closes the general data set, establishing a correct CCHR address on the specified ECB data level or DECB for the indicated relative record number (RRN) and initializes areas of the ECB as required.

Format

#include <tpfapi.h>
int      gdsnc(enum t_lvl level, unsigned char op, enum t_blktype size,
               int rrn_fmt, const char *dsn);

or

#include <tpfapi.h>
int      gdsnc(TPF_DECB *decb, unsigned char op, enum t_blktype size,
               int rrn_fmt, const char *dsn);

level
One of 16 possible values representing a valid ECB data level from enumeration type t_lvl, expressed as Dx, where x represents the hexadecimal number of the level (0-F). This parameter specifies the extended file address reference word (FAXW) into which the CCHR address corresponding to the indicated RRN will be placed. Once returned by this function, the contents of this ECB data level should not be changed by the application. The CE1FMx field for the level specified should be initialized to zero or to the volume sequence number desired.

decb
A pointer to a DECB. This parameter specifies the FAXW into which the CCHR address corresponding to the indicated RRN will be placed. Once returned by this function, the contents of this DECB must not be changed by the application. The IDECFM0 field for the DECB specified must be initialized to zero or to the volume sequence number desired.

op
Whether the data set is to be opened or closed. Use defined terms GDSNC_OPEN or GDSNC_CLOSE.

size
The size of the record. This parameter must belong to enumeration type t_blktype, defined in tpfapi.h. Use L1, L2, or L4 for TPF formatted records, or UNDEF for MVS formatted records.

rrn_fmt
Whether or not the data set being referred to has TPF format relative record numbers. Use the defined terms GDSNC_TPF_FMT to indicate TPF format, or GDSNC_NOT_TPF_FMT to indicate MVS (or other) RRN formatting.

dsn
This parameter is treated as a pointer to type char, in which the data set name must appear. This data set name must be left-justified in an array of type char, padded with blanks, and must be 16 bytes long.
Note:
Specifying level, op, size, or rrn_fmt parameters that are not valid results in a system error with exit.

Normal Return

Integer value of 0 indicating that the function completed successfully and that the FAXW has been updated with the proper CCHR address.

Error Return

4
Invalid RRN for data set (BAD_DSN_RRN)

8
Invalid RRN for currently mounted volume (BAD_VOL_RRN)

12
Missing volume sequence number (BAD_VOL_SEQ)

16
Data set not mounted (DSN_NOT_MNT)

24
Device-dependent data table was not found (DDT_NOT_FND)

Programming Considerations

Examples

The following example opens a data set on level D9 using TPF system format, 1055-byte records, data set name VM1.KMV.FILE, and issues an appropriate message if there is an error.

#include <tpfapi.h>
int zero = 0;

  ·
  ·
  ·
ecbptr()->ce1fm9 = zero; memcpy(&(ecbptr->ce1fx9[0]),&zero,4); switch (gdsnc(D9,GDSNC_OPEN,L2,GDSNC_TPF_FMT,"VM1.KMV.FILE ")) { case 0: break; case 4: /* in TARGET(TPF) this call was: errno = 0x123; perror("BAD DSN RRN"); abort(); in ISO-C it looks like: */ serrcop(SERRC_EXIT,0x123,"BAD DSN RRN",NULL) ; case 8: serrcop(SERRC_EXIT,0x234,"BAD VOL RRN",NULL) ; case 12: serrcop(SERRC_EXIT,0x345,"BAD VOL SEQ",NULL) ; case 16: serrcop(SERRC_EXIT,0x456,"DSN NOT MNT",NULL) ; case 24: serrcop(SERRC_EXIT,0x678,"DDT NOT FND",NULL) ; }

Related Information

See TPF Application Programming for more information about DECBs.