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.

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:

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

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 name
X'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'=RECOVERG
X'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.