6 Informational Commands

This chapter describes information-based commands and includes the following services:

Overview

The informational services described in this chapter supply information about DIVArchive requests, archived assets, Source/Destinations, archive media, and so on. Some commands return large amounts of information in batches. This requires the caller to take information returned in the response, and pass it back in the next request to get the next information batch.

DIVArchive System Information: getArchiveSystemInfo()

This command returns information regarding the configuration and status of DIVArchive. The information includes the number of running requests, the operational status of tape drives, libraries, and Actors, and other information (for example, running requests).

If you issue the command to DIVAnet, the command returns information about the local site. If the -site {site_name} option appears in the Options parameter, DIVAnet returns status on the selected site only. The information returned by DIVAnet only shows status information for a single site, not all sites.

Input Parameters

The following table lists the getArchiveSystemInfo() input parameters:

Table 6-1 getArchiveSystemInfo() Command Input Parameters

Parameter Description Data Type and Default

sessionCode

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

String (1 - 36 characters)

This field is required.

options

If you use DIVAnet, and the -site {site_name} option appears in this parameter, DIVAnet returns status on the selected site.

String (0 - 768 characters)

You can leave this field empty.


Returned Values

If a response to the request was returned by DIVArchive or DIVAnet, HTTP status code 200 will be returned, along with the values below. The command returns generic information about the DIVArchive system. For example, the number of available tape drives, the total number of objects, and the total number of blank tapes. It also returns detailed information regarding Actors, tape drives, and tape library LSMs (Library Storage Module).

Table 6-2 getArchiveSystemInfo() Command Return Values

Section Parameter Description Data Type and Default
 

divaStatus

This parameter identifies the DIVArchive status code for the operation.

Integer (1000 - 1039)

actorsAndDrivesList

 

The section identifies a list of Actor and drive information. See the following items for details.

 

actorsAndDrivesList

actorAddress

The parameter identifies the Actor IP address.

String (1 - 36 characters)

actorsAndDrivesList

actorisAvailable

This parameter is true if the Actor is available to process requests.

Boolean (true or false)

actorsAndDrivesList

connectedDrives

This parameter identifies the ID numbers of the drives connected to the Actor. Each ID is formatted as: acs-lsm-drive (for example, 0-0-1).

String (1 - 192 characters)

actorsAndDrivesList

repackEnabled

This parameter is true if the actor is enabled for Repack.

Boolean (true or false)

actorsAndDrivesList

classicEnabled

This is for backward compatibility only. This parameter is true if all of the classic operations are enabled. The classic operations are as follows:

  • cacheArchiveEnabled

  • directArchiveEnabled

  • cacheRestoreEnabled

  • directRestoreEnabled

  • deleteEnabled

  • copyToGroupEnabled

  • associativeCopyEnabled

Boolean (true or false)

actorsAndDrivesList

cacheArchiveEnabled

This parameter is true if the Actor is enabled for Cache Archive Requests.

Boolean (true or false)

actorsAndDrivesList

directArchiveEnabled

This parameter is true if the Actor is enabled for Direct Archive Requests.

Boolean (true or false)

actorsAndDrivesList

cacheRestoreEnabled

This parameter is true if the Actor is enabled for Cache Restore Requests.

Boolean (true or false)

actorsAndDrivesList

directRestoreEnabled

This parameter is true if the Actor is enabled for Direct Restore Requests.

Boolean (true or false)

actorsAndDrivesList

deleteEnabled

This parameter is true if the Actor is enabled for Delete Requests.

Boolean (true or false)

actorsAndDrivesList

copyToGroupEnabled

This parameter is true if the Actor is enabled to perform Copy To Group Requests.

Boolean (true or false)

actorsAndDrivesList

associativeCopyEnabled

This parameter is true if the Actor is enabled to perform Associative Copy Requests.

Boolean (true or false)

actorsAndDrivesList

cacheForRepack

This parameter is not used and the value is always zero.

Integer (0)

 

capSize

This parameter identifies the number of slots in the default library CAP.

Integer

drivesList

 

This section identifies the list of information about tape drives. This tag repeats for each drive in the list. The following seven parameters are contained in each driveList entry.

Not applicable

drivesList

driveName

This parameter identifies the name of the drive and formatted as acs-lsm-drive (for example, 0-0-1).

String (1 - 192 characters)

drivesList

driveType

This parameter is a string describing the type of drive (for example, LTO4).

String (1 - 192 characters)

drivesList

driveTypeId

This parameter identifies a DIVArchive ID uniquely identifying the drive type.

Integer

drivesList

lsmID

This parameter identifies the numeric ID of the LSM containing the drive.

Integer

drivesList

driveIsAvailable

This parameter is true if the drive is available.

Boolean (true or false)

drivesList

repackEnabled

This parameter is true if the drive is enabled for repack.

Boolean (true or false)

drivesList

classicEnabled

This parameter is true if the drive is enabled for classic read and write operations.

Boolean (true or false)

 

firstUsedRequestId

This parameter identifies the ID number of the first request processed since the Manager was last started.

Integer

 

lastUsedRequestId

This parameter identifies the ID number of the last request processed.

Integer

 

libStatus

This parameter identifies the current library status. The possible values are as follows:

0: Online

1: Out of Order

2: Unknown

Integer (0 - 2)

lsmList

 

This parameter identifies the list of information about LSMs (Library Storage Modules). The <lsmList> tag repeats for each LSM in the list. The following three parameters are contained in each lsmList entry.

 

lsmList

lsmName

This parameter identifies the configured LSM name.

String (1 - 50 characters)

lsmList

lsmID

This parameter identifies the numeric ID of the LSM.

Integer

lsmList

lsmIsAvailable

This parameter is true if the LSM is available.

Boolean

 

numOfAvailableActors

This parameter identifies the number of running, and available, Actors.

Integer

 

numOfAvailableDisks

This parameter identifies the number of disks Online.

Integer

 

numOfAvailableDrives

This parameter identifies the number of drives Online.

Integer

 

numberOfBlankTapes

This parameter identifies the total number of blank tapes in all tape libraries in DIVArchive.

Integer

 

remainSizeOnTapes

This parameter identifies the total amount of space (in megabytes) remaining on all online tapes, in all tape libraries, in DIVArchive.

Integer

 

siteIpAddress

This parameter identifies the IP address of the DIVArchive Manager.

String

 

siteName

This parameter identifies the configured DIVArchive site name. This is a DIVArchive value and different than the DIVAnet site name.

String

 

sitePort

This parameter identifies the Manager connection port number.

Integer

 

status

This parameter identifies the status of DIVArchive. This integer value is one of the following:

0: On

1: Off

2: Unknown

Integer (0 - 2)

 

totalNumberOfObjects

This parameter identifies the total number of objects in DIVArchive.

Integer

 

totalSizeOnTapes

This parameter identifies the total amount of space (in megabytes) in all online tapes, in all tape libraries, in DIVArchive.

Integer


DIVArchive Status Codes

The following are typical DIVArchive getArchiveSystemInfo() command 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.

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 getArchiveSystemInfo() command:

<p:getArchiveSystemInfo xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:options>1678</p:options>
</p:getArchiveSystemInfo>

REST Response Example

The following is an example of a REST response for a getArchiveSystemInfo() command:

<getArchiveSystemInfoResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd>
<return>
   <p:divaStatus>1000</p1:divaStatus>
   <p:info>
      <p1:actorsDrivesList>
        <p1:actorName>actor_001_std_74ny</p1:actorName>
        <p1:actorAddress>10.15.62.68</p1:actorAddress>
        <p1:actorIsAvailable>true</p1:actorIsAvailable>
        <p1:connectedDrives>0-0-0</p1:connectedDrives>
        <p1:repackEnabled>true</p1:repackEnabled>
        <p1:classicEnabled>false</p1:classicEnabled>
        <p1:cacheArchiveEnabled>true</p1:cacheArchiveEnabled>
        <p1:directArchiveEnabled>true</p1:directArchiveEnabled>
        <p1:cacheRestoreEnabled>true</p1:cacheRestoreEnabled>
        <p1:directRestoreEnabled>true</p1:directRestoreEnabled>
        <p1:deleteEnabled>true</p1:deleteEnabled>
        <p1:copyToGroupEnabled>true</p1:copyToGroupEnabled>
        <p1:associativeCopyEnabled>true</p1:associativeCopyEnabled>
        <p1:cacheForRepack>0</p1:cacheForRepack>
      </p1:actorsDrivesList>
      <p1:actorsDrivesList>
        <p1:actorName>actor_002_std_74ny</p1:actorName>
        <p1:actorAddress>10.15.62.69</p1:actorAddress>
        <p1:actorIsAvailable>true</p1:actorIsAvailable>
        <p1:connectedDrives>0-0-1</p1:connectedDrives>
        <p1:repackEnabled>true</p1:repackEnabled>
        <p1:classicEnabled>false</p1:classicEnabled>
        <p1:cacheArchiveEnabled>true</p1:cacheArchiveEnabled>
        <p1:directArchiveEnabled>true</p1:directArchiveEnabled>
        <p1:cacheRestoreEnabled>true</p1:cacheRestoreEnabled>
        <p1:directRestoreEnabled>true</p1:directRestoreEnabled>
        <p1:deleteEnabled>true</p1:deleteEnabled>
        <p1:copyToGroupEnabled>true</p1:copyToGroupEnabled>
        <p1:associativeCopyEnabled>true</p1:associativeCopyEnabled>
        <p1:cacheForRepack>0</p1:cacheForRepack>
      </p1:actorsDrivesList>
      <p1:capSize>8</p1:capSize>
      <p1:drivesList>
        <p1:driveName>0-0-0</p1:driveName>
        <p1:driveTypeID>9</p1:driveTypeID>
        <p1:driveType>SIMU_LT03</p1:driveType>
        <p1:lsmID>0</p1:lsmID>
        <p1:driveIsAvailable>true</p1:driveIsAvailable>
        <p1:repackEnabled>true</p1:repackEnabled>
        <p1:classicEnabled>true</p1:classicEnabled>
      </p1:drivesList>
      <p1:drivesList>
        <p1:driveName>0-0-1</p1:driveName>
        <p1:driveTypeID>9</p1:driveTypeID>
        <p1:driveType>SIMU_LT03</p1:driveType>
        <p1:lsmID>0</p1:lsmID>
        <p1:driveIsAvailable>true</p1:driveIsAvailable>
        <p1:repackEnabled>true</p1:repackEnabled>
        <p1:classicEnabled>true</p1:classicEnabled>
      </p1:drivesList>
      <p1:firstUsedRequestId>31473</p1:firstUsedRequestId>
      <p1:lastUsedRequestId>33079</p1:lastUsedRequestId>
      <p1:libStatus>0</p1:libStatus>
      <p1:lsmList>
        <p1:lsmName>LSM_0</p1:lsmName>
        <p1:lsmID>0</p1:lsmID>
        <p1:lsmIsAvailable>true</p1:lsmIsAvailable>
      </p1:lsmList>
      <p1:lsmList>
        <p1:lsmName>LSM_1</p1:lsmName>
        <p1:lsmID>65536</p1:lsmID>
        <p1:lsmIsAvailable>true</p1:lsmIsAvailable>
      </p1:lsmList>
      <p1:numOfAvailableActors>3</p1:numOfAvailableActors>
      <p1:numOfAvailableDisks>6</p1:numOfAvailableDisks>
      <p1:numOfAvailableDrives>12</p1:numOfAvailableDrives>
      <p1:numberOfBlankTapes>15998</p1:numberOfBlankTapes>
      <p1:remainSizeOnTapes>225117</p1:remainSizeOnTapes>
      <p1:siteIpAddress>10.15.62.67</p1:siteIpAddress>
      <p1:siteName>local</p1:siteName>
      <p1:sitePort>9005</p1:sitePort>
      <p1:status>0</p1:status>
      <p1:totalNumberOfObjects>3532</p1:totalNumberOfObjects>
      <p1:totalSizeOnTapes>226297</p1:totalSizeOnTapes>
    </ns0:info>
  </return>
