OSREQ activity subtypes 1–10 data section format

The format of the subtype data section for all OSREQ macro functions is identical; although, not all of the fields are applicable to all OSREQ functions. Also, with the exception of the OSREQ return code (ST1RC), the rest of the fields are not valid if the OSREQ function fails. The following are subtypes and descriptions for the functions of the OSREQ macro:
1
OSREQ ACCESS
2
OSREQ STORE
3
OSREQ RETRIEVE
4
OSREQ QUERY
5
OSREQ CHANGE
6
OSREQ DELETE
7
OSREQ UNACCESS
8
OSREQ STOREBEG
9
OSREQ STOREPRT
10
OSREQ STOREEND

Table 1 shows the format of the subtype data section for all OSREQ functions (subtypes 1–10):

Table 1. OSREQ activity subtypes 1-10 data section format
Offsets Name Length Format Description
0 0 ST1COLN 44 EBCDIC Collection name. Valid for subtypes 2, 3, 4, 5, 6, 8, 9, and 10.
44 2C ST1OBJN 44 EBCDIC Object name. Valid for subtypes 2, 3, 4, 5, 6, 8, 9, and 10.
88 58 ST1SGN 8 EBCDIC Storage group name. Valid for subtypes 2, 3, 4, 5, 6, 8, 9, and 10.
96 60 ST1SCN 8 EBCDIC Storage class name. Valid for subtypes 2, 4, 5, 8, 9, and 10.
104 68 ST1MCN 8 EBCDIC Management class name. Valid for subtypes 2, 4, 5, 8, 9, and 10.
112 70 ST1OFF 4 binary Offset for both partial object retrieve (subtype 3), and object store part (subtype 9). Zero for all others.
116 74 ST1LEN 4 binary Length. Valid for subtypes 2, 3, 4, 6, 8, 9, and 10.
SUBTYPE
Meaning
1
Unused, contains binary zero.
2
Length of object stored.
3
Number of bytes retrieved.
4
Number of QEL elements returned to the application program.
5
Unused, contains binary zero.
6
Length of object deleted.
7
Unused, contains binary zero.
8
Total object length in bytes.
9
Length in bytes of the part of the object to be stored.
10
Total object length in bytes to complete storage of the object.
120 78 ST1TTOK 16 binary OSREQ tracking token supplied with TTOKEN keyword on the OSREQ macro.
Note: Any application programs that want to use the new TTOKEN keyword interface need to be recompiled with the new OSREQ macro. For more information concerning the TTOKEN keyword, see Table 1 and z/OS DFSMS OAM Application Programmer's Reference.
136 88 ST1TOK 8 binary OSREQ token.
144 90 ST1VSN 6 EBCDIC Volume serial number. Valid for subtypes 2, 3, and 6.

For an OSREQ STORE request (subtype 2), this field contains the volume serial number of the tape or optical volume to which the primary copy of the object was stored. Only valid if bit 1 or 2 is on in field ST2FLGS.

For an OSREQ RETRIEVE request (subtype 3), this field contains the volume serial number of the tape or optical volume from which the copy of the object was retrieved. Either the first or the second backup copy is retrieved as determined by the VIEW=BACKUP | BACKUP2 option indicated on the RETRIEVE request. Valid if bit 1, 2, 3, 4, 5, or 6 is on in field ST3FLGS.

