Change Job Media Library Attributes (QTACJMA) API
| 1 | Media library attributes description | Input | Char(*) |
| 2 | Length of media library attributes description | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified job name | Input | Char(26) |
| 5 | Internal job identifier | Input | Char(16) |
| 6 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Change Job Media Library Attributes (QTACJMA) API changes the specified job's settings for the media library attributes. For more information on tape management, see Tape information in the Storage solutions topic collection.
Authorities and Locks
- Device Description Authority
- *CHANGE
- Job Authority
- *JOBCTL, if the job for which information is changed has a different user profile from that of the job that calls the QTACJMA API. *JOBCTL special authority is required when changing or replacing the resource allocation priority.
Required Parameter Group
- Media library attributes description
- INPUT; CHAR(*)
The media library attributes. Either the entire list of attributes will be replaced or only specified entries will be changed by this specification.
- Length of media library attributes description
- INPUT; BINARY(4)
The length of the media library attributes description, in bytes.
- Format name
- INPUT; CHAR(8)
The format name CJMA0100 is the only valid format name used by this API. For more information, see CJMA0100 Format.
- Qualified job name
- INPUT; CHAR(26)
The name of the job for which information is to be changed. The qualified job name has three parts:
- Job name
- CHAR(10). A specific job name or the following
special value:
- *
- The job that this program is running in. The rest
of the qualified job name parameter must be blank.
- *INT
- The internal job identifier locates the job. The
user name and job number must be blank.
- User name
- CHAR(10). A specific user profile name, or blanks
when the job name is a special value or *INT.
- Job number
- CHAR(6). A specific job number, or blanks when
the job name specified is a special value or *INT.
- Internal job identifier
- INPUT; CHAR(16)
The internal identifier for the job. The List Job (QUSLJOB) API creates this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
CJMA0100 Format
The following table lists the fields for the media library attributes description in the CJMA0100 format. For more information about each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Option |
| 10 | A | CHAR(2) | Reserved |
| 12 | C | BINARY(4) | Number of device entries |
| Offsets vary. These fields repeat in the order listed, for each media library device that is to have attributes defined. | CHAR(10) | Media library device | |
| CHAR(6) | Reserved | ||
| BINARY(4) | Resource allocation priority | ||
| BINARY(4) | Wait time for initial amount | ||
| BINARY(4) | Wait time for end of volume mount | ||
| CHAR(4) | Reserved | ||
Field Descriptions
Media library device. The name of the media library device that the attributes apply to. The special values supported are:
| *ALL | The attributes apply to all media libraries. The value *ALL is only allowed when changing the attributes and must be the first and only device entry. |
| *DEFAULT | The attributes apply to all media libraries that do not have specific attributes defined for the specified job. The *DEFAULT device is only allowed when replacing the attribute list and must be specified as the first device entry. |
Number of device entries. The number of entries in the device list changed for this format. There must be at least one entry defined. The maximum number of device entries allowed is 1000.
Option. An option specifying the action to take. Special values are:
| *CHANGE | The media library attributes are changed by using the device entries specified in the media library attributes description. If an entry already exists for a specified device, that entry will be replaced. If no entry exists for a specified device, an entry will be created. |
| *REPLACE | The entire list of media library attributes are replaced by the device entries specified in the media library attributes description. The first entry must be for the *DEFAULT device. |
Reserved. This field must be set to hexadecimal zeros.
Resource allocation priority. The priority the specified job will be given when the job requests a tape resource within a media library device.
Valid values range from 1 (highest) through 99 (lowest).
Exceptions:
- Value of -1 implies *SAME. The resource allocation priority will remain the same. This value is only allowed for the *CHANGE option.
- Value of -2 implies *DEV. The priority specified in the device description will be used when the job requests a tape resource.
- Value of -31 implies *JOB. The specified job's run-time priority will be used for the resource allocation priority when the job requests a tape resource.
Wait time for end of volume mount. The maximum amount of time, in minutes, a request will wait for the allocation of a tape resource to mount the next volume after the end of volume is reached. Valid values range from 1 through 600.
Exceptions:
- Value of -1 implies *SAME. The wait time for the end of volume mount will remain the same. This value is only allowed for the *CHANGE option.
- Value of -2 implies *DEV. The end of volume mount wait time specified in the device description will be used.
- Value of -8 implies *NOMAX. The specified job will wait until a resource becomes available.
- Value of -31 implies *JOB. The specified job's default wait time will be used to calculate the wait time. The time is calculated by rounding the default wait time, in seconds, to the next highest minute.
- Value of -32 implies *IMMED. The specified job will not wait for a resource to become available.
Wait time for initial mount. The maximum amount of time, in minutes, a request will wait for the allocation of a tape resource to mount the first volume. Valid values range from 1 through 600.
Exceptions:
- Value of -1 implies *SAME. The wait time for the initial mount will remain the same. This value is only allowed for the *CHANGE option.
- Value of -2 implies *DEV. The initial mount wait time specified in the device description will be used.
- Value of -8 implies *NOMAX. The specified job will wait until a resource becomes available.
- Value of -31 implies *JOB. The specified job's default wait time will be used to calculate the wait time. The time is calculated by rounding the default wait time, in seconds, to the next highest minute.
- Value of -32 implies *IMMED. The specified job will not wait for a resource to become available.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1343 E | Job &3/&2/&1 not valid job type for function. |
| CPF136A E | Job &3/&2/&1 not active. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C51 E | Internal job identifier not valid. |
| CPF3C52 E | Internal job identifier no longer valid. |
| CPF3C53 E | Job &3/&2/&1 not found. |
| CPF3C54 E | Job &3/&2/&1 currently not available. |
| CPF3C55 E | Job &3/&2/&1 does not exist. |
| CPF3C58 E | Job name specified is not valid. |
| CPF3C59 E | Internal identifier is not blanks and job name is not *INT. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF6708 E | Command ended due to error. |
| CPF67B1 E | Option value &1 not valid. |
| CPF67B2 E | Number of devices entries &1 not valid. |
| CPF67B3 E | Media library device &1 not valid. |
| CPF67B4 E | Value &1 in field &2 not valid. |
| CPF67B5 E | &3/&2/&1 not authorized to change attribute. |
| CPF67B6 E | &3/&2/&1 not authorized to do requested operation. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V4R3
[ Back to top | Backup and Recovery APIs | APIs by category ]