Change Job Media Library Attributes (QTACJMA) API

Required Parameter Group:

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	Type	Field
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 ]