For an OSREQ DELETE request (subtype 6), this field contains the volume serial number of the tape or optical volume from which the primary copy of the object was deleted. Valid if bit 1 or 2 is on in field ST6FLGS.
150 96 ST1VMT 2 EBCDIC Volume media type. Valid for subtype 2, 3, and 6. If a volume serial number is contained in the previous field (ST1VSN), this field contains the media type of the volume whose volume serial number is in field ST1VSN as follows:
Value
Meaning
01
IBM 3995 5.25-inch 650-MB rewritable optical disk media.
02
IBM 3480 Cartridge System Tape.
03
IBM 3995 5.25-inch 650-MB WORM optical disk media.
04
IBM 3480 Enhanced Capacity Cartridge System Tape.
05
IBM High Performance Cartridge Tape.
06
IBM Extended High Performance Cartridge Tape.
07
IBM Enterprise Tape Cartridge.
08
IBM Enterprise WORM Tape Cartridge.
09
IBM Enterprise Economy Tape Cartridge.
10
IBM Enterprise Economy WORM Tape Cartridge.
11
IBM 3995 5.25-inch 1300-MB rewritable optical disk media.
12
IBM Enterprise Extended Tape Cartridge.
13
IBM 3995 5.25-inch 1300-MB WORM optical disk media.
14
IBM Enterprise Extended WORM Tape Cartridge.
15
IBM 3995 5.25-inch 1300-MB CCW optical disk media.
21
IBM 3995 5.25-inch 2600-MB rewritable optical disk media.
23
IBM 3995 5.25-inch 2600-MB WORM optical disk media.
25
IBM 3995 5.25-inch 2600-MB CCW optical disk media.
31
IBM 3995 5.25-inch 5.2-GB rewritable optical disk media.
33
IBM 3995 5.25-inch 5.2-GB WORM optical disk media.
35
IBM 3995 5.25-inch 5.2-GB CCW optical disk media.
Note: CCW = continuous composite WORM media. WORM = write-once-read-many.
152 98 ST1RC 4 binary OSREQ return code. Value in register 15 following the OSREQ macro invocation.
156 9C ST1RS 4 binary OSREQ reason code. Value in register 0 following the OSREQ macro invocation.
160 A0 ST1FLGS 4 binary Processing flags. The meaning is dependent on the record subtype. Unless specified below, all bits are zero and reserved. For subtype 1, the following bit definitions apply:
Bit
Meaning
0
When on, the IADDRESS parameter was specified on the OSREQ request.
1-31
Reserved
160 A0 ST2FLGS 4 binary Processing flags. The meaning is dependent on the record subtype. Unless specified below, all bits are zero and reserved. For subtype 2, the following bit definitions apply:
Bit
Meaning
0
When on, the object is stored to disk.
1
When on, the object is stored to optical.
2
When on, the object is stored to tape.
3
Unused.
4
Unused.
5
When on, the OSREQ STORE request resulted in the mounting of a shelf-resident removable media volume (tape or optical) by an operator. This bit is valid only if bit 1 or 2 is on.
6
When on, the OSREQ STORE request resulted in the mounting of a library-resident removable media volume (tape or optical) inside an automated storage library. This bit is valid only if bit 1 or 2 is on.
7
When on, the OSREQ STORE request was satisfied using an already mounted removable media volume (tape or optical). This bit is valid only if bit 1 or 2 is on.
8
When on, an immediate backup copy is scheduled for this object.
9
When on, the object is stored to LOB storage structure.
10
When on, the object is stored on a sublevel 1. When bit 0 is on, the object is stored in DB2. When bit 2 is on, the object is stored to a tape sublevel 1 volume.
11
When on, the object is stored on a sublevel 2. When bit 0 is on, the object is stored in a file system. When bit 2 is on, the object is stored to a tape sublevel 2 volume.
12
Unused
13
When on, the OSREQ STORE request included a DELHOLD=HOLD parameter. A deletion-hold was in effect for this object when it was initially stored.
       
Bit
Meaning
14
When on, the object was stored as a retention-protected object.
15
When on, the object was stored as a deletion-protected object.
16
When on, the object was stored as an event-based-retention object.
Start of change17End of change
Start of changeReserved.End of change
Start of change18End of change
Start of changeWhen on, a 64-bit virtual storage address was provided for the object data bufferEnd of change
160 A0 ST3FLGS 4 binary Processing flags. The meaning is dependent on the record subtype. Unless specified below all bits are zero and reserved. For subtype 3, the following bit definitions apply:
Bit
Meaning
0
When on, the primary copy of the object was retrieved from disk.
1
When on, the primary copy of the object was retrieved from optical.
2
When on, the primary copy of the object was retrieved from tape.
3
When on, either the first or the second backup copy of the object was retrieved from optical as a result of VIEW=BACKUP or VIEW=BACKUP2 being specified on the OSREQ macro. See bit 10 to indicate which backup copy was retrieved.
4
When on, either the first or the second backup copy of the object was retrieved from tape as a result of VIEW=BACKUP or VIEW=BACKUP2 being specified on the OSREQ macro. See bit 10 to indicate which backup copy was retrieved.
5
When on, either the first or the second backup copy of the object was retrieved from optical as a result of the primary copy of the object being unavailable and the automatic access to backup being active. See bit 10 for indication which backup copy was retrieved.
6
When on, either the first or the second backup copy of the object was retrieved from tape as a result of the primary copy of the object being unavailable and the automatic access to backup being active. See bit 10 for indication which backup copy was retrieved.
7
When on, the OSREQ RETRIEVE request resulted in the mounting of a shelf-resident removable media volume (tape or optical) by an operator. This bit is valid only if bit 1, 2, 3, 4, 5, or 6 is on.
8
When on, the OSREQ RETRIEVE request resulted in the mounting of a library-resident removable media volume (tape or optical) inside an automated storage library. This bit is valid only if bit 1, 2, 3, 4, 5, or 6 is on.
9
When on, the OSREQ RETRIEVE request was satisfied using an already mounted removable media volume (tape or optical). This bit is valid only if bit 1, 2, 3, 4, 5, or 6 is on.
10
When on, the second backup copy of the object was retrieved.
11
When on, a recall is scheduled for this object.
12
When on, a recall was explicitly specified on the OSREQ RETRIEVE request.
13
When on, the primary copy of the object was retrieved from a LOB table.
       
