openFT transfers absolute and relative generation data sets from PS data sets. openFT does not, however, create new generation data groups; these must already exist before transfer takes place. In addition, a DSCB model (DSCB: Data Set Control Block) must exist on the same volume as contains the generation data group. (A DSCB model is created automatically and correctly if a generation data group is created in a user catalog with a TSO command. This is not the case if the generation data group is created in the "master catalog". In this event, a DSCB model must be explicitly created with JES JCL, as described in the IBM documentation; see VSAM Catalog Administration, Access Method Reference, for example.)
openFT cannot transfer entire generation data groups.
Absolute generation data set
The name of an absolute generation data set must be specified in the NCOPY command in the usual format for TSO:
fully qualified file name:
'generationgroup.GmmmmVnn'partially qualified file name:
generationgroup.GmmmmVnn
generationgroup
name of the generation data group
max. 35 characters with "first level qualifier" (fully qualified)
max. 27 characters without "first level qualifier" (partially qualified)
mmmm
is the absolute generation number (between 0000 and 9999)
nn
is the version number (between 00 and 99)
Relative generation data set
The name of a relative generation data set must also be specified in the usual format for TSO:
fully qualified file name: 'generationgroup(0)' or 'generationgroup(±m)'partially qualified file name: generationgroup(0) or generationgroup(±n)
generation group: is the name of the generation data group (see above)
(...)
is the relative generation number:
(0)
current generation
(±m)
m = 1..255 (fully qualified specification)
(±n)
n = 1..99 (partially qualified specification)
In the following description, "(±n)" is used to represent both "(±m)" and "(±n)".
If a relative generation data set name is specified, openFT forms the absolute generation data set name according to the following rules:
Generation number
The absolute generation number is formed from the current generation number and the relative generation number specified:
relative generation number (0):
absolute generation number = current generation number
relative generation number (-n):
absolute generation number = generation number of the "n-th predecessor" of the current generation data set (determined using the LISTCAT command)
relative generation number (+n):
absolute generation number = current generation number + n modulo 9999
(The current generation number for an empty generation group is G0000.)
For files in the local system, the relative generation number is converted to an absolute generation number when the request is accepted. For files in the remote system, this conversion takes place at the start of request processing. In this context, please also refer to the notes at the end of this section.
Version number
When a receive file is first created, the version number is set to V00.
If the receive file already exists, the previous file name is used for
WRITE-MODE=*REPLACE or*EXTEND (no increment of the version number).
Existence of send and receive files when transferring relative generation data sets
If a relative generation data set is specified as the send file, then it must, of course, already exist.
The specification of a non-existent file generation as a send file (e.g. a positive relative file generation(+n)) therefore results in an error message.
New generation data sets (receive file) are created only if a relative generation data set > 0 is specified, regardless of the WRITE-MODE. In particular, it is not possible to create a "current" generation data set (0) in an empty generation data group.
If you specify a relative file generation ≤ 0 for a receive file while also specifying WRITE-MODE=*NEW, an error message is output.
You may specify a relative generation data set ≤ 0 for a receive file if WRITE-MODE=*REPLACE or *EXTEND is also specified; only an existing generation data set, however, can be replaced or extended. If the corresponding generation data set does not exist, an error message is issued.
Causes of the error message FTR0020
The message FTR0020 is issued in many of the error situations mentioned above that can arise in the context of file generation:
FTR0020 OPENFT: 'file' not found.
This error message may be caused by:
The generation data group of the send or receive file does not exist.
The relative generation number (0) was specified but the generation group of the send or receive file is empty.
A relative generation number (-n) was specified but the corresponding generation data set (send or receive file) does not exist.
Please also observe the following notes on transferring relative generation data sets:
If the absolute generation number G9999 is exceeded, modulo 9999 applies (see above), i.e. the generation number reverts to zero in the sequence of counting. This can have unexpected results if an absolute generation number calculated in this way has already been assigned to existing generations.
When a new generation is created, the oldest generation or all previous generations may be deleted (depending on the LIMIT, EMPTY/NOEMPTY and
SCRATCH/NOSCRATCH parameters specified in the DEFINE-
GENERATIONDATAGROUP command when the generation data group was created).For files in the local system, the relative generation data set name is converted to an absolute generation data set name when the request is accepted. For files in the remote system, this conversion takes place at the start of request processing. Once a generation name has been assigned, it remains the same throughout request processing. This has the following results:
If, once the absolute generation data set name has been formed, new file generations are created (e.g. by a batch job executing in parallel), the resulting displacement of the "current" generation data set number is not taken into account.
The relative generation data set name appears in the result list and in the transfer logging function (FT administrator function, see the manual "openFT (z/OS) - Installation and Operation") exactly as it was specified in the NCOPY command.
Similarly, in a NSTATUS or NCANCEL command, you must specify the relative generation data set name exactly as it was specified in the original NCOPY command.
There is no way of ensuring that two transfer requests cannot access the same generation data group. If this occurs, the generation numbering may be displaced unexpectedly.
In an FT system which does not support the specification of relative generation data set names for REM=*MSP, the REM=*ANY syntax can be used to access a relative generation data set as a send or receive file in a remote system of type openFT (z/OS).
Inbound file management requests cannot access relative file generations.