Reclaim Media (Q1ARCLMED) API

Required Parameter Group:

1	Reclaim media information	Input	Char(*)
2	Length of reclaim media information	Input	Binary(4)
3	Format of reclaim media information	Input	Char(8)
4	Error Code	I/O	Char(*)

Program: QBRM/Q1ARCLMED

Default Public Authority: *USE

Threadsafe: No

The Reclaim Media (Q1ARCLMED) API gives users the ability to programaticaly reclaim a single tape volume.

Authorities and Locks

None

Required Parameter Group

Reclaim media information INPUT; CHAR(*)

The attributes identifying the reclaim media operation. The format of the reclaim media information is specified in the Reclaim Media Information Formats name parameter.

Length of reclaim media information INPUT; BINARY(4)

The number of bytes that the calling program provides for the reclaim media information format.

Format of reclaim media information INPUT; CHAR(8)

The format of the reclaim media information parameter. The possible format names follow:

CRMI0100

Information format for a reclaim media operation.

See Reclaim Media Information formats for a description of this format.

Error code I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see the Error Code Parameter section below.

CRMI0100 Reclaim Media Information Formats

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(10)	Input device
10	0A	CHAR(10)	Output device
20	14	CHAR(10)	Output media class
30	1E	CHAR(1)	Append option
31	1F	CHAR(1)	End of tape option
32	20	CHAR(6)	Volume identifier
38	26	CHAR(10)	Reserved

Reclaim Media Information Format field descriptions:

Input device. Specifies what input device is to be used for the reclaim option.

device-name

The name of the device to be used for the reclaim operation. An exception will result if the specified device does not support the media class of a specified input volume.

Output device. Specifies what output device is to be used for the reclaim operation.

device-name

The name of the device to be used for the reclaim operation. An exception will result if the specified device does not support the specified output media class.

Output media class. Specifies the name of the media class to be used for any volume created using this API.

media-class-name

The name of the media class used to select an output volume for the reclaim operation.

Append option. Indicator of whether the reclaim operation should append to an active volume or begin writing to an expired volume.

0	The reclaim operation should begin writing to an expired volume of the specified output media class.
1	The reclaim operation should append to an active volume of the specified output media class.

End of tape option. Indicator of automatic tape positioning operation to perform on the output volume when the reclaim operation ends.

0	The output volume is rewound, but not unloaded (*REWIND)
1	The output volume is not rewound or unloaded (*LEAVE)
2	The output volume is automatically rewound and unloaded (*UNLOAD)

Volume identifier. The six character identifier of the tape volume for which active file sequences should be reclaimed. Only tape volume identifiers of six bytes are supported at this time.

volume-id

A six-byte volume identifier of a tape volume registered in the BRMS media inventory. The volume must be active and must contain at least one active file sequence. The volume must also be owned by the system on which the reclaim operation is performed.

Error Messages

The following messages may be sent from this function:

Message ID	Error Message Text

Message ID	Error Message Text
CPF3CF1 E	Error code parameter not valid.
CPF24B4 E	Server error while addressing parameter list.
CPF5222 E	Name is not valid.
CPF9800 E	All CPF98xx messages could be signaled (xx range is 01 to FF).
BRM1243 E	Duplicate devices not allowed.
BRM1430 E	Device * not found.
BRM1881 E	Device * not compatible with media policy *.
BRM3C1E E	Required parameter omitted.
BRM3C4B E	Value not valid for field at offset *.
BRM3C4C E	Value not valid for field at offset *
BRM3C91 E	Product feature required.
BRM3C99 E	Unexpected condition with * API. Reason *.
BRM402A E	BRMS product initialization required.
BRM4040 E	Access denied for user *.
BRM4108 E	Format name * not correct.

The reclaim operation uses the DUPMEDBRM command during the reclaim media process to clean up the original volume set. After the reclaim completes, the STRRCYBRM command needs to specify the parameter USEDUPMED(*YES) to report the new volumes.

Sample Program:

The following is an sample CL program:

PGM PARM(&MEDCLS_P &VOL_P &SRCDEV_P &TGTDEV_P &APPEND_P &EOT_P)

DCL VAR(&MEDCLS_P) TYPE(*CHAR) LEN(10)    /* Output Media Class */
DCL VAR(&VOL_P) TYPE(*CHAR) LEN(6)        /* Volume to reclaim */
DCL VAR(&SRCDEV_P) TYPE(*CHAR) LEN(10)    /* Source Device */
DCL VAR(&TGTDEV_P) TYPE(*CHAR) LEN(10)    /* Target Device */
DCL VAR(&APPEND_P) TYPE(*CHAR) LEN(1)     /* Append (0 or 1) */
DCL VAR(&EOT_P) TYPE(*CHAR) LEN(1)        /* End Of Tape (0, 1, or 2) */
DCL VAR(&ATTRINFO) TYPE(*CHAR) LEN(48)    /* API Input Buffer */
DCL VAR(&ATTRLEN) TYPE(*INT) LEN(4) +
      VALUE(48)                           /* Length of ATTRINFO */
DCL VAR(&ERRCODE) TYPE(*CHAR) LEN(8) + 
      VALUE(X'0000000000000000')          /* Tell API to send errors */
     
CHGVAR VAR(%SST(&ATTRINFO 1 10))  VALUE(&SRCDEV_P) 
CHGVAR VAR(%SST(&ATTRINFO 11 10)) VALUE(&TGTDEV_P) 
CHGVAR VAR(%SST(&ATTRINFO 21 10)) VALUE(&MEDCLS_P)
CHGVAR VAR(%SST(&ATTRINFO 31 1))  VALUE(&APPEND_P)
CHGVAR VAR(%SST(&ATTRINFO 32 1))  VALUE(&EOT_P)
CHGVAR VAR(%SST(&ATTRINFO 33 6))  VALUE(&VOL_P)

/* CALL THE API */
CALL PGM(QBRM/Q1ARCLMED) PARM(&ATTRINFO +
       &ATTRLEN 'CRMI0100' &ERRCODE)
       
ENDPGM