gtpa2m3jApplication Programming

General Data Set and General File Support

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:

Function
Action

 gdsnc 
General Data Set Name -- Associates a data set name with a unique entry by using the MVS data definition name (DDNAME) concept. (This is functionally similar to an MVS OPEN.)

 gdsrc 
General Data Set Record -- Accesses a specific record in the data set named by the gdsnc function. (This corresponds to the use of FACE/FACS for obtaining a file address).

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.

General Data Set Functions

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.

Note:
Nothing prevents the DDNAME and the DSNAME from being the same.

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