Retrieving Information by Generation Data Set Name (LOCATE and CAMLST NAME)

Specify the name of a generation data set using the fully-qualified generation index name and the relative generation number of the data set. The value of a relative generation number reflects the position of a data set in a generation data group. The following values can be used to identify a data set in a generation data group:

Zero—specifies the latest data set (highest generation number) cataloged in a generation data group.
Negative number—specifies a data set cataloged before the latest data set.
Rule: If DISP (disposition) is DELETE to make room for other data sets and no generation data group exists, the job will complete indicating a deleted generation name (G0000V00). If a generation data group exists but is not in the range specified for deletion, the step will fail.
Positive number—specifies a data set not yet cataloged in the generation data group.

Using zero or a negative number as the relative generation number places a volume list (or a volume control block) in your output area and replaces the relative generation number with the absolute generation name.

Using a positive number as the relative generation number creates an absolute generation name and replaces the relative generation number. Because there are no entries in the catalog, zeros are read into the first 256 bytes of your output area.

The format for the LOCATE and CAMLST NAME macros is:


>>-+-------+--LOCATE--list_addrx-------------------------------><
   '-label-'


>>-listname--CAMLST--NAME--,dsname_relexp--,area_relexp--------><

list_addrx: Points to the parameter list (labeled listname) set up by the CAMLST macro instruction.
NAME: To read a block from the catalog by generation data set name, code this operand as shown.
dsname_relexp: Specifies the virtual storage location of the name of the generation index and the relative generation number. The area that contains these must be 44 bytes long.
area_relexp: Specifies the virtual storage location of your 265-byte output area, which you must define. The output area must begin on a doubleword boundary. The output area will contain a volume list that is built from the catalog. If the data set resides on one volume, bytes 252 - 254 can contain the relative track address of the DSCB. This address is relative to the beginning of the volume.