</getArchiveSystemInfoResponse>

Source/Destination Information: getSourceDestinationList()

This command returns information regarding all of the configured DIVArchive Source/Destinations. A DIVArchive Source/Destination is a disk or server (for example, an FTP server) that DIVArchive can archive from or restore to.

If the command is issued to DIVAnet, the command returns all DIVArchive Source/Destinations for all sites in the DIVAnet network. The Source/Destination name is prefixed with the site name, and delimited with an underscore. If the -site {site_name} option appears in the options parameter, DIVAnet returns Source/Destination information for only the selected site.

Input Parameters

The following is a list of getSourceDestinationList() command input parameters:

Table 6-3 getSourceDestinationList() Command 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.

options

For this parameter there are no options defined in DIVArchive. In DIVAnet, the -site {site_name} option indicates the site to return the list of Source/Destinations from.

String (0 - 768 characters)


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 6-4 getSourceDestinationList() Command Returned Values

Section Parameter Description Data Type and Default
 

divaStatus

This parameter identifies the DIVArchive status code for the operation.

Integer

arraysInfo

 

This section repeats for each Source/Destination configured in the system. The following table entries describe the parameters for each <arraysInfo> entry.

 

arraysInfo

serversAddress

This parameter identifies the network address of the server or disk.

String

arraysInfo

serversConnectOption

This parameter identifies the DIVArchive connect options (similar to command line options) supplied by default on all requests using the Source/Destination. These options are merged with any options that appear in the request itself.

String

arraysInfo

serversMaxAccess

This parameter identifies the maximum number of concurrent operations from and to the Source/Destination.

Integer

arraysInfo

serversMaxReadAccess

This parameter identifies the maximum number of concurrent read operations from the Source/Destination.

Integer

arraysInfo

serversMaxThroughput

This parameter identifies the maximum throughput to and from the Source/Destination (per request) allowed by DIVArchive. This value is for a single request, and is expressed in megabits per second.

Integer

arraysInfo

serversMaxWriteAccess

This parameter identifies the maximum number of concurrent write operations to the Source/Destination.

Integer

arraysInfo

serversName

This parameter identifies the name of the Source/Destination. DIVArchive uses this name requests.

String

arraysInfo

serversProductionSystem

This parameter identifies the DIVArchive production system name that the Source/Destination belongs to.

String

arraysInfo

serversRootPath

This parameter identifies the Source/Destination root path. This parameter is not relevant for all Source/Destinations.

String

arraysInfo

serversSourceType

This parameter identifies the type of Source/Destination as defined in the configuration.

String


DIVArchive Status Codes

The following are typical DIVArchive getSourceDestinationList() command 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.

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 getSourceDestinationList() command:

<p:getSourceDestinationList xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:options></p:options>
</p:getSourceDestinationList>

REST Response Example

The following is an example of a REST response for a getSourceDestinationList() command:

<p:getSourceDestinationListResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd>
<p:return>
   <p:divaStatus>1000</p:divaStatus>
   <p:arraysInfo>
      <p1:serversAddress>127.0.0.1</p1:serversAddress>
      <p1:serversConnectOption -transfer_timeout 1200 -list_timeout 600</p1:serversConnectOption>
      <p1:serversMaxAccess>10</p1:serversMaxAccess>
      <p1:serversMaxReadAccess>10</p1:serversMaxReadAccess>
      <p1:serversMaxThroughput>100000</p1:serversMaxThroughput>
      <p1:serversMaxWriteAccess>10</p1:serversMaxWriteAccess>
      <p1:serversName>ftp_005_vf</p1:serversName>
      <p1:serversProductionSystem>ps_001</p1:serversProductionSystem>
      <p1:serversRootPath/>
      <p1:serversSourceType>FTP_STANDARD</p1:serversSourceType>
    </p:arraysInfo>
    <p:arraysInfo>
      <p1:serversAddress> </p1:serversAddress>
      <p1:serversConnectOption>-allow_delete_on_source</p1:serversConnectOption>
      <p1:serversMaxAccess>10</p1:serversMaxAccess>
      <p1:serversMaxReadAccess>10</p1:serversMaxReadAccess>
      <p1:serversMaxThroughput>100000</p1:serversMaxThroughput>
      <p1:serversMaxWriteAccess>10</p1:serversMaxWriteAccess>
      <p1:serversName>THA_MOBILE_WK37</p1:serversName>
      <p1:serversProductionSystem>ps_001</p1:serversProductionSystem>
      <p1:serversRootPath>c:\diskSrcDests\THA_MOBILE_WK37</p1:serversRootPath>
      <p1:serversSourceType>DISK</p1:serversSourceType>
    </p:arraysInfo>
<p:/return>
</p:getSourceDestinationListResponse>

Disk Array Information: getArrayList()

This command returns information regarding DIVArchive disk arrays, including which are available, and the used and available space each disk. A DIVArchive disk array is a grouping of one or more physical disks arrays or disks. This command lists the parameters associated with the array, and the parameters for each of the member disks.

If the command is issued to DIVAnet, the command returns all DIVArchive arrays for all sites in the DIVAnet network. The array name is prefixed with the site name delimited with an underscore. If the -site {site_name} option appears in the options parameter, DIVAnet returns array information only for the selected site.

Input Parameters

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

Table 6-5 getArrayList() 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.

options

If you use DIVAnet, and the -site {site_name} option appears in this parameter, DIVAnet returns information for the selected site only.

String (0 - 768 characters)

You can leave this field empty.


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 6-6 getArrayList() Command Returned Values

Section Parameter Description Data Type and Default
 

divaStatus

This parameter identifies the DIVArchive status code for the operation.

Integer

arraysInfo

 

This <arraysInfo> section repeats for each Source/Destination configured in the system. The following table entries describe the parameters for each <arraysInfo> entry.

 

arraysInfo

arrayDesc

This parameter is a description of the array configured in DIVArchive.

String

arraysInfo

arrayName

This parameter identifies the name of the array. This is the media name of an object stored on this DIVArchive array.

String

arraysInfo

mediaFormatId

This parameter identifies the format type of the tapes in this group; either DIVArchive legacy format, or AXF (Archive Exchange Format). The possible integer values are as follows:

0: Legacy - DIVArchive Legacy format

1: AXFv0.9

2: AXFv1.0

Integer (0 - 2)

arraysInfo

numberOfDisk

This parameter identifies the number of disks configured in the DIVArchive array.

Integer

arraysInfo/arrayDiskList

 

This <arrayDiskList> section repeats for each member disk in the DIVArchive array. The following table entries describe each <arrayDiskList> parameter.

List

arraysInfo/arrayDiskList

diskCurrentRemainingSize

The remaining size on disk available to DIVArchive (in MB).

Integer

arraysInfo/arrayDiskList

diskIsWritable

This parameter is true if the disk is writable.

Boolean (true or false)

arraysInfo/arrayDiskList

diskMaxThroughput

This parameter (measured in megabits per second) identifies the maximum configured throughput of the disk. Lower values will place an artificial constraint on disk performance.

Integer

arraysInfo/arrayDiskList

diskMinFreeSpace

This parameter identifies the minimum disk space (in kilobytes) to keep unallocated, as specified by the configuration.

Integer

arraysInfo/arrayDiskList

diskName

This parameter identifies the name of the disk as it is configured in DIVArchive.

String

arraysInfo/arrayDiskList

diskSite

This parameter identifies the DIVArchive site name. This is different from DIVAnet site name. The DIVAnet site name is prepended to the array name.

String

arraysInfo/arrayDiskList

diskStatus

This parameter identifies the overall current status of the disk. This integer value can be one of the following:

0: Unknown

1: Online

2: Offline

3: Not Visible

Integer (0 - 3)

arraysInfo/arrayDiskList

diskTotalSize

This parameter identifies the total disk size in kilobytes.

Long

arraysInfo/arrayDiskList

diskArrayName

This parameter identifies the name of the array to which this disk belongs. This field is currently not populated, but instead will be returned as a nil value.

String


DIVArchive Status Codes

The following are typical DIVArchive getArrayList() 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.

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 getArrayList() request:

<p:getArrayList xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:options></p:options>
</p:getArrayList>

REST Response Example

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

<p:getArrayListResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd>
<p:return>
   <p:divaStatus>1000</p:divaStatus>
   <p:arraysInfo>
      <p1:arrayDesc>AXF two disk example</p1:arrayDesc>
      <p1:arrayName>PROXY_MEDIA005</p1:arrayName>
      <p:mediaFormatId>2</p1:mediaFormatId>
      <p1:numberOfDisk>2</p1:numberOfDisk>
      <p1:arrayDiskList>
         <p1:diskCurrentRemainingSize>873132317</p1:diskCurrentRemainingSize>
         <p1:diskIsWritable>true</p1:diskIsWritable>
         <p1:diskMaxThroughput>100000</p1:diskMaxThroughput>
         <p1:diskMinFreeSpace>0</p1:diskMinFreeSpace>
         <p1:diskName>disk_005_a005</p1:diskName>
         <p1:diskSite>local</p1:diskSite>
         <p1:diskStatus>1</p1:diskStatus>
         <p1:diskTotalSize>1048214524</p1:diskTotalSize>
         <p1:diskArrayName xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
      </p1:arrayDiskList>
      <p1:arrayDiskList>
        <p1:diskCurrentRemainingSize>498093</p1:diskCurrentRemainingSize>
        <p1:diskIsWritable>true</p1:diskIsWritable>
        <p1:diskMaxThroughput>100000</p1:diskMaxThroughput>
        <p1:diskMinFreeSpace>0</p1:diskMinFreeSpace>
        <p1:diskName>disk_006_a005</p1:diskName>
        <p1:diskSite>local</p1:diskSite>
        <p1:diskStatus>1</p1:diskStatus>
        <p1:diskTotalSize>1048214524</p1:diskTotalSize>
        <p1:diskArrayName xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
      </p1:arrayDiskList>
    </p:arraysInfo>
    <p:arraysInfo>
       <p1:arrayDesc>AXF one disk example</p1:arrayDesc>
       <p1:arrayName>SPM_MEDIA002</p1:arrayName>
       <p1:mediaFormatId>2</p1:mediaFormatId>
       <p1:numberOfDisk>1</p1:numberOfDisk>
       <p1:arrayDiskList>
          <p1:diskCurrentRemainingSize>98530985</p1:diskCurrentRemainingSize>
          <p1:diskIsWritable>true</p1:diskIsWritable>
          <p1:diskMaxThroughput>100000</p1:diskMaxThroughput>
          <p1:diskMinFreeSpace>0</p1:diskMinFreeSpace>
          <p1:diskName>disk_002_a002</p1:diskName>
          <p1:diskSite>local</p1:diskSite>
          <p1:diskStatus>1</p1:diskStatus>
          <p1:diskTotalSize>1048214524</p1:diskTotalSize>
          <p1:diskArrayName xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
      </p1:arrayDiskList>
    </p:arraysInfo>
  </p:return>
