gtpa2m3j | Application Programming |
General data sets are usually related to some offline processing. Either data is produced online (for example, management reports) to be processed by offline programs, or data is produced offline (for example, programs to be loaded) for online processing. A general data set provides a data interface between the offline and online system components.
A TPF general data set (a disk module) is related to the meaning of an MVS data set. The records of a data set are allocated sequentially in the same module (called a volume in MVS). The file is processed online by using the TPF find and file functions. The find and file function extensions have a parameter where GDS can be specified to indicate that a requested data record resides on a general file or general data set, rather than in the TPF online database. A special assembler macro, file data chain transfer (FDCTC), permits the processing of records that are not restricted to the standard TPF record sizes. A file with standard record sizes is processed online by using the TPF find and file functions. The file referencing is slightly different from the procedures used to access fixed record types and pool records.
TPF provides 2 distinct general data set functions to allow an ECB-controlled program to access records in a TPF general data set:
A command allows an operator to mount and dismount modules (volumes) associated with a data set and to make an association between a data set name and a data definition name. The combination of gdsrc and any find function is equivalent to an MVS GET.
A TPF general file is a sequentially organized set of data that, in principle, is similar to a general data set. However, general files are not MVS compatible. Limited classes of general files are used by system programs. They may be used by application programs if appropriate.
General files and data sets are exceptions to the online real-time environment and will not be discussed here in more detail. For more information about general data sets, see TPF Database Reference.
The general data set name (gdsnc) and general data set record (gdsrc) functions are used to access general data set records. gdsnc is used to open and close the data set. gdsrc is used to access specific records in the data set. The find and file functions are used to read from and write to the data set.
The general data set (GDS) support uses the MVS concept of data definition name (DDNAME) specified by the program and data set name (DSNAME) bound by the operator at execution time. The program, when coded, specifies a 16-character DDNAME as a parameter for the gdsnc function. The operator, when mounting the general data set for the program, specifies both the DDNAME and the DSNAME as part of the mount command. Then, when the gdsnc function is issued, the TPF system provides the binding to link the program to the correct data set as specified by the operator.
The user must open the data set with the gdsnc function by passing the DDNAME, volume sequence number, and relative record number of the data set. The volume sequence number and relative record number may be 0. gdsnc returns in the CE1FMx, CE1FCx, CE1FHx, and CE1FRx fields of the file address reference word (FARW) that the user specified with the function, the indexes necessary for the system to access the data set. The file address of the relative record in the data set is returned in CCHR format in the file address reference word extension (CE1FXx). If the relative record number was 0, the address of the first record of the data set is returned.
To access specific records in the data set, the user must pass with the gdsrc function the relative record number of the desired record. The relative record number may be zero. gdsrc returns the file address of the desired record in CCHR format in the file address reference word extension (CE1FXx). If the relative record specified was 0, the address of the first record of the data set is returned.
The find or file functions with the GDS parameter specified are used to read data from or write data to the general data set record.
After manipulating the data with the find and file functions, the user must close the general data set with the gdsnc function. The parameters passed are the same as those passed with gdsnc open. The FARW (CE1FMx, CE1FCx, CE1FHx, CE1FRx) is cleared on return from gdsnc close.
The following is an example of the use of the general data set macros for assembly language.
*********************************************************************** * "OPEN" THE GENERAL DATA SET. * *********************************************************************** XC CE1FM8(1),CE1FM8 VOLUME SEQUENCE NUMBER MVC EBW000(16),=CL16'TPF.DATA.SET.A' DDNAME MVC EBW016(4),=F'0' RELATIVE RECORD NUMBER LA R14,EBW000 ADDRESS OF DDNAME GDSNC D8,O,RCT=A,SIZE=L,WORK=YES OPEN DATA SET LTR R14,R14 CHECK RETURN CODE BNZ GDSNERR BRANCH IF ERROR *********************************************************************** * READ, UPDATE, AND WRITE THE FIFTH RECORD OF THE GENERAL DATA SET. * * WHEN WORK=YES THE USER MUST PASS THE RELATIVE RECORD NUMBER IN THE * * FOUR BYTES IMMEDIATELY FOLLOWING THE DDNAME. * *********************************************************************** LA R14,EBW000 ADDRESS OF DDNAME MVC EBW016(4),=F'5' RELATIVE RECORD NUMBER = 5 GDSRC D8,SIZE=L,WORK=YES GET ADDRESS OF 5TH RELATIVE RECORD LTR R14,R14 CHECK RETURN CODE BNZ GDSRERR BRANCH IF ERROR MVC CE1FA8(2),=CL2'GS' RECORD ID MVC CE1FA8+2(1),=XL1'00' RECORD CODE CHECK FINDC D8,GDS=Y READ DATA SET RECORD WAITC FINDERR BRANCH IF ERROR . . UPDATE THE DATA SET RECORD . FILEC D8,GDS=Y WRITE DATA SET RECORD WAITC FILEERR BRANCH IF ERROR *********************************************************************** * READ, UPDATE, AND WRITE THE THIRD RECORD OF THE SAME DATA SET. * * WHEN WORK=NO THE USER MUST PASS THE RELATIVE RECORD NUMBER IN THE * * FARW EXTENSION. * *********************************************************************** MVC CE1FX8(4),=F'3' RELATIVE RECORD NUMBER = 3 GDSRC D8,SIZE=L,WORK=NO GET ADDRESS OF 3RD RELATIVE RECORD LTR R14,R14 CHECK RETURN CODE BNZ GDSRERR BRANCH IF ERROR MVC CE1FA8(2),=CL2'GS' RECORD ID MVC CE1FA8+2(1),=XL1'00' RECORD CODE CHECK FINHC D8,GDS=Y READ DATA SET RECORD WAITC FINDERR BRANCH IF ERROR . . UPDATE THE DATA SET RECORD . FILUC D8,GDS=Y WRITE DATA SET RECORD WAITC FILEERR BRANCH IF ERROR *********************************************************************** * "CLOSE" THE GENERAL DATA SET. * *********************************************************************** LA R14,EBW000 ADDRESS OF DDNAME XC CE1FM8(1),CE1FM8 VOLUME SEQUENCE NUMBER MVC EBW016(4),=F'0' RELATIVE RECORD NUMBER GDSNC D8,C,RCT=A,SIZE=L,WORK=YES CLOSE DATA SET LTR R14,R14 CHECK RETURN CODE BNZ GDSNERR BRANCH IF ERROR