gtpc2m3k | C/C++ Language Support User's Guide |
This function is provided to initialize a user's file address
reference word with the data necessary to access a general data set or a
volume of a general data set.
The function establishes a correct CCHR address on the specified entry
control block (ECB) data level or data event control block (DECB) for the
indicated relative record number (RRN) and initializes areas of the ECB as
required. This function works on an open general data set.
Format
#include <tpfapi.h>
int gdsrc(TPF_DECB *decb, enum t_blktype size,
const char *dsn);
or
#include <tpfapi.h>
int gdsrc(TPF_DECB *decb, enum t_blktype size,
const char *dsn);
- level
- One of 16 possible values representing a valid data level from the
enumeration type t_lvl, expressed as Dx, where x
represents the hexadecimal number of the level (0-F). This
parameter specifies the file address extension word (FAXW) onto which the CCHR
address of the indicated RRN is to be placed. Once returned by this
function, the contents of the file address reference word (FARW) and FAXW
should not be altered by the application.
- decb
- A pointer to a DECB. This parameter specifies the FAXW into which
the CCHR address of the indicated RRN will be placed. Once returned by
this function, the contents of the FARW and FAXW must not be changed by the
application.
- size
- The size of the record. This parameter must belong to the
enumeration type t_blktype, defined in
tpfapi.h. Use L1, L2, or
L4 for TPF-formatted records, or UNDEF for MVS-formatted
records.
- 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 a blank-padded array of type char, and must be 16
bytes long.
- Note:
- Specifying level or size parameters that are not valid
results in a system error with exit.
Normal Return
A return of 0 indicates 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
- The device-dependent table was not found (DDT_NOT_FND).
Programming Considerations
- 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 the
data set. This value must be zero to access the first record in the
data set.
- Except for the ID and 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 converts the relative record number shown into a CCHR
address to access the third record in data set
MAR.PNJ.FILE. The program issues an appropriate message
if there is an error.
#include <tpfapi.h>
int rrn = 2;
·
·
·
memcpy(&(ecbptr()->ce1fx3[0]),&rrn,4);
switch (gdsrc(D3,UNDEF,"MAR.PNJ.FILE "))
{
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.