</getArrayListResponse>

Tape Group Information: getGroupsList()

This command returns information regarding all of the configured DIVArchive tape groups. A DIVArchive tape group is a logical grouping of tape media with similar characteristics. Each DIVArchive object instance belongs to a single tape group. A DIVArchive object instance written to tape has a DIVArchive media name value equivalent to the tape group name. This command returns abbreviated information about each tape group.

If the command is issued to DIVAnet (MultiDIVA mode), the command returns all DIVArchive tape groups for all sites in the DIVAnet network. The group name will be prefixed with the site name and delimited with an underscore. If the -site {site_name} option appears in the options parameter, DIVAnet returns group information only for the selected site.

Input Parameters

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

Table 6-7 getGroupsList() 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.


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 6-8 getGroupsList() Returned Values

Section Parameter Description Data Type and Default
 

divaStatus

This parameter identifies the DIVArchive Status code for the operation.

Integer

groups

 

The <groups> tag repeats for each tape group configured in the system. The following table entries describe the parameters for each <groups> parameter.

List

groups

groupDesc

This parameter is a text description of the tape group as configured in DIVArchive.

String

groups

groupName

This parameter identifies the name of the tape group. This is the media name of an object instance stored in this tape group.

String

groups

mediaFormatId

This parameter identifies the format type of the tapes in this group; either DIVArchive legacy format, or AXF (Archive Exchange Format). The possible integer values are as follows:

0: Legacy - DIVArchive Legacy format

1: AXFv0.9

2: AXFv1.0

Integer (0 - 2)


DIVArchive Status Codes

The following are typical DIVArchive getGroupsList() 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.

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 getGroupsList() request:

<p:getGroupsList xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
</p:getGroupsList>

REST Response Example

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

<p:getGroupsListResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd>
<p:return>
   <p:divaStatus>1000</p:divaStatus>
   <p:groups>
      <p1:groupDesc>Commercial spots 01</p1:groupDesc>
      <p1:groupName>CommercialsSpot01</p1:groupName>
      <p1:mediaFormatId>2</p1:mediaFormatId>
   </p:groups>
   <p:groups>
      <p1:groupDesc>Feature Films with commercials embedded</p1:groupDesc>
      <p1:groupName>FeatureWithSpots04</p1:groupName>
      <p1:mediaFormatId>2</p1:mediaFormatId>
   </p:groups>
<p:/return>
</p:getGroupsListResponse>

Object Information: getObjectInfo()

This command returns detailed object information about a single archived object. The returned information includes the size of the object, file names, and object instances.

If the command is issued to DIVAnet (MultiDIVA mode), the command returns all object instances on all DIVArchive sites. In each object instance, the media name is prefixed with the site name where it exists and is delimited with an underscore. DIVAnet does not synchronize some object information, such as the inserted parameter.

Input Parameters

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

Table 6-9 getObjectInfo() 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.

objectName

This parameter identifies the name of the object. This parameter, along with objectCategory, creates the full formal name of a DIVArchive object.

String (1 - 192 characters)

objectCategory

This parameter identifies the name of the object category. This parameter, along with objectName, creates the full formal name of a DIVArchive object. If this field is empty, and more than one object in DIVArchive matches the objectName, the request will fail.

String (0 - 96 characters)


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 6-10 getObjectInfo() Request Returned Values

Parameter Description Data Type and Default

divaStatus

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

Integer (1000 - 1039)

info

The <info> section contains all of the object information details. One, and only one, instance of this tag exists on a successful call. See Object Detail Parameters for the structure of the information returned within the <info> tag

 

Object Detail Parameters

The following table describes the archived object parameters returned as part of either a getObjectInfo() call or a getObjectDetailsList() call. If you call getObjectDetailsList(), some parameters may not be returned according to the selected detail level specified in the request. See Object Query Information: getObjectDetailsList() for more information.

Note:

Disk-based object instances are named actorInstances in the following parameters table.

Table 6-11 Object Details Parameters (<info> or <objectInfos>)

Section Parameter Description Data Type and Default

actorInstances

 

This section identifies a disk instance (a DIVArchive array). The <actorInstances> tag repeats for each array instance that belongs to the object

 

actorInstances

actor

This parameter identifies the name of the DIVArchive disk array. This is also the media name of the disk-based object instance.

String

actorInstances

instanceID

This parameter identifies number uniquely identifying the instance within an object. This number is not unique across objects.

If DIVAnet is used, each instance has its own instance ID that is unique among all instances on all sites. The DIVAnet instance ID is a projection of (but different than) the DIVArchive instance ID.

Integer (0 - 100,000)

 

archivingDate

This parameter identifies the date and time when the request was received. It is reflected as a UTC value in seconds since January 01, 1970.

Integer

 

filesList

This parameter identifies the list of files contained in the object. Relative paths for the file names are included if the files were archived with relative paths. The <filesList> tag delimits each file, and is repeated for each file in the list. For example:

<filesList>misc/t.txt</filesList>
<filesList>t.mov</filesList>

If the object is complex, the files in the object do not appear. Instead, a single file appears representing the entire object. In this case, call getFilesAndFolders() to iteratively retrieve all of the files and folders within the object.

String (1 - 4000 characters for each file)

 

inserted

This parameter is true if either one of the object instances is a tape instance, and all of the tapes comprising the tape instance are present in a tape library, or a disk instance exists and the disk array is online.

Boolean (true or false)

 

isComplex

This parameter is true if the object is complex. Complex objects can have a million files and many nested folders.

Boolean (true or false)

 

lockStatus

This parameter identifies a code indicating the lock status of the object as follows:

0: Unlocked

1: Locked for restore

Integer (0 or 1)

 

modifiedOrDeleted

This parameter identifies a code indicating the created, modified, or deleted status of the object:

0: Undefined

1: Created or Modified

2: Deleted

Integer (0, 1 or 2)

 

nbFilesInComplexComponent

This parameter identifies the number of actual files in the archived object.

Integer

 

nbFoldersInComplexComponent

This parameter identifies the number of folders present in the archived object.

Integer

 

objectComments

This parameter identifies the user-supplied text regarding the archived object.

String (0 - 4000 characters)

 

objectSizeBytes

This parameter identifies the size of the archived object in bytes. This is defined as the sum total of the size of all files.

Integer

 

objectSize

This parameter identifies the object size in kilobytes.

Integer

 

objectSource

This parameter identifies the DIVArchive Source/Destination name used to archive the object.

String (1 - 96 characters)

objectSummary

 

This section identifies the formal name of the DIVArchive object (the object name plus category).

String

objectSummary

objectName

This parameter identifies the name of the object. This parameter, along with objectCategory, creates the full formal name of a DIVArchive object.

String (1 - 192 characters)

objectSummary

objectCategory

This parameter identifies the name of the object category. This parameter, along with objectName, creates the full formal name of a DIVArchive object.

String (1 - 96 characters)

 

rootDirectory

This parameter identifies the File Path Root within the Source/Destination that was used to archive the object. This value is used as a default on restores if the Restore request contains no File Path Root value.

String

tapeInstances

 

This section identifies the list of tape instances. The <tapeInstances> tag is repeated for each tape instance present in the object.

String

tapeInstances

groupName

This parameter identifies the name of the tape group where the object instance was assigned.

String

tapeInstances

inserted

This parameter is true if all of the tapes comprising the tape instance are present in a tape library.

Boolean (true or false)

tapeInstances

instanceID

This parameter is true if all of the tapes comprising the tape instance are present in a tape library.

Boolean (true or false)

tapeInstances

reqStatus

This parameter identifies a code indicating the current require status of the tape instance:

0: Marked as Required

1: Marked as Releasable

Integer (0 or 1)

tapeInstances/tapeDesc

 

This section identifies a list of tapes. The <tapeDesc> tag is repeated for each tape present in the list. If multiple tapes appear, the object instance is considered spanned.

List

tapeInstances/tapeDesc

externalizationComment

This parameter contains the comment that might have been added to DIVArchive when the tape was ejected from a tape library.

String

tapeInstances/tapeDesc

goingToBeRepacked

This parameter is false unless all instances are going to be repacked.

Boolean (true or false)

tapeInstances/tapeDesc

inserted

This parameter is true if this tape is present in a tape library.

Boolean (true or false)

tapeInstances/tapeDesc

tapeFormatId

This parameter identifies the format type of the tapes in this group. The format can be DIVArchive Legacy format, or AXF (Archive Exchange Format). The possible integer values are as follows:

0: Legacy - DIVArchive Legacy format

1: AXFv0.9

2: AXFv1.0

Integer (0, 1, or 2)

tapeInstances/tapeDesc

vsn

This parameter identifies the tape barcode or VSN (Volume Serial Number). This code uniquely identifies the tape within a DIVArchive system.

String (1 - 96 characters)

 

toBeRepacked

This parameter is false unless all instances are going to be repacked.

Boolean (true or false)

 

uuid

This parameter identifies the UUID (Universally Unique Identifier) assigned to an object when initially created.

When a CopyToNew operation is performed, the UUID from the source object is copied to the target object. Therefore, the UUID in this case cannot be used to uniquely identify an object in DIVArchive.

String


DIVArchive Status Codes

The following are typical DIVArchive getObjectInfo() 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.

1009: Object Does Not Exist

The specified object does not exist in the DIVArchive database.

1010: Name Matches Multiple Objects

More than one object with the specified name exists in the DIVArchive or DIVAnet database.

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 getObjectInfo() request:

<p:getObjectInfo 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:objectCategory>PROD</p:objectCategory>
</p:getObjectInfo>

REST Response Example

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

