STOWM (BPAM)

Syntax:

STOWM(ddname[,member][,function][,{newname|ttr}]
     [,{userfield|vv}][,mm][,cdate][,mdate]
     [,mtime][,cl][,il][,ml][,muserid])

Arguments:

ddname

is the 1 to 8 character name that identifies the data set you want to process. This name needs to have been previously associated with the data set, either via the ALLOCATE command or JCL DD statement, and opened via the OPEN function.

member

is the 1 to 8 character name that identifies the member the directory entry of which you want to create or update.

The member argument is required for all values of function except 'I'

function

determines the type of processing required. The valid values are:

'A': adds a directory entry. The entry can be a primary entry or an alias (see ttr below). This is the default.
'C': changes a directory entry (see newname below).
'D': deletes a directory entry. This deletes the member. When deleting a primary entry for a member of a PDSE, all aliases are also deleted.
'I': initializes a PDSE directory (deletes all members). This function cannot be used with a PDS.
'R': replaces a directory entry. The entry can be a primary entry or an alias (see ttr below).

For PDSE data sets, any user that is connected to a member can still access their version until the connection is broken. That is, directory modifications by one user are invisible to other connected users until they disconnnect from the member and reconnect. See the Using Data Sets publication for your level of DFP or DFSMS for more information.

newname

is the 1 to 8 character new member name. This argument is used with the 'C' (change) function only.

ttr

is the 6 byte printable hexadecimal address (in TTR format) of the member for which you want to create (or replace) an alias. A member's TTR can be obtained from the FINDM, STOWM, and LISTM functions.

Note: This argument must be exactly 6 bytes long. The TTRs produced by LISTM, STOWM, and FINDM are in the proper format.

userfield

is 0 to 62 bytes of user-specified data. Any values may be used. The interface always forces this argument to be an even number of bytes. If you pass an odd number of bytes, a byte of binary zeros will be appended to the right. Also, if you pass more than the maximum number of bytes, the argument is truncated on the right. No error indication is given.

Note: If any arguments follow this argument, it is not interpreted as the user field. It will be interpreted as the ISPF version number (see next description).

vv

is the ISPF version number. Valid range: 0-99.

mm

is the ISPF modification number. Valid range: 0-99.

cdate

is the ISPF creation date. The only valid format is CCYY.DDD (e.g., 1997.050). Any syntactically valid date is accepted. See the examples below.

mdate

is the ISPF modification date. The only valid format is CCYY.DDD (e.g., 1997.050). Any syntactically valid date is accepted. See the examples below.

mtime

is the ISPF modification time. The only valid format is HH:MM:SS. Any syntactically valid time is accepted. See the examples below.

cl

is the ISPF current lines value. Valid range: 0-65535. The system does not verify that this value reflects the number of lines in the member.

il

is the ISPF initial lines value. Valid range: 0-65535. The system does not verify that this value is correct.

ml

is the ISPF modified lines value. Valid range: 0-65535. The system does not verify that this value is correct.

muserid

is the ISPF modification user ID. Any printable string 1-7 characters in length is acceptable.

Module Name:

SWXSTOWM

Service Description:

The STOWM function is used to maintain the directory of a PDS or PDSE data set. Directory entries (both primary and aliases) can be added, renamed, replaced, and deleted. A special function is provided for clearing the directories of PDSE data sets.

When it follows one or more PUT function calls, STOWM will complete all pending write operations for the member. If the data set is open for output, STOWM will write an end-of-file marker after the records of the member. If open for update, write operations are completed, but no end-of-file marker is written.

You may use STOWM only if the file is open for output or update. If the file is open for input, close and re-open it for output or update.

Notes:

STOWM will, in some cases, disconnect a user from a PDSE member version.
The 'I' function deletes all members of a PDSE. Be sure that you really want to do this before using 'I'.

Returned Information:

The STOWM function returns a string of information the format of which depends on the value of function:

If the 'A' or 'R' is specified, the return code and the system-derived TTR address of the member are returned in the string (blank-delimited, return code first).
For all other functions, only the return code is returned in the string.

If you CALL the STOWM function, the returned value is contained in the RESULT special variable.

After completion of a STOWM function call, the RC and REASON variables will contain return code information:

RC: Contains the BPAM STOW return code. An RC of zero means the operation was completed successfully. If you use the 'R' function and the member does not exist, a return code of 8 is returned, but the directory entry is added.
REASON: Contains the BPAM STOW reason code.

Examples:

Create a new member (with one record). The 'A' function is assumed:

call open 'bpam', 'outdd', 'output'
call put 'outdd', 'this is a record'
call stowm 'outdd', 'earl'
call close 'outdd'

Create an alias for a member:

call open 'bpam', 'iodd', 'update'
parse value findm('iodd','earl','u') with rc ttr .
call stowm 'iodd', 'cathi', 'a', ttr
call close 'iodd'

Rename a member:

call open 'bpam', 'iodd', 'update'
call stowm 'iodd', 'earl', 'c', 'josh'
call close 'iodd'

Replace a member's directory entry (the code translates all colons in the user field to periods):

call open 'bpam', 'iodd', 'update'
parse value findm('iodd','josh','u') with,
  rc ttr k z c usrfld
usrfld = translate(usrfld, '.', ':')
call stowm 'iodd', 'josh', 'r', , usrfld
call close 'iodd'

Delete a member (or alias):

call open 'bpam', 'outdd', 'output'
call stowm 'outdd', 'josh', 'd'
call close 'outdd'

Create a (empty) new member with ISPF statistics. This example shows how to create date and time strings in the proper format. Note how the date and time references are clustered on a single REXX clause. REXX guarantees that all date/time references on a clause are consistent.
```
call open 'bpam', 'outdd', 'output'
parse value date('s')||date('j')||time() with,
  year +4 . +6 day +3 ctime
cdate = year'.'day
call stowm 'outdd', 'earl', 'a', , 1, 1, cdate,,
  cdate, ctime, 0, 0, 0, userid()
call close 'outdd'
```

Delete all members of a PDSE:

call open 'bpam', 'outdd', 'output'
call stowm 'outdd', , 'i'
call close 'outdd'