gtpc2m3j | C/C++ Language Support User's Guide |
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
- The CE1FMx field for the ECB data level or IDECFM0 field of the DECB
specified must be initialized to zero or to the volume sequence number
desired.
- The first fullword of the CE1FXx field of the ECB data level or IDECFX0
field of the DECB must contain zeros or the RRN of a desired record in a data
set. It must be zero to access the first record in the data set.
- Except for the ID and record code check (RCC) portions of the file address
reference words, the data inserted into the FARW by the TPF system must not be
changed.
- Applications that call this function using DECBs instead of ECB data
levels must be compiled with the C++ compiler because this function has been
overloaded.
- This function is implemented in dynamic link library (DLL)
CTAD. You must use the definition side-deck for DLL CTAD to link-edit
an application that uses this function.
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.