<getObjectInfoResponse xmlns="http://interaction.api.ws.diva.fpdigital.com/xsd" xmlns:ns0="http://response.model.api.ws.diva.fpdigital.com/xsd" xmlns:ns1="http://model.api.ws.diva.fpdigital.com/xsd">
  <return>
    <p:divaStatus>1000</p:divaStatus>
    <p:info>
      <p1:actorInstances>
        <p1:actor>array_003_legacy_vw</p1:actor>
        <p1:instanceID>1</p1:instanceID>
      </p1:actorInstances>
      <p1:archivingDate>1478282457</p1:archivingDate>
      <p1:filesList>700M</p1:filesList>
      <p1:inserted>true</p1:inserted>
      <p1:isComplex>false</p1:isComplex>
      <p1:lockStatus>0</p1:lockStatus>
      <p1:modifiedOrDeleted>0</p1:modifiedOrDeleted>
      <p1:nbFilesInComplexComponent>1</p1:nbFilesInComplexComponent>
      <p1:nbFoldersInComplexComponent>0</p1:nbFoldersInComplexComponent>
      <p1:objectComments> </p1:objectComments>
      <p1:objectSizeBytes>734003200</p1:objectSizeBytes>
      <p1:objectSize>716800</p1:objectSize>
      <p1:objectSource>ftp_001</p1:objectSource>
      <p1:objectSummary>
        <p1:objectCategory>PROD</p1:objectCategory>
        <p1:objectName>PREPROD_July_Edits4</p1:objectName>
      </p1:objectSummary>
      <p1:rootDirectory>source</p1:rootDirectory>
      <p1:tapeInstances>
        <p1:groupName>group_001_axf</p1:groupName>
        <p1:inserted>true</p1:inserted>
        <p1:instanceID>0</p1:instanceID>
        <p1:reqStatus>0</p1:reqStatus>
        <p1:tapeDesc>
          <p1:externalizationComment/>
          <p1:goingToBeRepacked>false</p1:goingToBeRepacked>
          <p1:inserted>true</p1:inserted>
          <p1:tapeFormatId>0</p1:tapeFormatId>
          <p1:vsn>3L0020</p1:vsn>
        </p1:tapeDesc>
      </p1:tapeInstances>
      <p1:toBeRepacked>false</p1:toBeRepacked>
      <p1:uuid>ba75378c-a8fb-4cf5-8e2e-da4d9b19acd9</p1:uuid>
    </p:info>
  </return>
</getObjectInfoResponse>

Object Query Information: getObjectDetailsList()

This command enables querying the DIVArchive database. It returns multiple archived objects or tape instances that satisfy the query. The call can return only the names of objects satisfying the query, or the same detailed information returned by the getObjectInfo() call. The getObjectDetailsList() call can return information in batches (see the following information in this section).

If the command is issued to DIVAnet (MultiDIVA mode), the command queries each site in turn, and returns a batch of information from each site in a round-robin fashion. In each object instance returned, the media name is prefixed with the site name (where it exists), delimited with an underscore. If the request contains a media value that corresponds to one of the system site names, DIVAnet returns information only from that site.

The getObjectDetailsList() call is meant for queries seeking objects, or tapes, that have had operations performed on them since a given date and time. Object and tape instance details are provided roughly in date and time order (see the following section for ordering details). This call supports the following types of queries:

Object Queries

Enables querying on all archived objects that satisfy a set of criteria. For example, category, media, and date and time. Object Queries focus on events such as object creation and deletion.

Tape Queries

Enables queries specifically on object tape instances, and supports queries on common tape operations such as insert, eject, repack, date and time, and category.

Object Query Modes

You can perform object queries in one of three modes. The number preceding the mode (in the following list) can be used in the objectListType parameter.

Results are returned based on the time an object was created, modified (in terms of number of copies), or deleted. For example, a user queries batches of objects modified in the last 24 hours, and an object was copied twice during that time. It is possible that as the results of the query are retrieved, the same object will appear in two separate batches. The same object will never appear in the same batch.

The three modes for performing queries are as follows:

1: Deleted Since Mode

This query mode returns objects that have been deleted since a specific date and time, indicating that at a specific time the object was either deleted, or an instance was modified, or both.

The results are ordered by the object deletion date and time, or instance deletion date and time, or both. The object name and category are returned (with detail level zero).

As batches of results are returned, you may see the same object returned twice because an object may have several delete operations performed on it throughout its lifetime. That is, several delete and add operations may have occurred.

2: Created Since Mode

This query enables the caller to return objects that have been created since a specific date and time value. If you supply zero for the date and time value, the call returns all objects in the database that satisfy the other query parameters. The results are ordered by the object archive date and time.

3: Modified Since Mode

This query returns objects that have been modified since a specific date and time, indicating that one or more of the following has occurred at a specific time:

  • Object Added

  • Object Deleted

  • Object Exported

  • Object Instance Added

  • Object Instance Deleted

  • Object Instance Exported

The results are ordered by the event time. That is, the object creation or deletion date and time, or instance creation or deletion date and time, or both. The current state of the object at the time of the query is returned.

As batches of results are returned, you may see the same object returned twice because an object may have had several operations performed on it, including deletion, throughout its lifetime. The current state of the object is returned for every event previously listed.

If the object was actually deleted at a certain time, you will not receive all object details (provided you have requested them) for that event. If the object is currently deleted at the time of the query, you will receive no details at all, because the details are no longer available.

Tape Query Event Types

A tape query can be performed according to one or more event types. The valid event types are as follows:

1: Instance Created

This event type returns tape instances that have been created since a specified date and time.

2: Instance Deleted

This event type returns tape instances that have been deleted since a specified date and time.

4: Instance Repacked

This event type returns tape instances that have been repacked since a specified date and time.

8: Instance Ejected

This event type returns tape instances that have had one or more tapes ejected from a tape library since a specific date and time.

16: Instance Inserted

This event type returns tape instances that have had one or more tapes inserted into a tape library since a specific date and time.

Each event type listed has a number. To select multiple events, you add these numbers together, and you enter the resulting number in the objectsListType parameter. For example, a query that returns tape instances that have been created or repacked within a given time would have 5 (the sum of 1: Instance Created + 4: Instance Repacked) as the value for the objectsListType parameter.

The results are ordered by the event date and time.

Batching and List Position

The query is specified in the initial call, and the results are returned in batches. You specify the batch size in the request. You must not specify any listPosition values in the initial query. To get the next batch, take the listPosition value returned from the previous call, and pass it on the next. Keep calling getObjectDetailsList() to receive each batch until you receive an empty list, indicating there are no more objects.

As batches of results are returned, you may see the same object returned twice in the list. This is especially true when Modified Since Mode is used. In this case, an object will be returned in the list for every insert or delete performed during the object's lifetime.

Because the getObjectDetailsList() call is stateless, you must maintain the state of the query by taking the returned list position parameters and passing them in as input on the next call. You must pass all of the returned list position parameters in the order that they were returned.

Continuous Polling for Updates

If you create a query and receive an empty list as a response, you can try the query again later using the returned list position values. A future call will return new objects if updates have been made to DIVArchive. In the query, use the createdSince parameter to get updates on new objects, or the modifiedSince parameter for updates on new or deleted objects or instances. Do not mix the createdSince parameter with modifiedSince, or deletedSince in the same calling sequence.

You can create a query that returns any new updates in the future, even though no objects currently satisfy the criteria. When you create the new query, provide the current time as the value for the initialTime parameter. It is possible that you may receive an empty list on the first response. In this case, you can archive a new object, and then attempt the same query (with the list position you just received) again. The newly archived object, and a new list position value, will be returned.

Input Parameters

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

Table 6-12 getObjectDetailsList() 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.

isFirstTime

You set this value to true when initiating a new query. You set this value to false as you retrieve batches of results from the initial query.

Boolean (true or false)

This field is required.

listPosition

These values mark the position of the returned elements in the list. These values are not specified in the initial call (where isFirstTime=true). The <listPosition> tag is repeated for each string value to be passed in the request. For example:

<listPosition>*str1*</listPosition>
<listPosition>*str2*</listPosition>
<listPosition>*str3*</listPosition>

You take the returned listPosition values from one call, and feed them as input into the request to retrieve the next batch.

This field is optional.

listType

This parameter identifies the type of query being performed as follows:

1: Object List

2: Tape Info List

Integer (1 or 2)

initialTime

This call returns objects and tape instances having events that occur after the initialTime value. This is a UTC value in seconds since January 01, 1970.

Integer

objectsListType

If you are performing an object query (listType=1), use one of the following:

1: Deleted Since

2: Created Since

3: Modified Since

If you are performing a tape instance query (listType=2), select one or more options by adding the numbers together from the following options:

1: Instance Created

2: Instance Deleted

4: Instance Repacked

8: Instance Ejected

16: Instance Inserted

See Object Query Modes for detailed information on these options.

Integer (1 - 32)

maxListSize

This parameter identifies the batch size, or maximum number of objects and tape instances returned in a single call.

Do not rely on the number of items returned to predict the end of the list. There is no guarantee that exactly the specified number items will appear in a batch.

Integer (1 - 1000)

This field is required.

objectName

This parameter identifies the object name being queried. You can use a wildcard in the value.

String

objectCategory

This parameter identifies the DIVArchive object category being queried. You can use a wildcard in the value.

String

mediaName

This parameter identifies the DIVArchive media name being queried. You can use a wildcard in the value.

String

levelOfDetail

There are four levels of detail that can be returned:

0: Object Name and Category

1: Medium - this level adds comments, source path root, and archive date.

2: Component - this level adds object size and file names.

3: All - this level returns all information in getObjectInfo().

The following limitations apply:

  • Deleted Since only works at detail level 0.

  • Tape instance queries only support detail levels 0 and 3.

Integer (0 - 3)


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 6-13 getObjectDetailsList() Return Values

Section Parameter Description Data Type and Default
 

divaStatus

This parameter identifies the DIVArchive status code for the operation.

Integer

objectDetailsList

 

This section contains the list of objects or tapes requested in the query.

 

objectDetailsList

listType

This parameter identifies the type of query being performed as follows:

1: Object List

2: Tape Info List

Integer (1 or 2)

objectDetailsList

siteId

This parameter identifies site name of the DIVArchive system that satisfied the request. If you use DIVAnet, this will correspond to the DIVAnet site name.

String

objectDetailsList

listPosition

This parameter identifies a list of strings that maintain the state of the query. You pass all of these values as input to the next getObjectDetailsList() call to retrieve the next batch. The <listPosition> tag repeats for each element of the list.

 

objectDetailsList/objectInfos

 

This section only appears when an object query has been performed. This tag repeats for each object returned.

See Object Detail Parameters for a full description of the object parameters that appear under the <objectInfos> tag.

 

objectDetailsList/objectTapeInfos

 

This section only appears when a tape instance query has been performed. This tag repeats for each tape instance returned.

The following section describes the parameters within the <objectTapeInfos> tag.

 

Tape Query Returned Values

The following table describes the values returned when performing a tape query. The parameters are repeated for each tape instance returned.