14
When on, the object is retrieved from a sublevel 1. When bit 0 is on, the object is retrieved from DB2. When bit 2 is on, the object is retrieved from a tape sublevel 1 volume.
15
When on, the object is retrieved from a sublevel 2. When bit 0 is on, the object is retrieved from a file system. When bit 2 is on, the object is retrieved from a tape sublevel 2 volume.
Start of change16End of change
Start of changeReserved.End of change
Start of change17End of change
Start of changeWhen on, a 64-bit virtual storage address was provided for the object data bufferEnd of change
160 A0 ST4FLGS 4 binary Processing flags. The meaning is dependent on the record subtype. Unless specified below, all bits are zero and reserved. For subtype 4, the following bit definitions apply:
Bit
Meaning
0
When on, the QUERY BACKUP OPTION has been disabled by specifying QB=N in the IEFSSNxx PARMLIB member. When off, the QUERY BACKUP OPTION is enabled, either by default or by specifying QB=Y in the IEFSSNxx PARMLIB member.
1-31
Reserved.
160 A0 ST5FLGS 4 binary Processing flags. The meaning is dependent on the record subtype. Unless specified below, all bits are zero and reserved. For subtype 5, the following bit definitions apply:
Bit
Meaning
0
When on, management class is specified on the OSREQ CHANGE macro.
1
When on, storage class is specified on the OSREQ CHANGE macro.
2
When on, retention period is specified on the OSREQ CHANGE macro.
3
When on, special retention period value of -1 is specified the OSREQ CHANGE macro.
4
When on, special retention period value of -2 is specified the OSREQ CHANGE macro.
5
When on, special retention period value of X'7FFFFFFF' is specified the OSREQ CHANGE macro.
6
When on, event expiration (EVENTEXP) is specified on the OSREQ CHANGE macro.
7
When on, activate deletion hold (DELHOLD=HOLD) is specified on the OSREQ CHANGE macro.
8
When on, release deletion hold (DELHOLD=NOHOLD) is specified on the OSREQ CHANGE macro.
160 A0 ST6FLGS 4 binary Processing flags. The meaning is dependent on the record subtype. Unless specified below, all bits are zero and reserved. For subtype 6, the following bit definitions apply:
Bit
Meaning
0
When on, the primary copy of the object is deleted from disk.
1
When on, the primary copy of the object is deleted from optical.
2
When on, the primary copy of the object is deleted from tape.
3
When on, the first backup copy of the object is deleted from optical.
4
When on, the first backup copy of the object is deleted from tape.
5
When on, the second backup copy of the object is deleted from optical.
6
When on, the second backup copy of the object is deleted from tape.
7
When on, the primary copy of the object is deleted from LOB table.
8
When on, the primary copy of the object is deleted from sublevel 1. When bit 0 is on, the object is deleted from DB2. When bit 2 is on, the object is deleted from a tape sublevel 1 volume.
9
When on, the primary copy of object is deleted from sublevel 2. When bit 0 is on, the object is deleted from a file system. When bit 2 is on, the object is deleted from a tape sublevel 2 volume.
Start of change10End of change
Start of changeReserved.End of change
160 A0 ST7FLGS 4 binary Processing flags. For subtype 7, all bits contain zero.
160 A0 ST8FLGS 4 binary Processing flags. For subtype 8, all bits contain zero.
160 A0 ST9FLGS 4 binary Processing flags. For subtype 9, all bits contain zero.
160 A0 ST10FLGS 4 binary Processing flags. The meaning is dependent on the record subtype. Unless specified below, all bits are zero and reserved. For subtype 10, the following bit definitions apply:
Bit
Meaning
0
When on, the object is stored to disk.
1
Unused.
2
When on, the object is stored to tape.
3
Unused.
4
Unused.
5
When on, the OSREQ STORE request resulted in the mounting of a shelf-resident tape volume by an operator (this could also be a non-IBM tape library). This bit is valid only if bit 2 is on.
6
When on, the OSREQ STORE request resulted in the mounting of a library-resident tape volume inside an IBM automated tape library. This bit is valid only if bit 2 is on.
7
When on, the OSREQ STORE request was satisfied using an already mounted tape volume. This bit is valid only if bit 2 is on.
8
When on, an immediate backup copy is scheduled for this object.
9
When on, the object is stored to LOB storage structure.
10
When on, the object is stored on a sublevel 1. When bit 0 is on, the object is stored in DB2. When bit 2 is on, the object is stored to a tape sublevel 1 volume.
11
When on, the object is stored on a sublevel 2. When bit 0 is on, the object is stored in a file system. When bit 2 is on, the object is stored to a tape sublevel 2 volume.
12
When on, the CANCEL=YES keyword was specified indicating the store sequence was successfully cancelled.
13
When on, the OSREQ STOREBEG request included a DELHOLD=HOLD parameter. A deletion-hold was in effect for this object when it was initially stored.
14
When on, the object was stored as a retention-protected object.
15
When on, the object was stored as a deletion-protected object.
16
When on, the object was stored as an event-based-retention object.
Start of change17End of change
Start of changeReserved.End of change
164 A4 ST1STOK 16 binary OSREQ STOKEN. Valid for subtypes 8, 9, and 10.
180 B4 ST1RC2 4 binary OSREQ Return Code 2. Valid for subtypes 2, 3, and 10.
184 B8 ST1STOUT 4 binary STIMEOUT value specified on the STOREBEG request. Specifies the maximum interval in seconds between STOREBEG, STOREPRT, and STOREEND request that OAM should wait before OAM will assume that there will be no more activity for this store sequence. Valid for subtype 8.
188 BC ST1OLRD 10 EBCDIC Old Last Reference Date. Value contained in OLDREFDT prior to the OSREQ CHANGE or RETRIEVE request. Valid for subtypes 3 and 5.
198 C6 ST1NLRD 10 EBCDIC New Last Reference Date. Value contained in ODLREFDT after the OSREQ CHANGE or RETRIEVE request has completed. Valid for subtypes 3 and 5.
208 D0 ST1INST 4 binary Instance ID. Valid for subtypes 2,3,6, and 10.

