This chapter describes additional miscellaneous DIVA Enterprise Connect commands and includes the following services:
The miscellaneous commands int his chapter can perform miscellaneous tasks such as canceling requests, adding or deleting tape groups, and locking or unlocking objects. These commands are simple request and response operations, and do not require returning information in batches, nor monitoring through the getRequestInfo() call.
registerClient()This command creates a client session. A valid client session is necessary to use the DIVArchive Web Services API. The client must provide valid authentication in this step to have a sessionCode returned successfully. You must supply a valid sessionCode in every Web Service request. This command is specific to the DIVArchive Web Services, and does not cause a call to DIVArchive or DIVAnet.
The following table lists the registerClient() input parameters:
Table 7-1 registerClient() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the name of the application invoking the services. |
String (1 - 96 characters) This field is required. |
|
|
This parameter identifies a string describing the location of the client (caller). |
String (1 - 96 characters) This field is required. |
|
|
This parameter identifies the ID of the client process that is executing, or another unique ID that identifies the instance of the application that is executing. |
String (1 - 96 characters) This field is required. |
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 7-2 registerClient() Command Return Values
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the DIVArchive status code for the operation. |
Integer (1000 - 1039) |
|
|
The parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) |
The following are typical DIVArchive registerClient() command status codes. See Appendix A for all DIVArchive Status Codes.
The request has been created successfully.
One or more parameters contain data that cannot be parsed correctly.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST registerClient() command:
<p:registerClient xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:appName>MediaDatabase2</p:appName> <p:locName>USWest2</p:locName> <p:processId>5828</p:processId> </p:registerClient>
The following is an example of a REST response for a registerClient() command:
<p:registerClientResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd> <p1:return>810c85c7-d70c-414e-93a4-655a3e4c89bd</p1:return> </p:registerClientResponse>
changeRequestPriority()This command enable you to change the priority of a running or pending request to a new value. The priority of a request that has already finished execution cannot be changed.
In DIVArchive, the effective priority of a request is constantly increased as it sits in the queue waiting to run. It is possible that if the priority of a long running request is changed (for example, from 50 to 60), the effective priority in DIVArchive may actually be decreased.
This command is available in DIVArchive. DIVAnet (MultiDIVA mode) returns success for this operation, but will not process the request.
The following table lists the changeRequestPriority() input parameters:
Table 7-3 changeRequestPriority() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the number of the request to modify. |
Integer This field is required. |
|
|
This parameter identifies the initial priority of the request 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 ( If you use |
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:
The following are typical DIVArchive changeRequestPriority() command status codes. See Appendix A for all DIVArchive Status Codes.
The request has been created successfully.
One or more parameters contain data that cannot be parsed correctly.
The request ID you issued does not exist in DIVArchive or DIVAnet.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST changeRequestPriority() command:
<p:changeRequestPriority xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:requestNumber>3904</p:requestNumber> <p:priorityLevel>75</p:priorityLevel> </p:changeRequestPriority>
The following is an example of a REST response for a changeRequestPriority() command:
<p:changeRequestPriorityResponse 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>
</p:return>
</p:changeRequestPriorityResponse>
cancelRequest()This command enables canceling a running DIVArchive or DIVAnet request. You must supply the request ID to cancel the request.
The following table lists the cancelRequest() input parameters:
Table 7-5 cancelRequest() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the number of the DIVArchive or DIVAnet request to cancel. |
Integer This field is required. |
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:
The following are typical DIVArchive cancelRequest() command status codes. There may be a delay between when a cancel request is issued, and when the request actually becomes canceled. See Appendix A for all DIVArchive Status Codes.
The request has been created successfully.
One or more parameters contain data that cannot be parsed correctly.
The request ID you issued does not exist in DIVArchive or DIVAnet.
The request you are attempting to cancel cannot be canceled because it is either not currently executing, or is in a state that cannot be interrupted.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST cancelRequest() command:
<p:cancelRequest xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:requestNumber>1678</p:requestNumber> </p:cancelRequest>
The following is an example of a REST response for a cancelRequest() command:
<p:cancelRequestResponse 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>
</p:return>
</p:cancelRequestResponse>
addGroup()This command enables the caller to add a tape group to a running DIVArchive system.
This command is available in DIVArchive, but not in DIVAnet (MultiDIVA mode).
The following table lists the addGroup() input parameters:
Table 7-7 addGroup() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the name of the group being added. |
String (1 - 96 characters) This field is required. |
|
|
This parameter identifies the DIVArchive tape set number where the group will belong. A DIVArchive tape set is a pool of tapes with similar characteristics. |
Integer ( this field is required. |
|
|
This parameter identifies the text describing the group. This text is available to users of the API who call |
String (1 - 768 characters) This field is required. |
|
|
If this parameter is |
Boolean ( This field is required. |
|
|
If this parameter is |
Boolean ( This field is optional. |
|
|
This parameter identifies the number of tapes reserved for worst fit repacking. |
Integer This field is required. |
|
|
This parameter identifies the format type of the tapes in this group. This is either DIVArchive legacy format, or AXF (Archive Exchange Format). The possible integer values are as follows:
|
Integer ( This field is required. |
|
|
If this parameter is |
Boolean ( This field is optional. |
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:
The following are typical DIVArchive addGroup() command status codes. See Appendix A for all DIVArchive Status Codes.
The request has been created successfully.
One or more parameters contain data that cannot be parsed correctly.
The requested group already exists in DIVArchive.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST addGroup() command:
<p:addGroup xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:groupName>LTOPOST3</p:groupName> <p:associatedSet>1</p:associatedSet> <p:comment>Raw footage for post</p:comment> <p:toBeRepacked>true</p:toBeRepacked> <p:worstFitEnabled>false</p:worstFitEnabled> <p:worstFitRepackTapes>1</p:worstFitRepackTapes> <p:mediaFormatId>1</p:mediaFormatId> <p:verifyWriteEnabled>true</p:verifyWriteEnabled> </p:addGroup>
The following is an example of a REST response for a addGroup() command:
<p:addGroupResponse 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>
</p:return>
</p:addGroupResponse>
deleteGroup()This command deletes a DIVArchive tape group. You can only delete a tape group if there are no object instances stored in the group.
This command is available in DIVArchive, but not in DIVAnet (MultiDIVA mode).
The following table lists the deleteGroup() input parameters:
Table 7-9 deleteGroup() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the name of the DIVArchive tape group to be deleted. |
String (1 - 96 characters) This field is required. |
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:
The following are typical DIVArchive deleteGroup() command status codes. See Appendix A for all DIVArchive Status Codes.
The request has been created successfully.
One or more parameters contain data that cannot be parsed correctly.
The tape group you provided does not exist in DIVArchive.
The tape group you provided currently has object instances stored in it.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST deleteGroup() command:
<p:deleteGroup xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:groupName>LTOPOST3</p:groupName> </p:deleteGroup>
The following is an example of a REST response for a deleteGroup() command:
<p:deleteGroupResponse 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>
</p:return>
</p:deleteGroupResponse>
lockObject()This command allows an object to become locked for restore. Objects cannot be restored while they are locked. You must invoke unlockObject() to allow the object to be restored.
This command is available in DIVArchive. DIVAnet returns success for this operation, but does not process the request.
The following table lists the lockObject() input parameters:
Table 7-11 lockObject() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the name of the object. This parameter, along with |
String (1 - 192 characters) This field is required. |
|
|
This parameter identifies the name of the object category. This parameter, along with |
String (1 - 96 characters) This field is required. |
|
|
No options are currently defined for this operation. |
String (0 - 768 characters) You can leave this field empty. |
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:
The following are typical DIVArchive lockObject() command status codes. See Appendix A for all DIVArchive Status Codes.
The request has been created successfully.
One or more parameters contain data that cannot be parsed correctly.
An object with the name provided does not exist in the DIVArchive.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST lockObject() command:
<p:lockObject xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:objectName>PREPROD_July_Edits4</p:objectName> <p:category>PROD</p:category> <p:options></p:options> </p:lockObject>
The following is an example of a REST response for a lockObject() command:
<p:lockObjectResponse 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>
</p:return>
</p:lockObjectResponse>
unlockObject()This command allows the unlocking of an object previously locked for restore. Objects cannot be restored if they are locked. DIVArchive returns success for the operation even if the object is not currently locked. You must invoke lockObject() to lock the object from restore.
This command is available in DIVArchive. DIVAnet returns success for this operation, but does not process the request.
The following table lists the unlockObject() input parameters:
Table 7-13 unlockObject() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the name of the object. This parameter, along with |
String (1 - 192 characters) This field is required. |
|
|
This parameter identifies the name of the object category. This parameter, along with |
String (1 - 96 characters) This field is required. |
|
|
No options are currently defined for this operation. |
String (0 - 768 characters) You can leave this field empty. |
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:
The following are typical DIVArchive unlockObject() command status codes. See Appendix A for all DIVArchive Status Codes.
The request has been created successfully.
One or more parameters contain data that cannot be parsed correctly.
An object with the name provided does not exist in the DIVArchive.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST unlockObject() command:
<p:unlockObject xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:objectName>PREPROD_July_Edits4</p:objectName> <p:category>PROD</p:category> <p:options></p:options> </p:unlockObject>
The following is an example of a REST response for a unlockObject() command:
<p:unlockObjectResponse 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>
</p:return>
</p:unlockObjectResponse>
linkObjects()This command links DIVArchive archived objects together, creating a parent-child relationship. The parent and child objects must both exist in DIVArchive before performing the link operation. In addition to maintaining this relationship in DIVArchive, additional options are available to delete the child object if the parent object is deleted, and to restore the child object if the parent object is restored.
This command is available in DIVArchive. DIVAnet returns success for this operation, but does not process the request. There is no unlink operation available in the DIVArchive Web Services API.
The following table lists the linkObjects() input parameters:
Table 7-15 linkObjects() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the name of the parent object. This parameter, along with |
String (1 - 192 characters) This field is required. |
|
|
This parameter identifies the name of the parent object category. This parameter, along with |
String (1 - 96 characters) This field is required. |
|
|
This parameter identifies the name of the child object. This parameter, along with |
String (1 - 192 characters) This field is required. |
|
|
This parameter identifies the name of the child object category. This parameter, along with |
String (1 - 96 characters) This field is required. |
|
|
The value of this parameter is |
Boolean ( This field is required. |
|
|
The value of this parameter is |
Boolean ( This field is required. |
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 7-16 linkObjects() Command Return Values
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the DIVArchive status code for the operation. |
Integer (1000 - 1039) |
|
|
The parameter identifies the ID that uniquely identifies the new running request. You can monitor the progress of the request by using this ID. |
Integer (1 - 10,000,000) |
The following are typical DIVArchive linkObjects() command status codes. See Appendix A for all DIVArchive Status Codes.
The selected objects have been linked.
One or more parameters contain data that cannot be parsed correctly.
An object with the name provided does not exist in the DIVArchive system.
The DIVArchive or DIVAnet system temporarily cannot accept any more requests. You can try the request again later.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST linkObjects() command:
<p:linkObjects xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:parentName>PREPROD_July_Edits4</p:parentName> <p:parentCategory>PROD</p:parentCategory> <p:childName>PREPROD_July_Metadata4</p:childName> <p:childCategory>PRODMeta</p:childCategory> <p:cascadeDelete>true</p:cascadeDelete> <p:cascadeRestore>false</p:cascadeRestore> </p:linkObjects>
The following is an example of a REST response for a linkObjects() command:
<p:linkObjectsResponse 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>
</p:return>
</p:linkObjectsResponse>
require()This command sets a flag in the DIVArchive database indicating that an object instance is required to be present in the tape library, and therefore should not be externalized. You can query this flag can be queried through the DIVArchive Control GUI. If the instance has already been marked as required, this call has no effect. The flag is informational only, and is not used to prevent or allow tape operations.
This command is available in DIVArchive, but not in DIVAnet (MultiDIVA mode).
The following table lists the require() input parameters:
Table 7-17 require() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the name of the object. This parameter, along with |
String (1 - 192 characters) This field is required. |
|
|
This parameter identifies the name of the object category. This parameter, along with |
String (1 - 96 characters) This field is required. |
|
|
This parameter identifies the tape instance to mark as required. If this field is empty, or the value |
String ( |
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:
The following are typical DIVArchive require() command status codes. See Appendix A for all DIVArchive Status Codes.
The request has been created successfully.
One or more parameters contain data that cannot be parsed correctly.
The object name and category pair provided does not exist in DIVArchive.
More than one object with the specified name exists in the DIVArchive or DIVAnet database.
The specified instance ID does not exist in DIVArchive.
The specified instance must be a tape instance.
There is no valid tape instance for the object in DIVArchive
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST require() command:
<p:require xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:objectName> PREPROD_July_Edits4</p:objectName> <p:categoryName>PROD</p:categoryName> <p:instanceID>1</p:instanceID> </p:require>
release()This command sets a flag in the DIVArchive database indicating that an object instance is available to be externalized. You can query this flag through the DIVArchive Control GUI. If the instance has already been released, this call has no effect. The flag is informational only, and is not used to prevent or allow tape operations.
This command is available in DIVArchive, but not in DIVAnet (MultiDIVA mode).
The following table lists the release() input parameters:
Table 7-19 release() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
This parameter identifies the name of the object. This parameter, along with |
String (1 - 192 characters) This field is required. |
|
|
This parameter identifies the name of the object category. This parameter, along with |
String (1 - 96 characters) This field is required. |
|
|
This parameter identifies the tape instance to mark as released. If this field is empty, or the value |
String ( |
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:
The following are typical DIVArchive release() command status codes. See Appendix A for all DIVArchive Status Codes.
There may be some delay between receiving this code and when the request is actually canceled.
One or more parameters contain data that cannot be parsed correctly.
The object name and category pair provided does not exist in DIVArchive.
More than one object with the specified name exists in the DIVArchive or DIVAnet database.
The specified instance ID does not exist in DIVArchive.
The specified instance must be a tape instance.
There is no valid tape instance for the object in DIVArchive
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST release() command:
<p:release xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:objectName> PREPROD_July_Edits4</p:objectName> <p:categoryName>PROD</p:categoryName> <p:instanceID>1</p:instanceID> </p:release>
enableAutomaticRepack()This command enables or disables the scheduled automatic repack service within DIVArchive. When enabled, DIVArchive uses the repack schedule and thresholds defined in the DIVArchive configuration. When disabled, the service is not executed.
This command is available in DIVArchive, but not in DIVAnet (MultiDIVA mode).
The following table lists the enableAutomaticRepack() input parameters:
Table 7-21 enableAutomaticRepack() Command Input Parameters
| Parameter | Description | Data Type and Default |
|---|---|---|
|
|
This parameter identifies the unique ID associated with the client's session. |
String (1 - 36 characters) This field is required. |
|
|
If you set this to |
Boolean ( This field is required. |
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:
The following are typical DIVArchive enableAutomaticRepack() command status codes. See Appendix A for all DIVArchive Status Codes.
Automatic repack has been enabled or disabled.
One or more parameters contain data that cannot be parsed correctly.
This code is returned if the client does not have permission for the request, or the command has been disallowed.
The following is an example of a REST enableAutomaticRepack() command:
<p:enableAutomaticRepack xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode> <p:enable>true</p:enable> </p:enableAutomaticRepack>
The following is an example of a REST response for a enableAutomaticRepack() command:
<p:enableAutomaticRepackResponse 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>
</p:return>
</p:enableAutomaticRepackResponse>
The following commands are deprecated:
InsertTapeShort()You can achieve the same result calling insertTape(), and omit the acsId and capId tags entirely. Alternatively, you can set the acsId and capId parameters to -1.
addGroupShort()You can achieve the same result calling addGroup(), and omitting the verifyWriteEnabled and worstFitEnabled tags entirely. Alternatively, you can set both parameters to false.
deleteInstanceByMediaName()You can achieve the same result calling deleteInstance(), populating the mediaName field, and setting instanceID value to -1.