Table 6-14 <objectTapeInfos> Request Returned Values

Section Parameter Description Data Type and Default

objectSummary

 

This parameter identifies the formal name of the DIVArchive object (the object name plus category). This occurs once in the objectTapeInfos structure.

 

objectSummary

objectName

This parameter identifies the name of the object. This parameter, along with objectCategory, creates the full formal name of a DIVArchive object.

String (1 - 192 characters)

objectSummary

objectCategory

This section describes a DIVArchive tape instance. This parameter, along with objectName, creates the full formal name of a DIVArchive object.

String (1 - 96 characters)

tapeInstanceInfo

 

This parameter identifies the tape instance information. This tag occurs once within the <objectTapeInfos> structure.

 

tapeInstanceInfo

req

This parameter indicates the current require status of the tape instance:

0: Marked as Required

1: Marked as Releasable

Integer (0 or 1)

tapeInstanceInfo

reqDate

   

tapeInstanceInfo

instanceID

This parameter is true if all of the tapes comprising the tape instance are present in a tape library.

Boolean (true or false)

tapeInstanceInfo/tapeDesc

 

This section identifies a list of tapes. The <tapeDesc> tag is repeated for each tape present in the list. If multiple tapes appear, the tape instance is considered to be spanned.

 

tapeInstanceInfo/tapeDesc

externalizationComment

This parameter identifies the externalizationComment parameter, and contains the comment that may have been added to DIVArchive when the tape was ejected from a tape library.

 

tapeInstanceInfo/tapeDesc

goingToBeRepacked

This parameter is false unless all instances are going to be repacked.

Boolean (true or false)

tapeInstanceInfo/tapeDesc

inserted

This parameter is true if this tape is present in a tape library.

Boolean (true or false)

tapeInstanceInfo/tapeDesc

tapeFormatId

This parameter identifies the format type of the tapes in this group; either DIVArchive legacy format, or AXF (Archive Exchange Format). The possible integer values are as follows:

0: Legacy - DIVArchive Legacy format

1: AXFv0.9

2: AXFv1.0

Integer (0, 1 or 2)

tapeInstanceInfo/tapeDesc

vsn

This parameter identifies the barcode of the tape, or VSN (Volume Serial Number). This code uniquely identifies the tape within a DIVArchive system.

String (1 - 96 characters)


DIVArchive Status Codes

The following are typical DIVArchive getObjectDetailsList() 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.

1035: Access Denied

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

REST Object Query Request Example

The following is an example of a REST getObjectDetailsList() Object Query request:

<p:getObjectDetailsList xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>9610ff91-8721-4af9-905d-316a60ebdb27</p:sessionCode>
   <p:isFirstTime>1</p:isFirstTime>
   <p:initialTime>1479300291</p:initialTime>
   <!--p:initialTime>0</p:initialTime-->
   <p:listType>1</p:listType>
   <p:objectsListType>2</p:objectsListType>
   <!--1 or more repetitions:-->
   <p:listPosition></p:listPosition>
   <p:maxListSize>3</p:maxListSize>
   <p:objectName>*</p:objectName>
   <p:objectCategory>api</p:objectCategory>
   <p:mediaName>*</p:mediaName>
   <p:levelOfDetail>3</p:levelOfDetail>
</p:getObjectDetailsList>

REST Object Query Response Example

The following is an example of a REST response for an getObjectDetailsList() Object Query request:

<getObjectDetailsListResponse xmlns="http://interaction.api.ws.diva.fpdigital.com/xsd" xmlns:ns0="http://response.model.api.ws.diva.fpdigital.com/xsd" xmlns:ns1="http://model.api.ws.diva.fpdigital.com/xsd">
  <return>
    <ns0:divaStatus>1000</ns0:divaStatus>
    <ns0:objectDetailsList>
      <ns1:listType>1</ns1:listType>
      <ns1:siteID>DIVA</ns1:siteID>
      <ns1:listPosition>1479304660</ns1:listPosition>
      <ns1:listPosition>1</ns1:listPosition>
      <ns1:listPosition>1479305114000</ns1:listPosition>
      <ns1:objectInfos>
        <ns1:actorInstances>
          <ns1:actor>array_002_axf</ns1:actor>
          <ns1:instanceID>0</ns1:instanceID>
        </ns1:actorInstances>
        <ns1:archivingDate>1479300506</ns1:archivingDate>
        <ns1:filesList>101</ns1:filesList>
        <ns1:filesList>102</ns1:filesList>
        <ns1:filesList>103</ns1:filesList>
        <ns1:inserted>true</ns1:inserted>
        <ns1:isComplex>false</ns1:isComplex>
        <ns1:lockStatus>0</ns1:lockStatus>
        <ns1:modifiedOrDeleted>1</ns1:modifiedOrDeleted>
        <ns1:nbFilesInComplexComponent>-1</ns1:nbFilesInComplexComponent>
        <ns1:nbFoldersInComplexComponent>-1</ns1:nbFoldersInComplexComponent>
        <ns1:objectComments> </ns1:objectComments>
        <ns1:objectSizeBytes>33084</ns1:objectSizeBytes>
        <ns1:objectSize>33</ns1:objectSize>
        <ns1:objectSource>ftp_001</ns1:objectSource>
        <ns1:objectSummary>
          <ns1:objectCategory>api</ns1:objectCategory>
          <ns1:objectName>godl-1</ns1:objectName>
        </ns1:objectSummary>
        <ns1:rootDirectory>source</ns1:rootDirectory>
        <ns1:tapeInstances>
          <ns1:groupName>group_005_legacy</ns1:groupName>
          <ns1:inserted>true</ns1:inserted>
          <ns1:instanceID>1</ns1:instanceID>
          <ns1:reqStatus>0</ns1:reqStatus>
          <ns1:tapeDesc>
            <ns1:externalizationComment/>
            <ns1:goingToBeRepacked>false</ns1:goingToBeRepacked>
            <ns1:inserted>true</ns1:inserted>
            <ns1:tapeFormatId>0</ns1:tapeFormatId>
            <ns1:vsn>3L2020</ns1:vsn>
          </ns1:tapeDesc>
        </ns1:tapeInstances>
        <ns1:tapeInstances>
          <ns1:groupName>group_001_axf</ns1:groupName>
          <ns1:inserted>true</ns1:inserted>
          <ns1:instanceID>2</ns1:instanceID>
          <ns1:reqStatus>0</ns1:reqStatus>
          <ns1:tapeDesc>
            <ns1:externalizationComment/>
            <ns1:goingToBeRepacked>false</ns1:goingToBeRepacked>
            <ns1:inserted>true</ns1:inserted>
            <ns1:tapeFormatId>0</ns1:tapeFormatId>
            <ns1:vsn>3L0020</ns1:vsn>
          </ns1:tapeDesc>
        </ns1:tapeInstances>
        <ns1:toBeRepacked>false</ns1:toBeRepacked>
        <ns1:uuid>1a72fb52-6a06-40a5-9380-566c9558d56e</ns1:uuid>
      </ns1:objectInfos>
      <ns1:objectInfos>
        <ns1:archivingDate>1479304660</ns1:archivingDate>
        <ns1:filesList>101</ns1:filesList>
        <ns1:filesList>103</ns1:filesList>
        <ns1:filesList>102</ns1:filesList>
        <ns1:inserted>true</ns1:inserted>
        <ns1:isComplex>false</ns1:isComplex>
        <ns1:lockStatus>0</ns1:lockStatus>
        <ns1:modifiedOrDeleted>1</ns1:modifiedOrDeleted>
        <ns1:nbFilesInComplexComponent>-1</ns1:nbFilesInComplexComponent>
        <ns1:nbFoldersInComplexComponent>-1</ns1:nbFoldersInComplexComponent>
        <ns1:objectComments> </ns1:objectComments>
        <ns1:objectSizeBytes>33084</ns1:objectSizeBytes>
        <ns1:objectSize>33</ns1:objectSize>
        <ns1:objectSource>ftp_001</ns1:objectSource>
        <ns1:objectSummary>
          <ns1:objectCategory>api</ns1:objectCategory>
          <ns1:objectName>godl-2</ns1:objectName>
        </ns1:objectSummary>
        <ns1:rootDirectory>source</ns1:rootDirectory>
        <ns1:tapeInstances>
          <ns1:groupName>group_001_axf</ns1:groupName>
          <ns1:inserted>true</ns1:inserted>
          <ns1:instanceID>0</ns1:instanceID>
          <ns1:reqStatus>0</ns1:reqStatus>
          <ns1:tapeDesc>
            <ns1:externalizationComment/>
            <ns1:goingToBeRepacked>false</ns1:goingToBeRepacked>
            <ns1:inserted>true</ns1:inserted>
            <ns1:tapeFormatId>0</ns1:tapeFormatId>
            <ns1:vsn>3L0020</ns1:vsn>
          </ns1:tapeDesc>
        </ns1:tapeInstances>
        <ns1:toBeRepacked>false</ns1:toBeRepacked>
        <ns1:uuid>0ab3afc5-7a77-4b35-a297-b755e740c41d</ns1:uuid>
      </ns1:objectInfos>
    </ns0:objectDetailsList>
  </return>
</getObjectDetailsListResponse>

REST Tape Query Request Example

The following is an example of a REST getObjectDetailsList() Tape Query request:

<p:getObjectDetailsList xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>0cc686cc-7654-4c02-b747-388edeb0f577</p:sessionCode>
   <p:isFirstTime>true</p:isFirstTime>
   <p:initialTime>0</p:initialTime>
   <p:listType>2</p:listType>
   <p:objectsListType>1</p:objectsListType>
   <!--1 or more repetitions:-->
   <p:listPosition></p:listPosition>
   <p:maxListSize>3</p:maxListSize>
   <p:objectName>*</p:objectName>
   <p:objectCategory>api</p:objectCategory>
   <p:mediaName>*</p:mediaName>
   <p:levelOfDetail>3</p:levelOfDetail>
</p:getObjectDetailsList>

REST Tape Query Response Example

The following is an example of a REST response for a getObjectDetailsList() Tape Query request:

