The STOW macro updates a partitioned data set directory or PDSE directory by adding, changing, replacing, or deleting an entry in the directory. You can use the STOW macro to add, replace, or delete an entry for a generation of a member. You can also use the STOW macro to clear a partitioned data set or PDSE directory. You can update only one entry at a time using the STOW macro. If the data set is open for output and the entry to be added is a member name (not an alias), the system writes an end-of-data indication following the member. If the data set is open for update, the entry to be replaced is updated in the directory; no end-of-file record is written. You must position to the member using the POINT or FIND macro before issuing the STOW macro. Your program must test all output operations for completion using the same data control block before issuing the STOW macro.
You can use the STOW macro only when the data set is opened for OUTPUT, UPDAT, or OUTIN. See z/OS DFSMS Using Data Sets for more information on using the STOW macros.
If the data set is a PDSE, the CHECK macro can complete before all of the data is on DASD. The STOW macro ensures that all of the member data has been written to DASD.
For PDSEs, the STOW macro synchronizes data to DASD.
For program object PDSEs, you can use only the change, delete, and initialize functions. You cannot specify the add and replace functions for program object PDSEs.
You can use the STOW macro to disconnect a member of a PDSE. (Member connections are established by the OPEN, BLDL, FIND, and POINT macros. Refer to z/OS DFSMS Using Data Sets for information on PDSE connections.) This action is indicated by the DISC directory action. If the DISC directory action is specified, the DCB may be open for INPUT, OUTPUT, UPDAT, or OUTIN.
All addresses for the STOW must be 24-bit addresses.
The format of the STOW macro is:
| [label] |
STOW |
dcb address |
- dcb address—RX-Type Address, (2-12), or (1)
- specifies the address of the open DCB that caused the connections to be established. The DCB may be open for input.
- list address—RX-Type Address, (2-12), or (0)
- specifies the address of the area containing the information that is required by the system to
maintain the partitioned data set directory. The size and format of the area depend on the
directory action requested as follows:
Adding or Replacing a Directory Entry: STOW dcb,area,A|R
The list address must specify an area at least 12 bytes long and beginning on a halfword boundary. The following illustration shows the format of the area:
- NAME:
- Specifies the member name or alias being added or replaced. The name must begin in the first byte of the field and be padded on the right with blanks, if necessary, to complete the 8-byte field.
- TT:
- Specifies the relative track number where the beginning of the member is located.
- R:
- Specifies the relative block (record) number on the track identified by
TT. Recommendations:
- The TTR fields shown above must be supplied by the problem program if an alias is being added or replaced (alias bit is 1). For a PDSE, the TTR field is a token that does not represent the physical location of the member in the data set. For a PDSE, the TTR in an alias directory entry must be the starting TTR of a member already in the directory.
- Alias directory entries in a PDSE must point to the beginning of a member.
The system supplies the TTR fields when a member name is being added or replaced. Issue the FIND macro to locate the member before using STOW to replace it.
- C:
- Specifies the type of entry (member or alias) for the name, the number of note
list fields (TTRNs), and the length in halfwords, of the user data field. The
following describes the meaning of the 8 bits:
- Bit
- Meaning
- 0=0
- Indicates a member name.
- 0=1
- Indicates an alias.
- 1 and 2
- Indicate the number of TTRN fields (maximum of 3) in your data field.
- 3-7
- Indicate the total number of halfwords in the user data field.
- USER DATA FIELD:
- The user data field contains the user data for the directory entry. You can use the user data field to provide variable data as input to the STOW macro; there is no specific format for user data.
Note:- Note lists are not allowed for PDSEs, and will result in an error return code from STOW.
- The replaced version of a member of a PDSE remains accessible using FIND by TTR or the POINT macro until all connections to it are released. Connections are released when the PDSE is closed.
Replacing a Generation: The list address must be of a 12-byte area. The first 8 bytes are the member name, followed by the 4-byte generation number.
Deleting a Directory Entry: The list address must specify an 8-byte area containing the member name or alias to be deleted. The name must begin in the first byte of the area and be padded on the right with blanks, if necessary, to complete the 8 bytes.
When a member of a PDSE is deleted, it remains accessible using FIND by TTR or the POINT macro until all connections to it are released. Connections are released when the PDSE is closed.
Changing the Name of a Member: The list address must specify the address of a 16-byte area. The first 8 bytes contain the old member name or alias, and the second 8 bytes contain the new member name or alias. Both names must begin in the first byte of their 8-byte area and be padded on the right with blanks, if necessary, to complete the 8-byte field.
Initializing the Directory: Omit the list address when the directory action is "I". If the list address is specified, it will be ignored.
Disconnecting a List of Members: Each entry in the list address includes a three byte MLT, a one byte concatenation number, and a one byte status field. The MLT and the concatenation number may have been obtained from a prior BLDL (the fields PDS2TTRP and PDS2CNCT of the directory entry define the respective values). Table 1 defines the structure of the list:Table 1. Member List Structure Offset Length Description X'00' 2 Length of list (from offset 0) X'02' 1 Flags X'80' indicates DISC (set by STOW macro) X'03' 2 Reserved. Must be X'0000'. X'05' 3 DCB address X'08' 0 Beginning of array of entries to be disconnected. The number of entries is determined from length. X'08' 1 Status field: - X'00'
- Member disconnected
- X'01'
- Member not previously connected
- X'02'
- Member represents a partitioned data set
- X'03'
- Bad concatenation number
X'09' 1 Reserved. Must be X'00'. X'0A' 3 MLT X'0D' 1 Concatenation number - directory action—[A|C|D|I|R|DISC|IFF|RG|DG|RECOVERG]
- If directory action is not coded, A (add an
entry) is the default. The parameter is coded as shown to specify the type of directory
action. IFF, RG, DG and RECOVERG can only be issued against a PDSE.
- A
- specifies that an entry is to be added to the directory.
- C
- specifies that the name of an existing member or alias is to be changed.
- D
- specifies that an existing directory entry is to be deleted. For PDSEs, when the member name is deleted, all aliases for that member are deleted.
- I
- clears, or resets to empty, a PDS or PDSE directory. The parameter list (list address) is not required for STOW initialize. There are no serialization requirements for using STOW initialize. For PDSES, PDSE member connections will protect any application accessing a member concurrent to the issuance of STOW initialize. A member being read will be marked for deletion, but will not be deleted until after the connection is released.
- R
- specifies that an existing directory entry be replaced by a new directory entry. If R is coded but the old entry is not found, the new entry is added to the directory and a completion code of X'08' is returned in register 15. For PDSEs, when the member name is replaced, all aliases for that member are deleted. The replaced version of the PDSE member is marked for deletion, but it is not deleted until there are no applications accessing that member.
- DISC
- indicates the disconnect function is to be performed.
- IFF
-
If you specify the IFF function, the DCB must be open with the OUTPUT or UPDAT option on the OPEN macro. This function currently supports ONLY PDSE data members. To create a new PDSE data member with the new attributes type descriptor and CCSID - a Timestamp of ‘00000000’s needs to be specified on the compare operand. To create a new PDSE data member with new values for the type descriptor and CCSID attributes a valid matching Timestamp must be specified on the compare operand to match the Timestamp of the last updater that is on the disk.
Create or Update the Attributes of a Member: The list address can only have one entry and the entry must have x’40’ at offset ’02’ to indicate it is an IFF function. Table 2 defines the structure of the list.
Table 2. Member List Structure for IFF Offset Length Description X'00' 2 length of list X'02' 1 Flags - x'40' = STOW IFF X'03' 2 Reserved. X'05' 3 DCB address X'08' 8 compare operand (timestamp). X'10' 4 address of directory entry in PDS2 format Note: directory entry must indicate primary nameX'14' 16 TYPE DESCRIPTOR. X'24' 2 CCSID - RG
- Specifies that a generation for the member of a PDSE is to be replaced with the member being created. Adds the generation if it does not exist. When generation=0, then a normal replace is done by replacing the current (most recent) generation.
- DG
- Specifies that a generation for the PDSE is to be deleted. When generation=0, then a normal delete is done, except that the current member does not become the newest generation.
- RECOVERG
- Specifies an existing generation that the system will renumber so it becomes the
current generation.
Table 3 defines the structure of the list for RG, DG and RECOVERG.
Table 3. Member List Structure for RG, DG and RECOVERG Offset Length Description X'00' 2 Length of PLIST=20. Set by the user. X'02' 1 Function. Set by the macro expansion. X'20'=RG
X'10'=DG
X'08'=RECOVERGX'03' 1 Unused, must be zero. Set by the macro expansion. X'04' 4 DCB address. Set by the macro expansion. X'08' 8 Member name. Set by the user. X'10' 4 Generation number. Set by the user and returned by DESERV.