Although subtypes 1–10 share a common subtype data section, not all fields are valid for each of the ten subtypes. Table 2 identifies which fields in the OAM subtype data section are valid for each of the ten OSREQ subtypes:

Table 2. Valid subtype data section fields for OSREQ functions
Field name OSREQ ACCESS Subtype 1 OSREQ STORE Subtype 2 OSREQ RETRIEVE Subtype 3 OSREQ QUERY Subtype 4 OSREQ CHANGE Subtype 5 OSREQ DELETE Subtype 6 OSREQ UNACCESS Subtype 7 OSREQ STOREBEG Subtype 8 OSREQ STOREPRT Subtype 9 OSREQ STOREEND Subtype 10
ST1COLN   X X X X X   X X X
ST1OBJN   X X X X X   X X X
ST1SGN   X X X X X   X X X
ST1SCN   X   X X     X X X
ST1MCN   X   X X     X X X
ST1OFF     X           X  
ST1LEN   X X X   X   X X X
ST1TTOK                    
ST1TOK                    
ST1VSN   X X     X        
ST1VMT   X X     X        
ST1RC X X X X X X X      
ST1RS X X X X X X X      
ST1FLGS X     X            
ST1STOK               X X X
ST1RC2   X X             X
ST1STOUT               X    
ST1OLRD     X   X          
ST1NLRD     X   X          
ST2FLGS   X                
ST3FLGS     X              
ST4FLGS       X            
ST5FLGS         X          
ST6FLGS           X        
ST7FLGS             X      
ST8FLGS               X    
ST9FLGS                 X  
ST10FLGS                   X
Parent topic: OAM System Management Facility records