<getObjectDetailsListResponse xmlns="http://interaction.api.ws.diva.fpdigital.com/xsd" xmlns:p="http://response.model.api.ws.diva.fpdigital.com/xsd" xmlns:p1="http://model.api.ws.diva.fpdigital.com/xsd">
  <return>
    <p:divaStatus>1000</p:divaStatus>
    <p:objectDetailsList>
      <p1:listType>2</p1:listType>
      <p1:siteID>DIVA</p1:siteID>
      <p1:listPosition>0</p1:listPosition>
      <p1:listPosition>godl-2</p1:listPosition>
      <p1:listPosition>api</p1:listPosition>
      <p1:objectTapeInfos>
        <p1:objectSummary>
          <p1:objectCategory>api</p1:objectCategory>
          <p1:objectName>700M</p1:objectName>
        </p1:objectSummary>
        <p1:tapeInstanceInfo>
          <p1:req>1</p1:req>
          <p1:reqDate>1478282456</p1:reqDate>
          <p1:instanceID>0</p1:instanceID>
          <p1:tapeDesc>
            <p1:externalizationComment> </p1:externalizationComment>
            <p1:goingToBeRepacked>false</p1:goingToBeRepacked>
            <p1:inserted>true</p1:inserted>
            <p1:tapeFormatId>2</p1:tapeFormatId>
            <p1:vsn>3L0020</p1:vsn>
          </p1:tapeDesc>
        </p1:tapeInstanceInfo>
      </p1:objectTapeInfos>
      <p1:objectTapeInfos>
        <p1:objectSummary>
          <p1:objectCategory>api</p1:objectCategory>
          <p1:objectName>godl-1</p1:objectName>
        </p1:objectSummary>
        <p1:tapeInstanceInfo>
          <p1:req>1</p1:req>
          <p1:reqDate>1479301156</p1:reqDate>
          <p1:instanceID>1</p1:instanceID>
          <p1:tapeDesc>
            <p1:externalizationComment> </p1:externalizationComment>
            <p1:goingToBeRepacked>false</p1:goingToBeRepacked>
            <p1:inserted>true</p1:inserted>
            <p1:tapeFormatId>0</p1:tapeFormatId>
            <p1:vsn>3L2020</p1:vsn>
          </p1:tapeDesc>
        </p1:tapeInstanceInfo>
        <p1:tapeInstanceInfo>
          <p1:req>1</p1:req>
          <p1:reqDate>1479301168</p1:reqDate>
          <p1:instanceID>2</p1:instanceID>
          <p1:tapeDesc>
            <p1:externalizationComment> </p1:externalizationComment>
            <p1:goingToBeRepacked>false</p1:goingToBeRepacked>
            <p1:inserted>true</p1:inserted>
            <p1:tapeFormatId>2</p1:tapeFormatId>
            <p1:vsn>3L0020</p1:vsn>
          </p1:tapeDesc>
        </p1:tapeInstanceInfo>
      </p1:objectTapeInfos>
      <p1:objectTapeInfos>
        <p1:objectSummary>
          <p1:objectCategory>api</p1:objectCategory>
          <p1:objectName>godl-2</p1:objectName>
        </p1:objectSummary>
        <p1:tapeInstanceInfo>
          <p1:req>1</p1:req>
          <p1:reqDate>1479304660</p1:reqDate>
          <p1:instanceID>0</p1:instanceID>
          <p1:tapeDesc>
            <p1:externalizationComment> </p1:externalizationComment>
            <p1:goingToBeRepacked>false</p1:goingToBeRepacked>
            <p1:inserted>true</p1:inserted>
            <p1:tapeFormatId>2</p1:tapeFormatId>
            <p1:vsn>3L0020</p1:vsn>
          </p1:tapeDesc>
        </p1:tapeInstanceInfo>
      </p1:objectTapeInfos>
    </p:objectDetailsList>
  </return>
</getObjectDetailsListResponse>

Object Files and Folders Information: getFilesAndFolders()

This command returns information regarding the files and folders in a DIVArchive archived object. It can return file size, file name (with path offset information if present), and checksum information (if available). It returns information for every file and folder in the archived object.

This command returns information in batches. To traverse the list of files, set the startIndex parameter in the request to 1. In the response, take the nextStartIndex value and pass it as the startIndex in the next getFilesAndFolders() call. You proceed in this manner until the nextStartIndex value you receive becomes negative. This negative value means that you should process any returned entries, but you should not call the method again.

Note:

If you have reached the end of the list, and pass a negative startIndex value to the next call, you will receive an empty list, but also a 1008 error (Invalid Parameter).

This call is available in both DIVArchive and DIVAnet. If you are using DIVAnet (MultiDIVA mode), DIVAnet chooses from which DIVArchive site to retrieve the file and folder information.

You can use the getObjectInfo() call to return the file names of each file in the object, but the following describes why you may want to call getFilesAndFolders() instead:

Folder Information

The getFilesAndFolders() call can optionally return all folders in an object, along with all of the files.

Complex Objects

The getFilesAndFolders() call returns file information for all types of archived objects, including complex objects. The getObjectInfo() call does not return the file names if the object is a complex object.

Batching

The getFilesAndFolders() call returns files in batches, enabling the caller to safely retrieve thousands of files and folders.

Sizes and Checksums

The getFilesAndFolders() call returns the file sizes and checksums for each file in an archived object.

Input Parameters

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

Table 6-15 getFilesAndFolders() 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.

objectName

This parameter identifies the name of the object to provide information on. This parameter, along with category, creates the unique formal name of a DIVArchive object.

String (1 - 192 characters)

category

This parameter identifies the object category of the specified object. This parameter, along with objectName, creates the unique formal name of a DIVArchive object.

String (1 - 96 characters)

startIndex

This parameter identifies a unique file and folder ID referencing the first file or folder to return in the list.

You should set this value to 1 to retrieve the beginning of the list. After retrieving a batch of file and folder entries, pass the returned value of nextStartIndex as the startIndex to retrieve the next batch.

You must not try to increment this value in your program because sometimes there are gaps in the IDs that are returned.

Integer (greater than or equal to 1)

batchSize

This parameter identifies the maximum size of the returned list. You must set this to a value no greater than 1000. Oracle recommends setting the value to 500. This is only a suggestion and may be overridden by the underlying functionality. This parameter does not guarantee that the list will be a certain size.

Integer (1 - 1000)

This field is required.

listType

This parameter specifies what file and folder information is returned. You can select one of the following:

0: Files - file information for all files

1: Folders - folder information for all folders

2: Both Files and Folders

Integer (0, 1 or 2)

This field is required.

options

If you use DIVAnet, -site {site_name} enables the caller to choose which site to pull the file and folder information from.

String (0 - 768 characters)


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 6-16 getFilesAndFolders() Request Returned Values

Section Parameter Description Data Type and Default

objectSummary

 

This section identifies a tag that contains the objectName and objectCategory.

 

objectSummary

objectName

This parameter identifies the name of the object. This parameter, along with objectCategory, creates the unique formal name of a DIVArchive object.

String (1 - 192 characters)

objectSummary

objectCategory

This parameter identifies the object category. This parameter, along with objectName, creates the unique formal name of a DIVArchive object.

String (1 - 96 characters)

 

isComplex

This parameter is true if the object is a DIVArchive complex object. Complex objects can have hundreds of thousands of files, but the file names are not returned using the getObjectInfo() call.

Boolean (true or false)

 

nextStartIndex

After the first call, you use this value as the startIndex input parameter for the following call.

Integer

 

siteName

This parameter identifies the DIVArchive site name. If connected to DIVAnet (in MultiDiva mode), then the DIVAnet site name will be populated.

String

fileAndFolderList

 

This section identifies the list of files, folders, or both, in an archived object. This tag repeats for each drive in the list. The following parameters are contained in each file and folder entry.

List

fileAndFolderList

fileOrFolderName

This parameter identifies the file name (with embedded path information, if present), or the folder name.

String

fileAndFolderList

isDirectory

This parameter is true if the component is a directory.

Boolean (true or false)

fileAndFolderList

sizeBytes

This parameter identifies the size of the file in bytes. This is valid only for files.

Integer

fileAndFolderList

fileId

This parameter identifies a file or folder ID that uniquely identifies the file or folder within the archived object.

Integer

fileAndFolderList

totalNumFilesAndFolders

This parameter identifies the total number of files in the folder (including subfolders). This statistic is only valid for folders that are part of complex objects.

Integer

fileAndFolderList

totalSizeFilesAndFolders

This parameter identifies the total size of all files in the folder (including subfolders). This statistic is only valid for folders that are part of complex objects.

Integer

fileAndFolderList/checksums

 

This section identifies the checksum information for each file. Directories do not have checksums.

Not applicable

fileAndFolderList/checksums

checksumType

This parameter identifies the type of checksum. For example, MD5, SHA1, and so on.

String

fileAndFolderList/checksums

checksumValue

This parameter identifies the value of the checksum in hexadecimal string format. The length of this string varies based on the type of checksum in use.

String

fileAndFolderList/checksums

isGenuine

This parameter is true if the checksum was provided at the time of the archive, and verified as Genuine.

Boolean (true or false)


DIVArchive Status Codes

The following are typical DIVArchive getFilesAndFolders() 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.

1019: End Of List Reached

The end of the list has been reached, and there are no more entries to retrieve.

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 getFilesAndFolders() request:

<p:getFilesAndFolders xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>4eb23590-c5a8-4af9-97c9-9234f1b571cc</p:sessionCode>
   <p:objectName>PREPROD_July_Edits4</p:objectName>
   <p:objectCategory>PROD</p:objectCategory>
   <p:startIndex>1</p:startIndex>
   <p:batchSize>500</p:batchSize>
   <p:listType>2</p:listType>
   <p:options></p:options>
</p:getFilesAndFolders>

REST Response Example

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

<getFilesAndFoldersResponse xmlns="http://interaction.api.ws.diva.fpdigital.com/xsd" xmlns:ns0="http://response.model.api.ws.diva.fpdigital.com/xsd" xmlns:ns1="http://model.api.ws.diva.fpdigital.com/xsd">
  <return>
    <p:divaStatus>1000</p:divaStatus>
    <p:divaFilesAndFolders>
      <p1:objectSummary>
        <p1:objectCategory>SM_tryit</p1:objectCategory>
        <p1:objectName>tryit_does_not_exist</p1:objectName>
      </p1:objectSummary>
      <p1:isComplex>false</p1:isComplex>
      <p1:nextStartIndex>-1</p1:nextStartIndex>
      <p1:siteName>local</p1:siteName>
      <p1:fileAndFolderList>
        <p1:checksums>
          <p1:checksumType>MD5</p1:checksumType>
          <p1:checksumValue>cf975e6243044b95272a29247046c971</p1:checksumValue>
          <p1:isGenuineChecksum>false</p1:isGenuineChecksum>
        </p1:checksums>
        <p1:fileOrFolderName>kiki.tx2</p1:fileOrFolderName>
        <p1:isDirectory>false</p1:isDirectory>
        <p1:fileId>1</p1:fileId>
        <p1:sizeBytes>12</p1:sizeBytes>
        <p1:totalNumFilesFolders>0</p1:totalNumFilesFolders>
        <p1:totalSizeFilesFolders>0</p1:totalSizeFilesFolders>
      </p1:fileAndFolderList>
      <p1:fileAndFolderList>
        <p1:checksums>
          <p1:checksumType>MD5</p1:checksumType>
          <p1:checksumValue>5f75b988ec56974f9f6194ad7a5baf64</p1:checksumValue>
          <p1:isGenuineChecksum>false</p1:isGenuineChecksum>
        </p1:checksums>
        <p1:fileOrFolderName>complex.0004.txt</p1:fileOrFolderName>
        <p1:isDirectory>false</p1:isDirectory>
        <p1:fileId>2</p1:fileId>
        <p1:sizeBytes>4090</p1:sizeBytes>
        <p1:totalNumFilesFolders>0</p1:totalNumFilesFolders>
        <p1:totalSizeFilesFolders>0</p1:totalSizeFilesFolders>
      </p1:fileAndFolderList>
    </p:divaFilesAndFolders>
  </return>
