5 Device Requests

This chapter describes tape device requests and includes the following services:

Eject Tape: ejectTape()

This request ejects media from an archive device; typically tape media from a tape library device. The tapes are usually ejected into a CAP (Cartridge Access Point) located on a tape library. The request is complete after all tapes are successfully ejected.

If the request is created successfully the call returns a request ID. You can monitor the progress of the call throughout its lifecycle using the getRequestInfo() call. This request is available in DIVArchive, but not DIVAnet.

Input Parameters

The following is a list of ejectTape() request input parameters:

Table 5-1 ejectTape() Request Input Parameters

Parameter Description Data Type and Defaults

sessionCode

This parameter identifies the unique ID associated with the client's session.

String (1 - 36 characters)

This field is required.

vsnList

This parameter identifies the volume serial number (barcode) of the tapes to be ejected. These must be unique values within each DIVArchive system. The <vsnList> tag delimits each barcode, and is repeated for each barcode in the list. For example:

<vsnList>DS4903</vsnList>
<vsnList>FS4905</vsnList>

String (each barcode can have 1 - 96 characters)

One, or multiple, instances of this parameter may appear.

release

If you set this value to true, all object instances located on the tape are marked in DIVArchive as no longer required (released). This flag is for informational purposes only.

Boolean (true or false)

This field is required.

comment

This parameter is a comment that you can use to indicate to DIVArchive operators why the eject tape operation was performed.

String

priorityLevel

This parameter identifies the initial request priority on a scale of 0 to 100 (100 is the highest priority). The effective priority of the request increases the longer it waits for execution.

Integer (0 - 100)

If you use nil or -1 for this value, the DIVArchive default is used.

Returned Values

If a response to the request was returned by DIVArchive or DIVAnet, HTTP status code 200 will be returned, and will include the following values:

Table 5-2 ejectTape() Request Returned Values

Parameter Description Data Type and Default

divaStatus

This parameter is the DIVArchive Status Code for the operation (see the following section).

Integer (1000 - 1039)

requestNumber

This parameter is an ID uniquely identifying the running request. You can monitor the progress of the request using this ID.

Integer (1 - 10,000,000)

DIVArchive Status Codes

The following are typical DIVArchive ejectTape() request status codes. See Appendix A for all DIVArchive Status Codes.

1000: Success

The request has been created successfully.

1008: Invalid Parameter

One or more parameters contain data that cannot be parsed correctly.

1032: Cannot Accept More Requests

The DIVArchive or DIVAnet system temporarily cannot accept any more requests. You can try the request again later.

1033: Tape Does Not Exist

The provided barcode does not exist in the DIVArchive configuration.

1035: Access Denied

This code is returned if the client does not have permission for the request, or the command has been disallowed.

REST Request Example

The following is an example of a REST ejectTape() request:

<p:ejectTape xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:vsnList>DS4903</p:vsnList>
   <p:vsnList>FS4905</p:vsnList>
   <p:release>false</p:release>
   <p:comment>Externalized for long term storage</p:comment>  
   <p:priorityLevel>50</p:priorityLevel>
</p:ejectTape>

REST Response Example

The following is an example of a REST response for an ejectTape() request:

<p:ejectTapeResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd>
   <p:return>
      <p1:divaStatus>1000</p1:divaStatus>
      <p1:requestNumber>4905</p1:requestNumber>
   </p:return>
</p:ejectTapeResponse>

Insert Tape: insertTape()

This request facilitates the insertion of media into an archive device; typically tape media into a tape library device. DIVArchive waits for a short period while an operator inserts the tapes, usually into a CAP in a tape library. The request completes when all affected tapes are successfully inserted into the library.

If the request is called successfully it returns a request ID. You can monitor the progress of the call throughout its lifecycle using the getRequestInfo() call. This request is available in DIVArchive, but not DIVAnet (MultiDiva mode).

Input Parameters

The following is a list of insertTape() request input parameters:

Table 5-3 insertTape() Request Input Parameters

Parameter Description Data Type and Defaults

sessionCode

This parameter identifies the unique ID associated with the client's session.

String (1 - 36 characters)

This field is required.

require

If you set this value to true, all object instances located on the tape are marked in as required in DIVArchive. This flag is for informational purposes only.

Boolean (true or false)

This field is required.

priorityLevel

This parameter identifies the initial request priority on a scale of 0 to 100 (100 is the highest priority). The effective priority of the request increases the longer it waits for execution.

Integer (0 - 100)

If you use nil or -1 for this value, the DIVArchive default is used.

acsId

This parameter is the ACS ID (Automated Cartridge System ID, which is the tape library ID) of the device where tapes will be inserted. If you enter -1 for this value, DIVArchive attempts an insert in all tape library devices. This ID can be obtained in the getArchiveSystemInfo() call.

Integer

capId

This parameter identifies the numeric ID of the CAP in the tape library where tapes will be inserted. If you enter -1 for this value, DIVArchive attempts an insert into the first available CAP.

Integer

Returned Values

If a response to the request was returned by DIVArchive or DIVAnet, HTTP status code 200 will be returned, and will include the following values:

Table 5-4 insertTape() Request Returned Values

Parameter Description Data Type and Default

divaStatus

This parameter is the DIVArchive Status Code for the operation (see the following section).

Integer (1000 - 1039)

requestNumber

This parameter is an ID uniquely identifying the running request. You can monitor the progress of the request using this ID.

Integer (1 - 10,000,000)

DIVArchive Status Codes

The following are typical DIVArchive insertTape() request status codes. See Appendix A for all DIVArchive Status Codes.

1000: Success

The request has been created successfully.

1008: Invalid Parameter

One or more parameters contain data that cannot be parsed correctly.

1032: Cannot Accept More Requests

The DIVArchive or DIVAnet system temporarily cannot accept any more requests. You can try the request again later.

1035: Access Denied

This code is returned if the client does not have permission for the request, or the command has been disallowed.

REST Request Example

The following is an example of a REST insertTape() request:

<p:insertTape xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:require>false</p:require>
   <p:priorityLevel>50</p:priorityLevel>
   <p:acsId>-1</p:acsId>
   <p:capId>-1</p:capId>
</p:insertTape>

REST Response Example

The following is an example of a REST response for an insertTape() request:

<p:insertTapeResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd>
   <p:return>
      <p1:divaStatus>1000</p1:divaStatus>
      <p1:requestNumber>4905</p1:requestNumber>
   </p:return>
</p:insertTapeResponse>