Tape Management Exit Program
| 1 | Exit description information | Input | Char(*) |
| 2 | Label information | Input | Char(*) |
| 3 | Operational information | Input | Char(*) |
| 4 | Control value information | Output | Char(*) |
QSYSINC Member Name: ETATAPMG
Exit Point Name: QIBM_QTA_TAPE_TMS
Exit Point Format Name: TMS00200
Threadsafe: No
The Tape Management exit program allows a tape management system to monitor and control the use of volumes and devices used by the operating system for most tape operations. The exit program is given control at certain points during tape and library processing.
Note: To use this exit program, you need the Media and Storage Extension feature of the IBM® i operating system.
The exit program is not given control when:
- The system is being installed
- The tape job is a dedicated service tools (DST) tape job
- The job is ending
The operating system handles the setup, calling, and response processing of the user exit program as specified through the registration facility. (For information about registering an exit point with the registration facility and adding an exit program to an exit point, see Registration Facility APIs. This exit point supports only one exit program.)
Authorities and Locks
None.
Required Parameter Group
- Exit description information
- INPUT; CHAR(*)
A description of the exit point. For a description of the format, see Format of Exit Description Information.
- Label information
- INPUT; CHAR(*)
The current volume label and the last header label or trailer label that was written or read. For a description of the format, see Format of Label Information.
- Operational information
- INPUT; CHAR(*)
Information about the tape operation at the time the exit program is called. For a description of the format, see Format of Operational Information.
- Control value information
- OUTPUT; CHAR(*)
Information to control the tape operation being performed. This format is set by the IBM i operating system and can be changed by the exit programs to control tape processing. For a description of the format, see Format of Control Value Information.
Format of Exit Description Information
The following table shows the format of the exit description information. For a description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of exit description information |
| 4 | 4 | CHAR(1) | Tape position exit type |
| 5 | 4 | CHAR(1) | Tape library device exit type |
Field Descriptions
Length of exit description information. The length, in bytes, of the exit description information.
Tape library device exit type. An identifier that indicates to the exit program the type of library processing occurring in the tape library device. The values are:
| 0 | Ignore Use the value specified in the tape position exit type field. |
| 1 | Addition This exit type occurs immediately after the cartridge identifier is added to a tape library device using the Add Tape Cartridge (ADDTAPCTG) command. |
| 2 | Removal This exit type occurs immediately before the cartridge identifier is removed from a tape library device using the Remove Tape Cartridge (RMVTAPCTG) command. |
| 3 | Category This exit type occurs immediately before the cartridge identifier has its category changed from one category to another using the Change Tape Cartridge (CHGTAPCTG) command. |
| 4 | Mismatch This exit type occurs whenever a mismatch is found between a cartridge identifier and the volume identifier on the tape cartridge. |
| 5 | Mount failure This exit type occurs when a cartridge failed to be mounted. It gives the tape management program an opportunity to choose a different cartridge. |
| 6 | Unload exit This exit type occurs after taking the option reject and unload. It gives the tape management program an opportunity to choose the next cartridge to be mounted. |
| 7 | Mount category exit This exit type occurs before a category is mounted through the use of the Set Tape Category (SETTAPCGY) command with *MOUNTED specified for the option parameter. This exit type allows the tape management program the opportunity to reject the SETTAPCGY command. |
| 8 | Demount category exit This exit type occurs before a category is demounted through the use of the Set Tape Category (SETTAPCGY) command with *DEMOUNTED specified for the option parameter. This exit type allows the tape management program the opportunity to reject the SETTAPCGY command. |
| 9 | Inventory success exit This exit type occurs after a successful inventory has been received from the tape library device. |
Tape position exit type. An identifier that indicates to the exit program a reference to or the position of the tape. The values are:
| 0 | Ignore Use the value specified in the tape library device exit type field. |
| 1 | Start of file (SOF) This exit type occurs late in the open tape file processing but before any steps related to mounting the first tape volume. This exit type provides information concerning the open processing and allows the exit program to select the first tape volume that will be read from or written to. |
| 2 | Start of volume (SOV) This exit type occurs immediately after the volume label is read unless an initialize operation is being done. The purpose is to enable acceptance or rejection of a tape volume and to allow the exit program to record the volume actually used. This exit type occurs once for each volume processed. When an initialize operation is being done, this exit type occurs before the volume label is written. The current volume identifier (if known) is the volume identifier before the initialize operation and the next volume identifier is the new volume identifier. |
| 3 | Start of file section (SOS) This exit type occurs immediately after the HDR2 file header label is read on input or immediately before the HDR2 label is written on output. Its purpose is to enable acceptance or rejection of a tape that was previously accepted at start-of-volume exit type. This exit type occurs once for each file processed. |
| 4 | End of file section (EOS) This exit type occurs immediately after the EOV2 end-of-volume label is read on input or immediately after the EOV2 label is written on output. This exit type allows the exit program to select the next tape volume to be read from or written to. This exit type occurs once for each volume processed except for the last volume. (This exit type does not occur for single volume processes.) |
| 5 | End of file (EOF) This exit type occurs immediately after the EOF2 end-of-file label has been read on input or immediately after the EOF2 label is written on output. Its purpose is to inform the exit program that tape processing is complete. |
| 6 | Message This exit type occurs immediately before a message is sent by the tape manager. The exit type informs the exit program that a message will be sent. If the message is an inquiry message, the valid responses accepted by the message handler may be the same as those that the IBM i program accepts from the tape management system. |
| 7 | End position This exit type occurs immediately before an end positioning occurs. End positioning refers to whether the tape is rewound, unloaded, or left in leave processing. (Leave processing refers to the use of ENDOPT(*LEAVE) on a tape command.) The exit type is driven by the End Option (ENDOPT) parameter on all tape commands. These values could be ENDOPT(*LEAVE), ENDOPT(*REWIND), or ENDOPT(*UNLOAD). User-specified values cannot be overridden in error scenarios because tape volumes are always rewound in error situations. |
| 8 | Command exit This exit type occurs before the start-of-file exit type and is designed to allow tape management systems the ability to choose values that need to be known before any operation is performed on the tape device. It is only enabled as an exit type when options can be changed. |
Examples of Exit Calls
This example shows the sequence and the tape position exit types that result from saving a library object (SAVLIB command) to one tape:
- Command (CMD)
- Start of file (SOF)
- Start of volume (SOV)
- Start of file section (SOS)
After this exit type, the data file is written.
- End of file (EOF)
- End position
This example shows the sequence and the tape position exit types that result from saving one library object to two tapes:
- Start of command (CMD)
- Start of file (SOF)
- Start of volume (SOV)
- Start of file section (SOS)
After this exit type, the first part of the data file is written.
- End of file section (EOS)
After this exit type, a new tape volume is requested.
- Start of volume (SOV)
- Start of file section (SOS)
After this exit type, the next part of the data file is written to the second tape.
- End of file (EOF)
- End position
This example shows the sequence and tape position exit types that result from using the DSPTAP DATA(*SAVRST) command.
- Start of file (SOF)
- Start of volume (SOV)
- Start of file section (SOS). A keystore file and record label can be specified at this exit to allow the object summary to be displayed.
- End position
Format of Label Information
The following table shows the format of the label information. For a description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of label information |
| 4 | 4 | CHAR(80) | Current volume label |
| 84 | 54 | CHAR(80) | Last processed HDR1 or TRL1 label |
| 164 | A4 | CHAR(80) | Last processed HDR2 or TRL2 label |
Field Descriptions
Current volume label. The volume label currently being processed. If the tape position exit type is SOF or if the tape library device exit type is addition, removal, category, or mismatch, this field contains blanks. This field also contains blanks if a nonlabeled tape is being processed.
Last processed HDR1 or TRL1 label. The HDR1 file header label or TRL1 trailer label that was last encountered. If the tape position exit type is SOF or SOV or if the tape library device exit type is addition, removal, category, or mismatch, this field contains blanks. This field also contains blanks if a nonlabeled tape is being processed.
Last processed HDR2 or TRL2 label. The HDR2 file header label or TRL2 trailer label that was last encountered. If the tape position exit type is SOF or SOV or if the tape library device exit type is addition, removal, category, or mismatch, this field contains blanks. This field also contains blanks if a nonlabeled tape is being processed.
Length of label information. The length, in bytes, of the label information.
Format of Operational Information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of operation information |
| 4 | 4 | BINARY(4) | Length of control value information |
| 8 | 8 | CHAR(1) | Tape operation |
| 9 | 9 | CHAR(17) | Data file label |
| 26 | 1A | CHAR(10) | Tape device file name |
| 36 | 24 | CHAR(10) | Tape device file library name |
| 46 | 2E | CHAR(10) | Current device name |
| 56 | 38 | CHAR(6) | Current volume identifier |
| 62 | 3E | CHAR(10) | Next device name |
| 72 | 48 | CHAR(6) | Next volume identifier |
| 78 | 4E | CHAR(4) | Current device type |
| 82 | 52 | CHAR(10) | Current tape density |
| 92 | 5C | CHAR(1) | Data check on write |
| 93 | 5D | CHAR(10) | Next tape density |
| 103 | 67 | CHAR(1) | Tape device ready status |
| 104 | 68 | CHAR(1) | Tape volume initialize status |
| 105 | 69 | CHAR(1) | Initialize new volume label |
| 106 | 6A | CHAR(32) | Logical block identifier |
| 138 | 8A | CHAR(6) | Cartridge identifier |
| 144 | 90 | CHAR(10) | Category name |
| 154 | 9A | CHAR(8) | Category system name |
| 162 | A2 | CHAR(1) | Mismatch status |
| 163 | A3 | CHAR(10) | Library device name |
| 173 | AD | CHAR(1) | Library device status |
| 174 | AE | CHAR(1) | Library device mode |
| 175 | AF | CHAR(1) | System restricted state status |
| 176 | B0 | CHAR(1) | Tape volume write protection status |
| 177 | B1 | CHAR(7) | Message identifier |
| 184 | B8 | CHAR(10) | Message type |
| 194 | C2 | CHAR(10) | Message queue or program name |
| 204 | CC | CHAR(10) | Message queue or program library name |
| 214 | D6 | CHAR(4) | Message destination |
| 218 | DA | CHAR(1) | Volume list status |
| 219 | DB | BINARY(4) | Offset of replacement text |
| 223 | DF | BINARY(4) | Length of replacement text |
| 227 | E3 | CHAR(1) | Generated cartridge ID status |
| 228 | E4 | CHAR(1) | Sequence number change allowed |
| 229 | E5 | CHAR(1) | End position |
| 230 | E6 | CHAR(10) | File sequence number |
| 240 | F0 | CHAR(10) | Aggregate volume sequence number |
| 250 | FA | CHAR(10) | Media library tape resource name |
| 260 | 104 | CHAR(4) | Media library tape resource type |
| 264 | 108 | CHAR(4) | Media library tape resource model |
| 268 | 10C | CHAR(1) | Generated cartridge identifier |
| 269 | 10D | CHAR(10) | Session identifier |
| 279 | 117 | CHAR(150) | Cartridge densities |
| 429 | 1AD | CHAR(26) | Qualified job name |
| 455 | 1C7 | CHAR(4) | Reserved |
| 459 | 1CB | CHAR(1) | Type of close operation |
| 460 | 1CC | CHAR(10) | Command name |
| 470 | 1D6 | CHAR(1) | Message recoverable flag |
| 471 | 1D7 | CHAR(1) | Output extend processing |
| 472 | 1D8 | CHAR(10) | User sequence number |
| 482 | 1E2 | CHAR(6) | User expiration date |
| 488 | 1E8 | CHAR(1) | Virtual device |
| 489 | 1E9 | CHAR(1) | WORM cartridge |
| 490 | 1EA | CHAR(6) | Target Release |
| * | * | CHAR(*) | Message replacement text (The offset to this field is stored in the Offset of replacement text field) |
Field Descriptions
Aggregate volume sequence number. The aggregate volume sequence number from the label information. The numeric value is right-justified with leading zeros or blanks.
Cartridge densities. The densities that are supported by the cartridge. Up to 15 densities or formats are supported by the cartridge. Each density or format is 10 characters in length. For example, if only one density exists, the first 10 bytes of this field are the character representation of the density or format and the last 140 bytes are blanks. This field is set at the start-of-volume exit type and is blank at all other exit types. This field is blank for devices or cartridges that do not support special cartridge-checking capabilities.
Cartridge identifier. The cartridge identifier of the tape cartridge. If the tape library device has a scanner, the cartridge identifier is the external bar-code identifier. If the tape library device does not have a scanner, the cartridge identifier is the logical volume identifier. This field is blank if the device is not in a tape library device or when the tape position exit type field is SOF.
Category name. The category name that the cartridge identifier is being changed to. This field is blank if the tape library device exit type field is not addition or category.
Category system name. The category system name that is the primary owner of the category name. This field is blank when the category is *INSERT, *EJECT, or *SHARE400.
Command name. The name of the command being run. If this field is blanks, then the command does not support passing the command name to the Media and Storage Extension structures at this exit point. Check Tape (CHKTAP), Duplicate Tape (DUPTAP), and Initialize Tape (INZTAP) commands pass the command name for all exit types.
Current device name. The name of the tape device being used at the time the exit point is reached. This field is blank if the tape library device exit type field is addition, removal, or category.
Current device type. The device type of the current tape device. This field is blank if the tape library device exit type field is addition, removal, or category.
Current tape density. The density of the tape reel or cartridge on the current tape device. This field is blank if the tape library device exit type field is addition, removal, or category.
Current volume identifier. The name of the expected volume to be used during the tape operation, not necessarily the loaded volume. IBM i issues an inquiry message when the expected volume is different from the loaded volume. This field is blank if the tape library device exit type field is addition, removal, or category.
Data check on write. Whether a permanent write data check occurred. Valid values are:
| 0 | A permanent write data check has not occurred. |
| 1 | A permanent write data check occurred and end-of-volume labels are being written before the end of tape. |
Data file label. The tape data file being processed. This field is blank if the tape library device exit type field is addition, removal, or category.
End position. The type of end position that is occurring for this close operation. This exit type is designed for applications that track the end positioning of cartridges. It becomes important for media library devices where *LEAVE ties up a device for that cartridge being left in leave processing. This field is blank at all exit points other than the end position exit type. Valid values follow:
| 0 | *REWIND |
| 1 | *UNLOAD |
| 2 | *LEAVE |
File sequence number. The file sequence number from the label information.
Generated cartridge identifier. Whether the cartridge identifier is generated. Generated identifiers include BLKxxx (where xxx are the characters 0-9) for blank or new tapes, IMPxxx for tapes in the convenience (import) station, NLTxxx for nonstandard labeled tapes, CLNxxx for cleaning tapes, and ERRxxx for tape cartridges in error. This field is blank when no cartridge identifier is passed in the operational information format in the cartridge identifier field. Valid values follow:
| 0 | The cartridge identifier is not generated. |
| 1 | The cartridge identifier is generated. |
Generated cartridge ID status. Whether the media library device has a bar-code reader. If the media library device does not have a bar-code reader, then the field indicates if the cartridge identifiers are generated by the system or if the logical volume identifiers are used as the cartridge identifiers. This field is blank at all exit types except inventory success exit. Valid values follow:
| 0 | The media library device has a bar-code reader. |
| 1 | The media library device does not have a bar-code reader, and the logical volume identifiers will be used as the cartridge identifiers (that is, the device description has *VOLID specified for the GENCTGID parameter). |
| 2 | The media library device does not have a bar-code reader, and the system will generate the cartridge identifiers (that is, the device description has *SYSGEN for the GENCTGID parameter). |
Initialize new volume label. Whether a new volume label initializes immediately. This field is blank if the tape position exit type field is not SOV. Valid values are:
| 0 | An SOV tape position exit type after the volume label on tape is read |
| 1 | An SOV tape position exit type before the new volume label is written |
Length of control value information. The length, bytes, of the control value information.
Length of operational information. The length, in bytes, of the operational information.
Length of replacement text. The length, in bytes, of the replacement text for the message exit type.
Library device mode. Whether the library device is in library mode. Valid values are as follows:
| 0 | The library device is not in library mode. |
| 1 | The library device is in library mode. |
Library device name. The name of the tape library device being used at the time the exit point is reached. This field is blank if a tape library device is not being used.
Library device status. Whether the device is in a library device. Valid values are as follows:
| 0 | The tape device is not in a library device. |
| 1 | The tape device is in a library device. |
Logical block identifier. The current tape position. This refers to the logical position of the data buffer rather than the physical position of the media. This field is passed as part of the SOS tape position exit type for tapes that support positioning by logical block identifier on standard labeled (*SL) tapes opened for output. This field is zero at all other exit types.
Media library tape resource name. For a media library device, the resource name of the tape device being used. If no device is allocated to the process for use, the field is blank.
Media library tape resource model. The model number of the tape resource name.
Media library tape resource type. The type number of the tape resource name.
Message destination. The destination of the message to be signalled by the operating system in relation to the program name specified in the message queue or program name field. Valid values are as follows:
| PREV | The message is sent to the program previous to the one specified. |
| SAME | The message is sent to the program specified. |
Message identifier. The identifier of the message that is signalled.
Message queue or program name. The name of the message queue or program to which the message will be sent.
Message queue or program library name. The name of the library in which the message queue or program will reside.
Message recoverable flag. Indicates if the message is recoverable. This field is valid only for the message exit. It is blank for all other exit types. Valid values are as follows:
| 0 | The message is not recoverable. |
| 1 | The message is recoverable. |
Message replacement text. The replacement text for the message identifier on the message exit type. The offset to this field and the length of this field are also contained in the operational information format.
Message type. The type of message that will be signalled. Valid values are as follows:
| ESCP | Escape message |
| INQ | Inquiry message |
Mismatch status. Whether a mismatch occurred when using the Add Tape Cartridge (ADDTAPCTG) command. This field is blank if the tape library device exit type is not mismatch or if the device is not in a tape library device. Valid values are:
| 0 | A mismatch did not occur when using the command. |
| 1 | A mismatch occurred when using the command. |
Next device name. The next device name in the list of devices. If only one device has been specified, the current and next device names are the same. This field is blank if the tape library device exit type is addition, removal, or category.
Next tape density. The new density when a reel or cartridge is initialized. This field is blank if the tape library device exit type is addition, removal, or category.
Next volume identifier. The next volume label in the list of labels. Blanks indicate that the volume identifier list is used up. This field is blank if the tape library device exit type is addition, removal, or category.
Offset of replacement text. The offset, in bytes, of the replacement text for the message exit type.
Output extend processing. Indicates when a tape file is opened for output with extend processing. This flag will only be set when a tape file is opened for output. Valid values are:
| blank | The file is opened for input. |
| 0 | The file is opened for output. |
| 1 | The file is opened for output with extend processing. |
Qualified job name. The qualified job name that forced the tape function and exit types.
Reserved. An ignored field.
Session identifier. An identifier to the tape management system of the session identifier that is associated with this request. Each session in a media library device has its own unique session identifier. An exception is a mounted category request, which has a session identifier assigned from the SETTAPCGY OPTION(*MOUNTED) to SETTAPCGY OPTION(*DEMOUNTED); this session identifier is used for each command that specifies VOL(*MOUNTED) while a category is mounted. This field is set to blanks for stand alone devices.
Sequence number change allowed. Whether the tape management system is allowed to change the user-specified sequence number. Valid values follow:
| blank | No change to the user-specified sequence number value is allowed. |
| 0 | No change to the user-specified sequence number value is allowed because of the tape positioning or tape file status (that is, end of volume). |
| 1 | A change to the user-specified sequence number is allowed. Valid sequence numbers include 1, *END, or one greater than the last sequence number on the tape. This value is valid only for output operations. |
| 2 | A change to the user-specified sequence number is
allowed.
For output operations, the valid new sequence number values include 1, any existing sequence number, *END, or one greater than the last sequence number on the tape. For input operations, the valid new sequence number values include any existing sequence number. |
When a change is allowed, the user-specified sequence number is placed in both the sequence number and large sequence number fields of the control value information. Either the sequence number or large sequence number fields of the control value information may be changed to a new value by the tape management system.
Note: For user-specified sequence numbers greater than 999 999, the value will appear only in the large sequence number field.
Note: The tape management system is not allowed to change the user-specified sequence number for input operations for the CHKTAP, DMPTAP, DSPTAP, and DUPTAP commands.
System restricted state status. Whether the system is in restricted state. Valid values are as follows:
| 0 | The system is not in a restricted state. |
| 1 | The system is in a restricted state. |
Tape device file library name. The name of the library that contains the tape device file. This field is blank if the tape library device exit type is addition, removal, or category.
Tape device file name. The name of the tape device file for this tape device. This field is blank if the tape library device exit type is addition, removal, or category.
Tape device ready status. Whether the tape device is ready. Valid values are:
| 0 | The tape device is not ready |
| 1 | The tape device is ready |
Tape operation. An indicator of how the tape file was opened. Valid values are:
| 0 | The tape file is open for input. |
| 1 | The tape file is open for output. |
| 2 | No tape file is open. |
Tape volume initialize status. The identifier that determines the type of checking for active files during the initialize operation. This field is blank when it is not an initialize operation. Valid values are:
| 0 | Initialize operation and check for active file is *NO. |
| 1 | Initialize operation and check for active files is *YES. |
| 2 | Initialize operation and check for active files is *FIRST. |
Tape volume write protection status. Whether the tape volume in use is write-protected. Valid values are as follows:
| 0 | The tape volume is not write-protected. |
| 1 | The tape volume is write-protected. |
Target Release. The target release specified for a save operation. The format VxRxMx is used for the target release, where Vx is the version, Rx is the release, and Mx is the modification level. This field is blank if the target release is not applicable.
Type of close operation. The type of close operation. If the exit type is not an end-of-file exit type, the field is blank. Valid values follow:
| blank | Not an end-of-file exit type |
| 1 | Temporary close (save or restore operation closes between files) |
| 2 | Permanent close (operation has completed) |
| 3 | Normal termination (operation is being ended normally) |
| 4 | Abnormal termination (operation is being ended abnormally) |
User expiration date. The expiration date specified by the user when the tape file was opened.
This field uses the Julian format with a leading century digit. It is of the form CYYDDD, where C represents the thousands and hundreds of the year value (19 is blank, 20 is 0, and 21 is 1), YY represents the year (00-99), and DDD represents the day of the year (001-366). For example, 1 February 1972 is represented as ' 72032' and 1 February 2072 is represented as '072032'.
The value *PERM indicates that the tape file is a permanent tape file.
The user expiration date will be blanks when the file is open for input or if the expiration date is *NONE.
User sequence number. The sequence number specified by the user when the tape file was opened. The sequence number will be blank when a tape file is opened for accessing a tape device but no input/output operations are to be issued or no sequence number is specified. Valid values are:
| *FIRST | First sequence on the tape (only valid for input) |
| *NEXT | Next sequence on the tape (only valid for input) |
| *END | Append to end of the tape (only valid for output) |
| number | The specified sequence on the tape (valid for input and output) |
Virtual device. Indicates whether or not the device is a virtual device. Valid values are:
| 0 | The device is not a virtual device. |
| 1 | The device is a virtual device. |
Volume list status. Whether *MOUNTED is specified for the volume (VOL) parameter. This field is set at SOF and SOV. This field allows tape management to control the monitoring of the Set Tape Category (SETTAPCGY) command for occurrences of *MOUNTED specified for the VOL parameter. This field is blank if the tape processing exit type is not start of file (SOF) and not start of volume (SOV). Valid values are as follows:
| 0 | VOL(*MOUNTED) is not specified. |
| 1 | VOL(*MOUNTED) is specified. |
WORM cartridge Specifies whether the current cartridge is a write-once-read-many (WORM) cartridge or a read-write cartridge. This field is valid when the tape processing exit type is start of volume (SOV), start of file section (SOS), end of file section (EOS), or end of file (EOF). It will be blank for all other exit types. Valid values are as follows:
| 0 | The current cartridge is a read-write cartridge. |
| 1 | The current cartridge is a write-once-read-many cartridge. |
Format of Control Value Information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Volume acceptance |
| 1 | 1 | CHAR(6) | Volume to be used |
| 7 | 7 | CHAR(6) | File expiration date |
| 13 | D | CHAR(1) | Character code conversion |
| 14 | E | CHAR(1) | Allow ignore response |
| 15 | F | CHAR(1) | Issue active file messages |
| 16 | 10 | CHAR(1) | Issue mount next tape message |
| 17 | 11 | CHAR(32) | Logical block identifier |
| 49 | 31 | CHAR(1) | Allow category change |
| 50 | 32 | CHAR(1) | Allow removal |
| 51 | 33 | CHAR(1) | Mismatch acceptance |
| 52 | 34 | CHAR(1) | Automatic ADDTAPCTG |
| 53 | 35 | CHAR(1) | Message response |
| 54 | 36 | CHAR(1) | Allow mount category |
| 55 | 37 | CHAR(1) | Allow demount category |
| 56 | 38 | CHAR(6) | Sequence number |
| 62 | 3E | CHAR(10) | Category name |
| 72 | 48 | CHAR(8) | Category system name |
| 80 | 50 | CHAR(10) | Large sequence number |
| 90 | 5A | CHAR(1) | Allow logical block identifier support |
| 91 | 5B | CHAR(1) | Allow cartridge search |
| 92 | 5C | CHAR(1) | End position |
| 93 | 5D | CHAR(10) | Density or format |
| 103 | 67 | CHAR(1) | Use optimum block size |
| 104 | 68 | CHAR(1) | Duplicate file |
| 105 | 69 | CHAR(10) | Image catalog name |
| 115 | 73 | CHAR(1) | Suppress auto-generate of virtual tape volume |
| 116 | 74 | CHAR(20) | Encryption Keystore File |
| 136 | 88 | CHAR(32) | Encryption Record Label |
Field Descriptions
All of these control values have a default at the exit types in which the exit program can change them. For exit types that values cannot be changed, the values are set to blanks.
Allow cartridge search. Whether to allow cartridge searching for non-bar-code media library devices when the cartridge that is specified in the VOL parameter of a command is not found. If the system is allowed to use cartridge searching, the system loads tapes and searches for a logical volume identifier to match the requested volume. The cartridges that the system loads and searches are the cartridges with generated identifiers and unknown logical volume identifiers. Cartridges with generated identifiers such as NLTxxx (nonlabeled), BLKxxx (blank), or ERRxxx (error) are not used in cartridge searching by the system.
If cartridge searching is allowed, the system may load and unload the convenience station tape, which causes the tape to no longer be recognized by the device. This field can only be changed at the start-of-file exit type. At all other exit types, the default value is blank. Valid values follow:
| 0 | Disallow system cartridge searching |
| 1 | Allow system cartridge searching |
Allow category change. Whether to allow a change of category for the cartridge identifier. You can change this value when the tape library device exit type field is category. The default is 1 when the tape library device exit type is category. Valid values are:
| 0 | The category for the cartridge identifier cannot be changed. |
| 1 | The category for the cartridge identifier can be changed. |
Allow demount category. Whether to allow a demount category. You can change this value when the tape library device exit type field is demount category. The default is 1 when the tape library device exit type is demount category. Valid values are as follows:
| 0 | Disallow the demount category operation. |
| 1 | Allow the demount category operation. |
Allow ignore response. Whether to allow an ignore response to a mount message. If the field contains a value that is not valid, it is ignored and message CPF4067 is issued. You can change the value when the tape position exit type field is SOV. The default is 0 when the tape position exit type is SOV. Valid values are:
| 0 | An ignore response is allowed from the mount next tape messages. The ignore response is permitted as normal on the mount next tape messages. |
| 1 | An ignore response is not allowed from the mount next tape messages. |
Allow logical block identifier support. Whether to allow logical block identifier support for this device. If a tape management system responds at the start-of-file exit type, this value allows devices that do not support logical block identifiers to work with IBM i code. Devices that are emulating IBM i supported devices may not support logical block identifiers but still report because of emulation that the device does support it. Valid values follow:
| 0 | Disallow logical block identifier support. |
| 1 | Allow logical block identifier support. |
Allow mount category. Whether to allow a mount category. You can change this value when the tape library device exit type field is mount category. The default is 1 when the tape library device exit type is mount category. Valid values are as follows:
| 0 | Disallow the mount category operation. |
| 1 | Allow the mount category operation. |
Allow removal. Whether to allow the removal of the cartridge identifier. You can change the value when the tape library device exit type field is removal. The default is 1 when the tape library device exit type is removal. Valid values are:
| 0 | The cartridge identifier cannot be removed from the tape library device. |
| 1 | The cartridge identifier can be removed from the tape library device. |
Automatic ADDTAPCTG. Whether to allow the tape management system the ability to automatically add the cartridge to a usable category when the exit type field is mount failure and the cartridge is currently in the *INSERT category. (For more information about usable categories, see the Add Tape Cartridge (ADDTAPCTG) command.) You can change this value when the tape library device exit type field is mount failure. The default is 0 when the tape library device exit type is mount failure. Valid values are:
| 0 | The cartridge identifier is not added to a usable category. |
| 1 | The cartridge identifier is added to the *NOSHARE category, and the tape processing continues. |
| 2 | The cartridge identifier is added to the *SHARE400 category, and the tape processing continues. |
| 3 | The cartridge identifier is added to the *IPL category, and the tape processing continues. |
| 4 | The cartridge identifier is added to the *NL category, and the tape processing continues. |
| 5 | The cartridge identifier is added to the *CNV category, and the tape processing continues. |
| 6 | The cartridge identifier is added to the category name and to the category system name fields that are specified in the control value information format. |
Category name. If a valid category name and category system name are specified, the cartridge is changed to that category. This automatic Change Tape Cartridge (CHGTAPCTG) command does not force a change exit type and can only be specified for media library devices and at the start-of-volume exit type. If you specify option 6 for the automatic tape cartridge field at the mount failure exit type, this field is also allowed. The field is set to blanks at all other exits types. You cannot change to the system-supplied categories *CNV and *SYSGEN.
Category system name. If you specify a valid category name and category system name, the cartridge is changed to that category. This automatic Change Tape Cartridge (CHGTAPCTG) command does not force a change exit type and can only be specified for media library devices and at the start-of-volume exit type. If you specify option 6 for the automatic tape cartridge field at the mount failure exit type, this field is also allowed. The field is set to blanks at all other exit types. You cannot change to the system-supplied categories *CNV and *SYSGEN.
Character code conversion. Whether to convert character code from ASCII to EBCDIC for data written on the tape. If the field contains a value that is not valid, it is ignored and message CPF4067 is issued. You can change this value when the tape position exit type field is SOF and the tape operation field is 1. The default is 0 when the tape position exit type is SOF and the tape operation field is 1.
| 0 | Convert ASCII data to EBCDIC data when processing the data file |
| 1 | Retain ASCII data |
Density or format. This field allows the tape management system to change the density or format of the tape volume. When the initialize new volume label (operational information format) is set to 1, which indicates that the new tape volume is written immediately, the user-specified density at the start-of-volume exit type is used. The field must be set to one of the valid cartridge densities that are listed in the operational information format. The field is blank when it cannot be changed.
Duplicate File. This field allows the tape management system to select which files are duplicated. You can change this value when the tape position exit type field is SOS and the tape operation field is 0 for the DUPTAP command. The default is to duplicate the file.
| 0 | Do not duplicate the file |
| 1 | Duplicate the file |
Encryption Keystore File. The keystore file containing the key to be used for encryption/decryption. The first 10 characters contain the file name. The second 10 characters contain the name of the library where the keystore file is located.
This field, along with the Encryption Record Label, can be changed at the SOS exit to indicate that the file data is to be encrypted (output operation) or decrypted (input operation).
For output operations this field is always set to blank for the first SOS exit of a file and must be changed to enable encryption. Whenever a file spans volumes this field is set to the value used for the same file on the previous volume.
For input operations this field is set to blank or the value defined in the tape decryption data area for the first SOS exit of a file. Whenever a file spans volumes this field will be set to the value used for the same file on the previous volume. See the Storage solutions topic collection for additional information about the tape decryption data area.
The field is ignored on other tape position exit types.
If an incorrect or unusable Keystore File is provided message CPF670A will be issued.
- If a file spans multiple volumes the same keystore file and encryption record label must be used at each SOS exit for the same file.
- Encryption can not be used when tape data files are being extended.
- The encryption key type must be AES.
- The job using the tape exit must have *OBJOPR and *READ authority to the keystore file. *UPD authority is required if the keystore file needs re-translation.
- For output operations IBM i option 44 (Encrypted backup enablement) must be installed and licensed.
- For save operations the target release must be V6R1M0 or later.
- The tape volume must be a standard labeled tape.
- Encryption can not be used when tape write error recovery is enabled.
See the Cryptography topic collection for additional information about encryption keystore files.
The application using the tape management exit program interface needs to verify that any parts of operating system including the SAVSYS files, SAVSYSINF files, and the QMSE, QSYS2, QUSRSYS libraries do not get encrypted. The tape management exit program does not verify what data is being encrypted.
Encryption Record Label. The label for the key record that identifies the key to be used for encryption/decryption. The label will be converted to CCSID 1200 (Unicode UTF-16). The job CCSID will be used for the conversion unless it is 65535, in which case the job default CCSID will be used.
This field, along with the Encryption Keystore File, can be changed at the SOS exit to indicate that the file data is to be encrypted (output operation) or decrypted (input operation).
For output operations this field is always set to blank for the first SOS exit of a file and must be changed to enable encryption. Whenever a file spans volumes this field is set to the value used for the same file on the previous volume.
For input operations this field is set to blank or the value defined in the tape decryption data area for the first SOS exit of a file. Whenever a file spans volumes this field will be set to the value used for the same file on the previous volume. See the Storage solutions topic collection for additional information about the tape decryption data area.
The field is ignored on other tape position exit types.
If an incorrect or unusable Key Record Label is provided message CPF670A will be issued.
- If a file spans multiple volumes the same keystore file and encryption record label must be used at each SOS exit for the same file.
- Encryption can not be used when tape data files are being extended.
- The encryption key type must be AES.
- The job using the tape exit must have *OBJOPR and *READ authority to the keystore file. *UPD authority is required if the keystore file needs re-translation.
- For output operations IBM i option 44 (Encrypted backup enablement) must be installed and licensed.
- For save operations the target release must be V6R1M0 or later.
- The tape volume must be a standard labeled tape.
- Encryption can not be used when tape write error recovery is enabled.
See the Cryptography topic collection for additional information about encryption keystore files.
The application using the tape management exit program interface needs to verify that any parts of operating system including the SAVSYS files, SAVSYSINF files, and the QMSE, QSYS2, QUSRSYS libraries do not get encrypted. The tape management exit program does not verify what data is being encrypted.
End position. This field allows the tape management system to change the end positioning that was specified by the user. The value can be changed at the end positioning exit type. This field is blank when the value cannot be changed. The default for this field is the value specified for end positioning in the operational information format and can be changed to any of the following:
| 0 | Rewind the tape volume. |
| 1 | Unload the tape volume. |
| 2 | Do not position tape (*LEAVE). |
| 3 | Unload and eject (remove) the tape volume. |
File expiration date. The expiration date of the file being written in the header label to control data file expiration.
This field uses the Julian format with a leading century digit. It is of the form CYYDDD, where C represents the thousands and hundreds of the year value (19 is blank, 20 is 0, and 21 is 1), YY represents the year (00-99), and DDD represents the day of the year (001-366). For example, 1 February 1972 is represented as ' 72032' and 1 February 2072 is represented as '072032'.
The value *PERM indicates that the tape file is a permanent tape file. This special value must be in uppercase and left-justified. Blanks indicate that the default expiration date should be used.
You can change this value at SOF or SOV tape position exit type when the tape operation field is 1 and the initialize new volume label field is 0. (These fields are in the operational information format.) The default for this field is the file expiration date that the user requested.
If the field is changed to contain a date that is not valid, it is ignored and message CPF4063 is issued.
Image catalog name. The name of the currently loaded image catalog on the virtual device. This field can be changed at any exit type along with setting the volume acceptance field to a value of 4 to cause a replacement virtual tape image catalog to be loaded. If the tape position exit type is SOF, SOV, or SOS, this field identifies a replacement for the current image catalog. If the tape position exit type is EOS or EOF, this field identifies a replacement for the next image catalog.
This field is always set to blank when the device is not a virtual device. If an incorrect or unusable image catalog name is provided, or the device is not a virtual device, message CPF41B0 will be issued.
The field is ignored during Duplicate Tape (DUPTAP) operations on all tape position exit types except SOF, SOV, and SOS on the first source and first target volumes.
Issue active file messages. Whether IBM i should issue active file messages. If the field contains a value that is not valid, it is ignored and message CPF4067 is issued. You can change the value when the tape position exit type field is SOV. The default is 0 when the tape position exit type is SOV. Valid values are:
| 0 | Issue active file messages |
| 1 | Do not issue active file messages |
Issue mount next tape message. Whether IBM i should issue mount next tape messages. If the field contains a value that is not valid, it is ignored and message CPF4067 is issued. You can change this value when the tape position exit type field is EOS. The default is 0 when the tape position exit type is EOS.
| 0 | Mount next tape messages are issued. |
| 1 | Mount next tape messages are not issued. |
Large sequence number. The sequence number being used. At the start-of-volume exit type, this field contains the user-specified sequence number. This field is blank for all other exit types. The field can be changed for both input and output operations when the sequence number change allowed field in the operational information indicates that a change is allowed.
For output operations, the following user-specified sequence numbers may be passed to the tape management system:
- blank
- *END (left-justified and padded with blanks)
- A numeric value (right-justified with leading zeros or blanks) from 1 to 16 777 215
- blank
- *END (left-justified and padded with blanks)
- A numeric value (right-justified with leading zeros or blanks) from 1 to 16 777 215
For input operations, the following user-specified sequence numbers may be passed to the tape management system:
- blank
- *FIRST (left-justified and padded with blanks)
- *NEXT (left-justified and padded with blanks)
- A numeric value (right-justified with leading zeros or blanks) from 1 to 16 777 215
- blank
- A numeric value (right-justified with leading zeros or blanks) from 1 to 16 777 215
An invalid value or changing the sequence number when it is not allowed causes message CPF416B to be issued. This field overrides a value that is specified for the sequence number field. This field has the same function as the sequence number field, but allows for a greater range of sequence numbers.
Logical block identifier. The tape position to locate. This field is checked after the SOV tape position exit type is reached. If the logical block identifier is changed by the user at a tape position exit type other than SOV, or is changed to an incorrect value, the logical block identifier is referred to as an incorrect logical block identifier in message CPD4076. The logical block identifier is an incorrect value for any of the following:
- The tape is the wrong format
- The tape is not a standard label (*SL) tape
- The tape is not opened for input
- The tape is opened for bypass label processing (*BLP)
- The tape is opened for a read-backward operation
- The device does not support positioning by logical block identifier
- The identifier is not found on the tape
Message response. The response to the message exit type. You can change the value when the tape processing exit type is message. The default is 0 when the tape processing exit point is message. If the message response from the user is anything other than 0, a message that states that the tape management system handled the error is sent to the user. Valid values are as follows:
| 0 | Ignore the message exit type. The message is sent when IBM i regains control of the program from the user exit program. |
| 1 | Cancel the operation by replying to the message exit type with a C before the message is actually sent. This stops the message from being sent. |
| 2 | Ignore the operation by replying to the message exit type with an I before the message is actually sent. This stops the message from being sent. |
| 3 | Retry the operation by replying to the message exit type with an R before the message is actually sent. This stops the message from being sent. |
| 4 | Initialize the tape volume by replying to the message exit type with an INZ before the message is actually sent. This stops the message from being sent. |
| 5 | Continue the operation by replying to the message exit type with a G before the message is actually sent. This stops the message from being sent. |
Mismatch acceptance. The control value that determines how to handle a cartridge ID mismatch situation. You can change the value when the tape library device exit type field is mismatch. The default is 1 when the tape library device exit type is mismatch. Valid values are:
| 1 | Ignore the mismatch of the cartridge identifier and the logical volume identifier. |
| 2 | Initialize the logical volume identifier to match the cartridge identifier. |
| 3 | Eject the tape cartridge immediately from the tape library device and place it in the *EJECT category. The tape operation ends immediately. |
| 4 | Reject the output operation, leaving the tape cartridge in the tape library device for input operations. The tape operation ends immediately. |
Suppress auto-generate of virtual tape volume. Whether to suppress auto-generate of a new virtual tape volume. You can change this value when the tape position exit type field is EOS. The default is 0 when the tape position exit type is EOS. Valid values are:
| 0 | Allow a new virtual tape volume to be auto-generated when the end of the image catalog is reached. |
| 1 | Do not allow a new virtual tape volume to be auto-generated when the end of the image catalog is reached. |
Sequence number. The sequence number to be used. Use the large sequence number field rather than this field if you are adding support for this function to a tape management system. At the start-of-volume exit type, this field contains the user-specified sequence number. This field is blank for all other exit types. The field can be changed for both input and output operations when the sequence number change allowed field in the operational information indicates that a change is allowed.
For output operations, the following user-specified sequence numbers may be passed to the tape management system:
- blank
- *END (left-justified and padded with blanks)
- A numeric value (right-justified with leading zeros or blanks) from 1 to 999 999
- blank
- *END (left-justified and padded with blanks)
- A numeric value (right-justified with leading zeros or blanks) from 1 to 999 999
For input operations, the following user-specified sequence numbers may be passed to the tape management system:
- blank
- *FIRST (left-justified and padded with blanks)
- *NEXT (left-justified and padded with blanks)
- A numeric value (right-justified with leading zeros or blanks) from 1 to 999 999
- blank
- A numeric value (right-justified with leading zeros or blanks) from 1 to 999 999
An invalid value or changing the sequence number when it is not allowed causes message CPF416B to be issued. This field is ignored if a value is specified for the large sequence number field.
Use optimum block size. Whether to use the optimum block size for save commands. If the optimum block size is used on a save command, commands such as Duplicate Tape (DUPTAP) only duplicate the tape volume to devices that support the same block size. If the optimum block size is not used, normal save processing uses the default block size that can be duplicated to any device type by using the DUPTAP command. The field is initialized to the value that the user specifies on the save command. The field can be changed at the start-of-command exit type only. At all other exit points, the field is set to blanks. Note that if a blank is passed, the value cannot be overridden by the tape management system. For example, on the Save System (SAVSYS) command, the value specified by the user for Use Optimum Block (USEOPTBLK) cannot be changed. Valid values follow:
| 0 | Do not use optimum block size |
| 1 | Use optimum block size |
| blank | An override is not allowed for optimum block size |
Volume acceptance. Whether the exit program accepts the mounted volume or the loaded virtual tape image catalog. This field has precedence over all other fields. You can change this value when the tape position exit type field is 1 through 6. The default is 1 for tape position exit types 1 through 5.
| 1 | Mounted volume is accepted |
| 2 | No volume is accepted. The tape operation ends immediately. |
| 3 | Reject in favor of another volume |
| 4 | Reject and unload in favor of another volume or in favor of another virtual tape image catalog. When a new virtual tape image catalog is specified. |
An acceptance value of '3' is not allowed when a category is mounted in a tape library device. CPF410B, CPF450B, or CPF510B will be issued and the tape operation ends immediately. An acceptance value of '4' is not allowed for a tape position exit type of SOV when the Initialize new volume label field of the Operational Information is set to '1'. An acceptance value of '3' is not allowed when rejecting in favor of another virtual tape image catalog. An acceptance value of '3' or '4' is not allowed for a tape position exit type of SOS for the DSPTAP command.
Volume to be used. The volume to be loaded if 3 or 4 is specified for the volume acceptance field. This field can be set at any exit type to pass a replacement volume identifier. If the tape position exit type is SOF, SOV, or SOS, this field identifies a replacement for the current volume identifier. If the tape position exit type is EOS or EOF, this field identifies a replacement for the next volume identifier.
The field is ignored during Duplicate Tape (DUPTAP) operations on all tape position exit types except SOF, SOV, and SOS on the first source and first target volumes.
The field is used as a new volume identifier override during Initialize Tape (INZTAP) operations.
The field must be set to blanks if 4 is specified for the volume acceptance field when a category is mounted in a tape library device.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPD4003 D | Alternate volume identifier not standard. |
| CPD4076 D | Logical block identifier not correct. |
| CPF4062 D | Alternate volume identifier not standard. |
| CPF4063 D | Incorrect file expiration date &7 specified. |
| CPF4067 D | Incorrect user exit control value specified. |
| CPF410A E | Error detected using program &6 in &7. |
| CPF410B E | Volume acceptance response not valid. |
| CPF410C E | End request specified by program &6. |
| CPF416B E | Incorrect user exit control value specified. |
| CPF41B0 E | Incorrect image catalog name specified. |
| CPF4402 D | Alternate volume identifier not standard. |
| CPF450A E | Error detected using program &6 in &7. |
| CPF450B E | Volume acceptance response not valid. |
| CPF450C E | End request specified by program &6. |
| CPF510A E | Error detected using program &6 in &7. |
| CPF510B E | Volume acceptance response not valid. |
| CPF510C E | End request specified by program &6. |
| CPF5401 E | Interface error on device &4. |
| CPF670A E | Incorrect encryption key information specified. |
Exit program introduced: V3R1
[ Back to top | Backup and Recovery APIs | APIs by category ]