</getFilesAndFoldersResponse>

Request Information: getRequestInfo()

This command returns information about a particular DIVArchive or DIVAnet request, and includes status and error message text. You can call it for requests currently executing, and completed requests. The caller provides the ID of the request (requestNumber). The ID is returned after a content request (for example, archiveObject(), copy(), and so on) is first invoked. The getRequestInfo() call indicates whether the request has completed.

If the command is issued to DIVAnet, then DIVAnet returns the status of the DIVAnet request. DIVAnet creates requests on one, or more, DIVArchive sites to fulfill the DIVAnet request.

Input Parameters

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

Table 6-17 getRequestInfo() 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.

requestNumber

This parameter identifies an ID that uniquely identifies the request. You can monitor the progress of the request by using this ID.

Integer

This parameter is required.


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 6-18 getRequestInfo() Request Returned Values

Section Parameter Description Data Type and Default
 

divaStatus

This parameter identifies the DIVArchive status code for the operation.

Integer (1000 - 1039)

divaRequestInfo

 

This section identifies the tag containing the request information.

Occurs only one time.

divaRequestInfo/abortionReason

 

This section identifies the tag indicating the reason why the request terminated.

Occurs only one time.

divaRequestInfo/abortionReason

code

This parameter identifies a code indicating a possible reason why the request terminated:

0: None

1: Tape Drive

2: Tape - individual tape issue

3: Actor

4: Disk

5: Disk Full

6: Source or Destination

7: Resources

8: Tape Library

9: Input Parameters

10: Unknown

11: Internal Error

Integer (0 - 11)

divaRequestInfo/abortionReason

description

This parameter identifies a text representation of the abortionReason code.

String

divaRequestInfo

additionalInfo

This parameter identifies the an unstructured XML value, encoded as a string, that indicates additional information associated with the request (see the following table entries). This information is not necessarily valid after the request completes.

 

divaRequestInfo

currentPriority

This parameter identifies the current priority of the request on a scale of 0 to 100 (100 is the highest priority). The current priority of the request increases the longer the request waits to be executed.

Integer (0 - 100)

divaRequestInfo/objectSummary

 

This section identifies a tag that contains the objectName and objectCategory associated with the request.

 

divaRequestInfo/objectSummary

objectName

This parameter identifies the name of the object. This parameter, along with objectCategory, creates the full formal name of a DIVArchive object.

String (1 - 192)

divaRequestInfo/objectSummary

objectCategory

This parameter identifies the name of the object category. This parameter, along with objectName, creates the full formal name of a DIVArchive object.

String (1 - 96)

divaRequestInfo

progress

This parameter identifies a value indicating the percentage of the request completed. If multiple transfers are required to process a request (for example, if Verify On Restore was selected), the percentage may reset back to 0 when performing the second transfer. Therefore, a progress of 100 does not necessarily indicate that the request has completed. In addition, -1 may be returned if the request terminated.

Integer (-1, 0 - 100)

divaRequestInfo/repackTapes

 

This section identifies a tag that applies only to Repack requests.

 

divaRequestInfo/repackTapes

destinationTape

This parameter identifies the destination tape to store the repacked information for a repack request.

String (0 - 96)

divaRequestInfo/repackTapes

sourceTape

This parameter identifies the fragmented tape to be repacked for a repack request.

String (0 - 96)

divaRequestInfo

requestNumber

This parameter identifies the ID that uniquely identifies the request.

Integer

divaRequestInfo

requestState

This parameter identifies the overall state of the request. The following states indicate that the request has finished execution:

3: Completed Successfully

4: Aborted

5: Cancelled

11: Partially Aborted

The following states indicate that the request is running, or the state is unknown:

6: Unknown

12: Running

Integer (3 - 12)

divaRequestInfo

requestType

This parameter identifies the type of request issued. Common requests include the following:

0: Archive

1: Restore

2: Delete

5: Copy

7: Restore Instance

8: Delete Instance

13: Partial Restore

Other requests include the following:

3: Eject Tape

4: Insert Tape

6: Copy To New

9: Unknown

10: Automatic Repack

11: On Demand Repack

12: Associative Copy

14: Multiple Restore

15: Transcode Archived

16: Export

17: Transfer Files

18: Automatic Verify Tapes

19: Manual Verify Tapes

Integer (0 - 19)


DIVArchive Status Codes

The following are typical DIVArchive getRequestInfo() 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.

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 getRequestInfo() request:

<p:getRequestInfo xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:requestNumber>1536</p:requestNumber>
</p:getRequestInfo>

REST Response Example

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

<getRequestInfoResponse xmlns=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p="http://response.model.api.ws.diva.fpdigital.com/xsd" xmlns:p1="http://model.api.ws.diva.fpdigital.com/xsd">
<return>
    <p:divaStatus>1000</p:divaStatus>
    <p:divaRequestInfo>
      <p1:abortionReason>
        <p1:code>0</p1:code>
        <p1:description>NoError</p1:description>
      </p1:abortionReason>
      <p1:additionalInfo>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;ADDITIONAL_INFO xmlns="http://www.fpdigital.com/divarchive/additionalInfoRequestInfo/v1.0"&gt;
      &lt;Object&gt;
           &lt;Name&gt;Stress_223&lt;/Name&gt;
           &lt;Category&gt;1000ArchivesBCAST9&lt;/Category&gt;
           &lt;Instances&gt;
                &lt;TapeInstance&gt;
                     &lt;Id&gt;0&lt;/Id&gt;
                     &lt;Tape&gt;
                          &lt;MediaName&gt;3L0022&lt;/MediaName&gt;
                     &lt;/Tape&gt;
                &lt;/TapeInstance&gt;
           &lt;/Instances&gt;
      &lt;/Object&gt;
&lt;/ADDITIONAL_INFO&gt;</p1:additionalInfo>
      <p1:currentPriority>50</p1:currentPriority>
      <p1:objectSummary>
        <p1:objectCategory>1000ArchivesBCAST9</p1:objectCategory>
        <p1:objectName>Stress_223</p1:objectName>
      </p1:objectSummary>
      <p1:progress>100</p1:progress>
      <p1:repackTapes>
        <p1:destinationTape>FD5309</p1:destinationTape>
        <p1:sourceTape>FD5301</p1:sourceTape>
      </p1:repackTapes>
      <p1:requestNumber>1209</p1:requestNumber>
      <p1:requestState>3</p1:requestState>
      <p1:requestType>1</p1:requestType>
    </p:divaRequestInfo>
  </return>
</getRequestInfoResponse>

Partial File Restore Request Information: getPartialRestoreRequestInfo()

This command returns extended information about a particular Partial File Restore request. When a Partial File Restore request is executed, DIVArchive may compute and use offsets that are different than those provided in the request. This command provides a method of obtaining the offsets that were actually used for the Partial File Restore.

This command is available in DIVArchive, but not in DIVAnet (MultiDIVA mode).

Input Parameters

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

Table 6-19 getPartialRestoreRequestInfo() 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.

requestNumber

This parameter identifies the request ID of the Partial File Restore request to obtain information on.

Integer (1 - 10,000,000)


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 6-20 getPartialRestoreRequestInfo() Request Returned Values

Section Parameters Description Data Type and Default
 

divaStatus

This parameter identifies the DIVArchive status code for the operation.

Integer (1000 - 1039)

 

destFile

This parameter identifies the output file name of the Partial File Restore. Relative, or absolute, paths in the file name are not allowed.

If the Partial File Restore results in multiple files being generated (such as audio files), DIVArchive uses the destFile name to assign a name to the audio files.

String (1 - 4000 characters)

This is required for timecode Partial File Restore.

offsetVector

 

This section identifies the actual timecode range for the Partial File Restore. There is no enclosing tag for all of the offsets in this section.

<offsetVector>
   <timeCodeBegin>00:00:00:00
   </timeCodeBegin>
   <timeCodeEnd>00:00:10:00
   </timeCodeEnd>
   <posType>2</posType>
</offsetVector>
<offsetVector>
   <timeCodeBegin>00:00:20:00
   </timeCodeBegin>
   <timeCodeEnd>-1
   </timeCodeEnd>
   <posType>2</posType>
</offsetVector>
 

offsetVector

timeCodeBegin

This parameter identifies the SMPTE timecode value marking the start of the extracted portion. The format is hour:minute:second:frame.

For example, 00:00:04:00 to 00:10:04:00 would denote a 10 minute segment starting 4 seconds in and ending at 10 minutes and 4 seconds.

This parameter is valid only when posType=1.

String (hour:minute:second:frame)

offsetVector

timeCodeEnd

This parameter identifies the SMPTE timecode value marking the end of the extracted portion. The format is hour:minute:second:frame.

This parameter is valid only when posType=1.

String (hour:minute:second:frame)

offsetVector

byteBegin

This parameter identifies the starting byte in the range. The first byte starts at 0.

This parameter is valid only when posType=0.

Integer (-1, 0 or a positive integer)

offsetVector

byteEnd

This parameter identifies the ending byte in the range. The last byte is indicated with a -1 value.

This parameter is valid only when posType=0.

Integer (-1, 0 or a positive integer)

offsetVector

posType

This parameter identifies the type of offset in use:

0: ByteOffset

1: Timecode

Integer (0 or 1)

 

sourceFile

This parameter identifies the source file name within the archived object.

String (1 - 4000 characters)


DIVArchive Status Codes

The following are typical DIVArchive getPartialRestoreRequestInfo() 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.

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 getPartialRestoreRequestInfo() request:

<p:getPartialRestoreRequestInfo xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:requestNumber>1536</p:requestNumber>
</p:getPartialRestoreRequestInfo>

REST Response Example

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

<p:getPartialRestoreRequestInfoResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd xmlns:p2=http://model.api.ws.diva.fpdigital.com/xsd xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <p:return>
      <p1:divaStatus>1000</p1:divaStatus>
      <p1:fileList>
         <p2:destFile>gxf</p2:destFile>
         <p2:offsetVector>
            <p2:byteBegin xsi:nil="true"/>
            <p2:byteEnd xsi:nil="true"/>
            <p2:timeCodeBegin>00:00:40:00</p2:timeCodeBegin>
            <p2:timeCodeEnd>00:00:59:28</p2:timeCodeEnd>
            <p2:posType>1</p2:posType>
         </p2:offsetVector>
         <p2:sourceFile>horseRace.gxf</p2:sourceFile>
         <p2:fileFolder xsi:nil="true"/>
         <p2:range xsi:nil="true"/>
      </p1:fileList>
   </p:return>
