Set Cartridge Filter (QTASCTGF) API
| 1 | Cartridge filter | Input | Char(*) |
| 2 | Length of cartridge filter | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Requested action | Input | Binary(4) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Set Cartridge Filter (QTASCTGF) API sets a filter that defines the cartridges that can be used by tape library devices on the system.
Authorities and Locks
The caller of this API must have *ALLOBJ and *IOSYSCFG special authorities.
Required Parameter Group
- Cartridge Filter
- INPUT; CHAR(*)
The structure that sets the cartridge filter.
- Length of cartridge filter
- INPUT; BINARY(4)
The length of the cartridge filter structure provided. The length must be set to 0 when the requested action value is 3. When the requested action value is 1, 2, or 4 the length specified must be large enough to contain the entire cartridge filter array as defined by the fields in the cartridge filter parameter.
- Format name
- INPUT; CHAR(8)
Specifies the content and format of the information being set.
The SFTR0100 format must be used for the cartridge filter. See SFTR0100 Format to view the information set for this format.
- Requested action
- INPUT; BINARY(4)
The action to take with the filter provided. The possible values are:
1 The filter provided will replace the existing filter. 2 The filter provided will be appended to the existing filter. 3 The existing filter will be cleared. 4 The filter provided will be removed from the existing filter. - Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
SFTR0100 Format
The following table shows the information that is set for the SFTR0100 format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to array |
| 4 | 4 | BINARY(4) | Number of array entries |
| 8 | 8 | BINARY(4) | Length of array entry |
| Array(*) of CHAR(*) | Cartridge filter array | ||
Field Descriptions
Cartridge filter array. An array of cartridge filters to be defined for the system. Each array entry may consist of either a specific cartridge identifier, or a generic name of a cartridge identifier. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. A generic name specifies all cartridge identifiers with names that begin with the generic prefix.
Note: The cartridge identifier is restricted to characters A through Z, zero through nine, at-sign (@), dollar-sign ($), and pound sign (#). A valid generic name contains 1 or more supported characters followed by a single asterisk (*) and blanks. The at-sign (@), dollar-sign ($), pound sign (#), and asterisk (*) characters must be provided in CCSID 37.
- @ = '7C'x
- $ = '5B'x
- # = '7B'x
- * = '5C'x
Length of array entry. This field is set to the length, in bytes, of a single cartridge filter entry. This field must be set to 6.
Number of array entries. The number of cartridge filter entries specified.
Offset to array. The offset, in bytes, to the cartridge filter array.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF222E E | &1 special authority is required. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C4C E | Value not valid for field &1. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF6708 E | Command ended due to error. |
| CPF67C9 E | An error occurred during a cartridge filter operation. |
| CPF67CA E | Cartridge &1 is not correct. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R3
[ Back to top | Backup and Recovery APIs | APIs by category ]