</p:getPartialRestoreRequestInfoResponse>

Finished Requests: getFinishedRequestList()

This command returns requests that have finished in the last n seconds. The n value is the initialTime parameter. The command returns a list of requests that completed successfully, and unsuccessfully. The returned information is similar to the output of the getRequestInfo() call. It includes the name of the archived object involved in each request, parameters conveying the status of each request, and additional information.

The command returns requests in batches. The size of each batch is governed by the maxFetch parameter. The returned parameter uniqueId holds the current position in the list. You pass the returned uniqueId value as input to the next getFinishedRequestList() call to retrieve the next batch. The end of the list is reached when an empty list of requests is returned. If you are constantly polling for finished requests, and you do not want to miss requests, you should use an initialTime that is slightly greater than how often you are polling.

Input Parameters

The following is a list of getFinishedRequestList() input parameters:

Table 6-21 getFinishedRequestList() Request Input Parameters

Parameter Description Data Type and Default

sessionCode

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

String (1 - 36 characters)

This parameter is required.

maxFetch

This parameter identifies the maximum number of requests to retrieve in a single call. The recommended setting is 500.

Integer

This parameter is required.

initialTime

This parameter indicates how far back in time to look for finished requests. This value is measured in seconds. This parameter has effect only on the initial call, and not when fetching batches of requests.

On the initial call, if the number 0 is passed, the behavior is different, and all finished requests in the system will be returned.

Integer (0 - 259200; in seconds)

uniqueId

This value should be empty on the first call. If retrieving requests in batches, this parameter should be populated with the uniqueId returned from the previous call.

String


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 6-22 getFinishedRequestList() Request Returned Values

Section Parameter Description Data Type and Default
 

divaStatus

This parameter identifies the DIVArchive Status Code for the operation.

Integer (1000 - 1039)

 

uniqueId

This parameter holds the position in the list when returning requests in batches. You pass this value into the next getFinishedRequestList() call to get the next batch.

String

divaRequestInfo

 

This section contains the request information.

Occurs only one time.

divaRequestInfo/abortionReason

 

This section describes the reason why the request terminated.

Occurs only one time.

divaRequestInfo/abortionReason

code

This parameter identifies a code indicating a possible reason why the request terminated as follows:

0: None

1: Tape Drive

2: Individual Tape Issue

3: Actor

4: Disk

5: Disk Full

6: Source or Destination

7: Resources

8: Tape Library

9: Input Parameters

10: Unknown

11: Internal Error

Integer (0 - 11)

divaRequestInfo/abortionReason

description

This parameter is a text representation of the abortionReason code.

String

divaRequestInfo

additionalInfo

This parameter is an unstructured XML value (encoded as a string) indicating additional information associated with the request (see the following table entries).

The information here is not necessarily valid after the request completes.

 

divaRequestInfo

currentPriority

This parameter identifies the current priority of the request on a scale of 0 to 100 (100 being the highest priority). The current priority of the request increases the longer it waits to be executed.

Integer (0 - 100)

divaRequestInfo/objectSummary

 

This section details the format name of the object (objectName and objectCategory).

Occurs only one time.

divaRequestInfo/objectSummary

objectName

This parameter identifies the name of the object. This parameter, along with the objectCategory, creates the full formal name of a DIVArchive object.

String (1 - 192 characters)

divaRequestInfo/objectSummary

objectCategory

This parameter identifies the object category. This parameter, along with the objectName, creates the full formal name of a DIVArchive object.

String (1 - 96 characters)

divaRequestInfo

progress

The value of this parameter indicates the percentage of the request that is complete. If multiple transfers are required to process a request (for example, if Verify on Restore has been selected), the percentage may reset back to 0 when performing the second transfer.

A progress of 100 does not necessarily indicate that the request has completed.

Integer (-1, 0 - 100)

divaRequestInfo / repackTapes

 

This section only applies to Repack requests.

Occurs only one time.

divaRequestInfo / repackTapes

destinationTape

This parameter identifies (on a repack request) the destination tape to store the repacked information.

String (0 - 96 characters)

divaRequestInfo / repackTapes

sourceTape

This parameter identifies the fragmented tape being repacked.

String (0 - 96 characters)

divaRequestInfo

requestNumber

This parameter identifies the ID that uniquely identifies the request.

Integer

divaRequestInfo

requestState

This parameter identifies the overall state of the request. The following states indicate that the request finished execution as follows:

3: Completed Successfully

4: Terminated

5: Canceled

11: Partially Terminated

The following states indicate that the request is running, or the state is unknown:

6: Unknown

12: Running

Integer (3 - 12)

divaRequestInfo

requestType

This parameter identifies the type of request issued. Common requests include the following:

0: Archive

1: Restore

2: Delete

5: Copy

7: Restore Instance

8: Delete Instance

13: Partial File Restore

Other request types include the following:

3: Eject Tape

4: Insert Tape

6: Copy To New

9: Unknown

10: Automatic Repack

11: On Demand Repack

12: Associative Copy

14: Multiple Restore

15: Transcode Archived

16: Export

17: Transfer Files

18: Automatic Verify Tapes

19: Manual Verify Tapes

Integer (0 - 19)


DIVArchive Status Codes

The following are typical DIVArchive getFinishedRequestList() 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.

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 getFinishedRequestList() request:

<getFinishedRequestList xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:maxFetch>150</p:maxFetch>
   <p:initialTime>34899</p:initialTime>
   <p:uniqueId></p:uniqueId>
</getFinishedRequestList>

REST Response Example

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

<getFinishedRequestListResponse xmlns:p="http://response.model.api.ws.diva.fpdigital.com/xsd" xmlns:p1="http://model.api.ws.diva.fpdigital.com/xsd">
  <return>
    <p:divaStatus>1000</p:divaStatus>
    <p:uniqueId>1489760744000,372</p:uniqueId>
    <p:requestInfoList>
      <p1:abortionReason>
        <p1:code>0</p1:code>
        <p1:description>NoError</p1:description>
      </p1:abortionReason>
      <p1:additionalInfo>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;ADDITIONAL_INFO xmlns="http://www.fpdigital.com/divarchive/additionalInfoRequestInfo/v1.0"&gt;
       &lt;Object&gt;
              &lt;Name&gt;CHANNEL17_EDIT3&lt;/Name&gt;
              &lt;Category&gt;Cat&lt;/Category&gt;
              &lt;Instances&gt;
                     &lt;DiskInstance&gt;
                           &lt;Id&gt;0&lt;/Id&gt;
                            &lt;Disk&gt;
                                  &lt;MediaName&gt;disk_002_a002&lt;/MediaName&gt;
                           &lt;/Disk&gt;
                     &lt;/DiskInstance&gt;
              &lt;/Instances&gt;
       &lt;/Object&gt;
&lt;/ADDITIONAL_INFO&gt;</p1:additionalInfo>
      <p1:currentPriority>40</p1:currentPriority>
      <p1:objectSummary>
        <p1:objectCategory>Cat</p1:objectCategory>
        <p1:objectName>CHANNEL17_EDIT3</p1:objectName>
      </p1:objectSummary>
      <p1:progress>100</p1:progress>
      <p1:repackTapes>
        <p1:destinationTape> </p1:destinationTape>
        <p1:sourceTape> </p1:sourceTape>
      </p1:repackTapes>
      <p1:requestNumber>366</p1:requestNumber>
      <p1:requestState>3</p1:requestState>
      <p1:requestType>13</p1:requestType>
    </p:requestInfoList>
    <p:requestInfoList>
      <p1:abortionReason>
        <p1:code>0</p1:code>
        <p1:description>NoError</p1:description>
      </p1:abortionReason>
      <p1:additionalInfo>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;ADDITIONAL_INFO xmlns="http://www.fpdigital.com/divarchive/additionalInfoRequestInfo/v1.0"&gt;
       &lt;Object&gt;
              &lt;Name&gt;CHANNEL17_EDIT3&lt;/Name&gt;
              &lt;Category&gt;Cat&lt;/Category&gt;
              &lt;Instances&gt;
                     &lt;DiskInstance&gt;
                           &lt;Id&gt;0&lt;/Id&gt;
                           &lt;Disk&gt;
                                  &lt;MediaName&gt;disk_002_a002&lt;/MediaName&gt;
                           &lt;/Disk&gt;
                     &lt;/DiskInstance&gt;
              &lt;/Instances&gt;
       &lt;/Object&gt;
&lt;/ADDITIONAL_INFO&gt;</p1:additionalInfo>
      <p1:currentPriority>40</p1:currentPriority>
      <p1:objectSummary>
        <p1:objectCategory>Cat</p1:objectCategory>
        <p1:objectName>CHANNEL17_EDIT3</p1:objectName>
      </p1:objectSummary>
      <p1:progress>100</p1:progress>
      <p1:repackTapes>
        <p1:destinationTape> </p1:destinationTape>
        <p1:sourceTape> </p1:sourceTape>
      </p1:repackTapes>
      <p1:requestNumber>367</p1:requestNumber>
      <p1:requestState>3</p1:requestState>
      <p1:requestType>13</p1:requestType>
    </p:requestInfoList>
</return>
</getFinishedRequestListResponse>

Storage Plan Information: getStoragePlanList()

This command returns information regarding all of the configured DIVArchive Storage Plans. A DIVArchive Storage Plan is a set of configuration parameters that describe how an archived object is processed (for example, copied, deleted, and so on) during its lifetime in DIVArchive.

If you issue the command to DIVAnet, the command returns all DIVArchive Storage Plans for all sites in the DIVAnet network. The returned Storage Plan name is prefixed with the DIVAnet site name delimited with an underscore. If the -site {sitename} option appears in the options parameter, DIVAnet returns Storage Plan information for the selected site only.

Input Parameters

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

Table 6-23 getStoragePlanList() 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.

options

There are no options defined in DIVArchive. In DIVAnet, the -site option indicates the site to return Storage Plans from.

 

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 6-24 getStoragePlanList() 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)

spList

This tag contains the name of the Storage Plan. The <spList> tag repeats for each Storage Plan configured in the system.

For example:

<spList>SP_001</spList>
<spList>SP_DEFAULT</spList>

List of Strings


DIVArchive Status Codes

The following are typical DIVArchive getStoragePlanList() 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.

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 getStoragePlanList() request:

<p:getStoragePlanList xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd">
   <p:sessionCode>810c85c7-d70c-414e-93a4-655a3e4c89bd</p:sessionCode>
   <p:options></p:options>
</p:getStoragePlanList>

REST Response Example

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

<p:getStoragePlanListResponse xmlns:p=http://interaction.api.ws.diva.fpdigital.com/xsd xmlns:p1=http://response.model.api.ws.diva.fpdigital.com/xsd>
<p:return>
   <p:divaStatus>1000</p:divaStatus>
   <p:spList>SP_001</spList>
   <p:spList>SP_DEFAULT</spList>
</p:return>
</p:getStoragePlanListResponse>