This chapter highlights DIVAnet's DIVArchive API support, and provides information on how to supply DIVAnet specific information using the DIVArchive API. This chapter is intended to be used with either the DIVArchive C++ API, DIVArchive Java API, or the DIVArchive Web Service API documentation.
DIVAnet supports a subset of the full DIVArchive API command set. Some DIVArchive API commands (such as EjectTape) will be rejected in DIVAnet MultiDiva Mode. DIVAnet 2.3.0 does support client connections from DIVArchive API clients releases 7.3 and earlier. Any new features added to the API after 7.3 will not supported by DIVAnet 2.3.0.
Invoking DIVA API calls against a DIVAnet server is largely the same as invoking calls against DIVArchive. However, there are some differences - DIVAnet sometimes accepts the well-known DIVA API parameters in a slightly different way. In addition, the content of fields returned by DIVAnet may be slightly different from DIVArchive, or have a different format. This section highlights those differences.
DIVAnet 2.3.0 requires that connected DIVArchive sites be installed with DIVArchive 7.3.1 or later. DIVArchive sites may then be upgraded independently without requiring an upgrade to DIVAnet.
This section highlights requests that involve the transfer (or deletion) of archived content, including Archive, Restore, Delete, and Copy. These commands can be invoked through the DIVArchive API. Some can also be invoked from the DIVAnetUI. Refer to the Oracle DIVArchive C++ API Programmer's Guide in the Oracle DIVArchive Additional Features documentation library for more information on what each command within the DIVArchive API does.
Note:
In DIVAnet MultiDiva Mode, DIVAnet requests often require a few pieces of information that requests issued directly to DIVArchive do not.DIVAnet requests often require additional information because of the supported functionality. For instance, you can use the Copy command in DIVAnet to copy content from one DIVA system to another. DIVAnet needs to know, at a minimum, what the target site is. However, the DIVA API CopyToGroup command does not contain a target site parameter. The sections below detail how to specify this additional information. For more information on configuring DIVAnet MultiDiva Mode, see Configuring Client API Ports.
Table 7-1 identifies the DIVArchive API Content Requests that are supported by DIVAnet. Clients that issue these requests are provided a Request ID in return, which can periodically query the status of the request.
Table 7-1 Supported DIVArchive Content Requests
| Request | Behavior in DIVAnet |
|---|---|
|
Archive |
Enables digital assets from a Source/Destination (such as FTP or CIFS file system) to be transferred to, and stored in, the local DIVArchive site, or optionally, another chosen site. For more information, see Archive Requests. |
|
Restore Restore Instance |
Enables a DIVAnet object to be restored (transferred) to a Source/Destination (such as FTP or CIFS). You can specify the site and (or) instance to restore, or let DIVAnet choose the best site. DIVAnet decides whether it should (1) restore an object from the local DIVArchive, (2) directly restore an object using a remote DIVArchive, or (3) pull an object from a remote DIVArchive and then transfer it to the chosen Source/Destination. A Restore Instance allows a specific instance at a specific site to be restored. If a failure occurs, you can configure DIVAnet to retry on other sites. For more information, see Restore Requests. |
|
Partial Restore Partial Restore Instance |
Partially restore an object in a manner similar to a full restore. If issuing a partial file restore on a remote system, that DIVA site must be configured for partial restore in a manner similar to the local site. For more information, see Oracle Partial File Restore Requests. |
|
Copy (CopyToGroup) |
Copy content from one DIVA site to another (an Intersite Copy), or create another instance of an object on new media at a DIVA site (equivalent to issuing a A specific instance can be copied to a target site. The For more information, see Copy Requests. |
|
Delete DeleteInstance |
Delete content from all sites, a specific site, or delete a specific instance on a specific site. If objects are locked on sites to be deleted, you can configure DIVAnet to retry for a given time period. For more information, see Delete Requests. |
An Archive request allows the caller to archive content that exists on a particular Source/Destination (configured in DIVArchive). The DIVA API arranges for a transfer to occur from the Source/Destination to DIVArchive. This differs from a web-based cloud API where the content is transferred directly from the requester through HTTPS. By default, DIVAnet archives to the local site.
Archive requests issued to DIVAnet are similar to those directly to DIVArchive, but with a few additions to the Target Sitename - the DIVArchive site where you will archive the content. Normally, DIVAnet will archive to the local site. However, you can archive directly to another site in one of two ways:
By providing the -site {sitename} option in the options field. An example would be -site diva1.
By prefixing a destination sitename to the media parameter in the archive request. For example, sitename1_TapeGroup1 indicates a destination site called sitename1, and a media of TapeGroup1.
DIVAnet does not support continuous retries for Archive commands, but does support a BackupArchiveSite option, which provides an alternate archive site in case the primary site is down.
A Restore request allows the client to restore content that exists in the archive system. The content arrives at the particular Source/Destination chosen in the request. The DIVA API arranges a transfer from a DIVArchive site directly to a Source/Destination (such as FTP or CIFS disk). This differs from a web-based cloud API where the content is transferred directly to the requester through HTTPS.
When restoring content using DIVAnet, the caller need not know which particular DIVA system has the content. And if failures occur retrieving content from one DIVA site, another DIVA site can automatically be consulted to retrieve the content.
DIVAnet supports restoring to any Source/Destination on any DIVAnet site. DIVAnet will retrieve content from other sites as needed to satisfy the request, ultimately transferring the content to the target Source/Destination.
Restore requests issued to DIVAnet are similar to those issued directly to DIVArchive, but with a few additions. Normally, DIVAnet chooses the best site to restore from. However, DIVAnet enables a client to specify the specific site to use for the restore. There are several ways this can be done:
-site: Normally, DIVAnet will choose the site from which to restore. However, you can attempt a restore from a particular site by providing the -site [sitename] option in the options field of the request. If in fact the content is not located at the chosen site, the operation will fail.
Instance Id: If you need complete control over the source, you can provide an instance number in the restore request. This will allow you to choose the source site, and the DIVA instance to restore from (see the following section). This instance id can be obtained by performing a getObjectInfo() API call, or by viewing the object in DIVAnet UI.
In both of these cases, retries are disabled.
To satisfy a restore request, DIVAnet uses the restore methods in Table 7-2. DIVAnet will dynamically select which restore workflow to use based on parameters such as the target Source/Destination and the source object. To decide which site to use for restores, DIVAnet asks a series of questions, including:
Is the object available on the local DIVArchive System?
Does the object have a disk instance?
Is the Source/Destination accessible from the remote DIVArchive System?
Is the Source/Destination accessible from the local site?
Is DIVArchive running on the source or target sites?
Is one site preferred over another in the configuration file?
Table 7-2 DIVAnet Restore Methods
| Method | Description |
|---|---|
|
Local |
Used when an object exists on the local site. The local site is the DIVArchive System sitename to which you are sending messages. A local DIVArchive System is also considered part of the local site. |
|
Direct Remote |
DIVAnet can arrange to have a remote DIVA system perform a restore operation. It will do this only if the target Source/Destination is also configured in the remote DIVA system. The Source/Destination names must match, and they must both refer to the same server or disk (and path on that disk, if applicable). When available, DIVAnet prefers this method over performing a Restore using Intersite Copy. |
|
Using Intersite Copy |
If content is not local, and if a remote DIVA system cannot directly restore to the target Source/Destination, DIVAnet can arrange for the content to be delivered in two hops. First, the remote DIVA restores to a Source/Destination shared between the source and target sites. Then, the local DIVA will archive the object, and finally, restore to the target Source/Destination. This way future requests for the content will be retrieved much quicker. If it is desired to always perform remote restores by creating a nearline copy, set |
|
Using Intersite Transfer |
In certain cases, when DIVAnet is not able to perform a direct remote restore, DIVAnet will deliver the content in two hops (as Restore using Intersite Copy) but will not actually archive the content locally. One such case involves Oracle Partial File Restore. First, DIVAnet will instruct the source DIVA to transfer the content to the Source/Destination accessible by both the source and target DIVA sites. Then, the local DIVA site will transfer the content to the target Source/Destination without archiving it. |
DIVAnet will allow you to restore to a Source/Destination that is available on any site. DIVAnet assumes that if a Source/Destination exists with the same name on two sites, both configurations point to the same physical Server\Device\Path. Users must be careful with the names that are assigned to Source/Destinations across the sites.
If a remote DIVA system cannot directly restore to the target Source/Destination, DIVAnet can arrange for the content to be delivered in two hops (see Restore Using Intersite Transfer). DIVAnet will arrange this only if the Source/Destination is the preferred site for the particular Source/Destination (see Preferred Source/Destination Mappings).
You can configure the Restore command to retry several times if the first restore fails. If the content to be restored exists on multiple sites, DIVAnet will automatically retry the restore with those sites. You can configure the maximum number of retries. In some cases, DIVAnet will decide to retry with the same site before moving on to other sites. In this case, DIVAnet will examine the RestoreRetryIntervalMins value to determine how long to wait before retrying with the same site.
DIVAnet 2.3.0 supports a subset of the DIVArchive API. Refer to this chapter for a list of the supported messages.
DIVAnet 2.3.0 has limited support for Multi Restore. DIVAnet does not allow Multi Restores for remote Source/Destinations, and does not allow viewing or monitoring of multiple Source/Destinations through the UI. Multi Restore can be used if the object exists locally, but cannot be accessed (for example, it has been externalized locally).
DIVAnet 2.3.0 does not support peer-to-peer site relationships, including load balancing.
In addition to full restores of content, DIVAnet also supports Partial File Restores. DIVAnet determines the site where the content is located, and arranges to have the portion restored.
If an object exists on a remote DIVA system, and the target Source/Destination for the restore is not accessible by a remote DIVA system, DIVAnet transfers the content in two steps - first using the remote DIVA to get the content to the local DIVA (without transferring the entire object), and then using the local DIVA to restore the content to the target Source/Destination.
As with restore, you can specify the instance number or -site parameter to perform a restore from a specific site, or specify retries when the initial site fails. And also as with restore, restoring to multiple destinations within the same restore request is not supported.
A Copy request creates a new instance of archived content from an existing instance. DIVAnet allows content to be copied from one DIVA site to another. The DIVArchive API CopyToGroup command (1) copies an object from one DIVA site to another, or (2) simply creates a new instance on a single site. For copies, DIVAnet needs to derive some parameters that are not available in the DIVA API. Table 7-3 describes these parameters.
Table 7-3 DIVAnet Copy Derived Parameters
| Derived Attribute | Description |
|---|---|
|
Target Sitename |
Indicates which site the object should be copied to. Target sitename does not exist as an architected field in the DIVA API. You can convey this to DIVAnet in one of two ways:
If you specify no sitename, the local site will be assumed. The -site keyword will work only with an API release 7.3 or greater. |
|
Media |
Media indicates the type of media to use to store the copied object. DIVAnet also enables providing a DIVA Storage Plan as a media name. Storage Plan will work only if the copy is an intersite copy. You can prefix the target sitename to the media to indicate the target sitename as well. If you are not sure which media to provide, you can provide a media of any to let the system choose which media to store to on the target site. For example, a media of diva1_any copies to site diva1, but DIVAnet chooses the media. The default that DIVAnet provides may not be appropriate for some use cases. If the object is already on the target site, and any is specified, the system will simply return success. |
|
Source Sitename |
Normally, DIVAnet will choose the site to copy from. However, if you need complete control over the source, you can provide an instance number in the copy request. This implicitly enables choosing the source site, and which DIVA instance to copy from (see the following section). This id can be obtained by performing a |
In a DIVAnet Copy request, if the source site is the same as the target site, DIVAnet can simply issue a CopyToGroup to the target DIVA site. For intersite copies, DIVAnet enables configuring the method used to perform these copies. For each source and target sitename pair (for example, site1 to site2), Table 7-4 lists the available transfer methods.
In addition to the copy method, each source and target sitename pairing contains the actual Source/Destinations used for the common storage area. The default destination media (for RestoreAndArchive), options parameters (passed to DIVArchive), and other parameters are also configurable.
Table 7-4 Site-to-Site Copy Methods
| Type | Description |
|---|---|
|
RestoreAndArchive |
With this option, DIVAnet restores content from the source site, to a Source/Destination that is common to the source and target sites. Then, DIVAnet instructs the target DIVArchive System to archive the content now in the common storage area. This is an alternative to using Drop Folders. |
|
RestoreAndMonitor |
Using this method, DIVAnet will perform the copy by first restoring the content to a specific destination. DIVAnet will then turn to monitoring the target DIVArchive system to determine when the content is successfully archived on the target site. The request will successfully complete only when the content is successfully archived on the target site. This of course relies on another process or program that will take the content and archive it into the target DIVA system. This option is useful in combination with DIVArchive Drop Folder Monitor software (DFM). Each DFM folder is configured to archive using a preselected media - meaning that when DFM is employed for copies, the media parameter is effectively ignored. |
|
Restore |
Using this method, DIVAnet will perform the copy by restoring to a specific destination, and then returning success. This method does not Confirm that the content has been successfully archived into the target site, and will likely cause failures if Restore Using Intersite Copy workflows are attempted. |
The DIVAnet Copy command will return success if an instance of the object already exists in the target site on the requested media. DIVArchive will terminate the request in this case.
If an object is requested to be copied to a site where the object already exists, but does not have the requested media, DIVAnet will create another instance of the object on that site using the media specified in the request. The exception to this is if any is supplied as the media. In this case, DIVAnet will not create another instance.
In DIVAnetUI, there is an option to have DIVAnet assign the target media on a Copy operation (use a media of Selected By DIVAnet). You can accomplish the same thing in a DIVA API request by specifying a media of any in the Copy request. DIVAnet will use its configuration to determine which media to use for the copy (see Site-to-Site Mappings for more information).
When any is passed, and the object already exists on the target site, DIVAnet will not create another instance of the object. No further action will be taken, and the request will succeed.
DIVAnet also supports periodic retries on copies. If enabled in the Workflow Profile, DIVAnet will retry copy operations that failed. In the Workflow Profile, you can configure how long DIVAnet will retry the request, and the wait period between retries. See Configuring Workflow Profiles for more information.
A DIVArchive Delete request allows the caller to remove an archived object. A DIVAnet Delete request, by default, will delete the object from all DIVArchive sites. A DIVAnet DeleteInstance request can delete one or all instances from a single DIVA site. So in reality, DIVAnet can perform three kinds of deletes. Table 7-5 describes the delete types and parameters they require.
| Type | Derived Attributes | Description |
|---|---|---|
|
Global Delete |
NA |
Deletes all object instances on all sites. In the API, not specifying a media or instance id in the request will cause the specified object to be deleted from all sites. |
|
Instance Delete |
Target Sitename |
Deletes a single object instance on a particular site. In the API, specify an instance id or a media to delete a specific object instance from a specific site. If you specify an instance id, you are targeting a specific instance on a specific site. Passing media or options parameters are not necessary. If you specify a media, DIVAnet needs to know the site you would like to delete from. You can specify the site in one of three ways:
|
|
Site Delete |
Target Sitename |
Deletes all instances of an object residing on a particular site. This can be accomplished in one of three ways:
|
As mentioned in the previous table, if a sitename is supplied and a media of any, this will cause all instances of the object to be deleted from the selected site. This can also be accomplished by passing -site [sitename] in the options field.
DIVAnet will not allow an Instance Delete to succeed when attempting to delete the last instance of an archived object (the last instance that exists in the DIVAnet database, that is). In this case a Global Delete or Site Delete request will need to be issued. Note however that a Site Delete will allow the last instance or instances to be deleted! You can use Access Rules to protect against Instance Deletes or Site Deletes that are effectively Global Deletes (see Access Rules for more information).
Also, if a user issues a delete directly to DIVArchive, there may be a time window where DIVAnet cannot ensure that the last instance is preserved.
If a Delete is received by DIVAnet, and DIVAnet is currently performing an Intersite Copy of the object, the DIVAnet request that spawned the copy will be canceled. The copy could be the result of a Copy command, or, it could be the result of a Restore command that performs a copy to satisfy the restore. Other types of DIVAnet requests will not be canceled.
If a DIVArchive request is being executed on behalf of a DIVAnet request, DIVArchive locks the object and prevents it from being deleted. So, if an object is locked before DIVAnet can send a delete message to DIVArchive, the delete request will fail.
DIVAnet supports periodic retries on deletes when deletes fail. If enabled in the Workflow Profile, DIVAnet will keep trying to delete on sites where (for example) instances/objects to be deleted are locked. You can configure within DIVAnet how long to retry.
Table 7-6 identifies DIVArchive API commands that do not specifically process or transfer archived content. These commands obtain information about objects or requests and are not assigned a request ID.
Table 7-6 Other Supported DIVArchive Commands Not Related to Content
| Request | Description | Behavior in DIVAnet |
|---|---|---|
|
|
Cancel a DIVAnet request. |
The -site option does not apply for this command. |
|
|
Use the DIVAnet Database to get information about an archived object. DIVAnet returns all instances of the object on all DIVAnet sites. You provide the Object Name and Object Category (you can leave the Category blank, but if multiple objects have the same Object Name, the call will fail). DIVAnet uses the DIVAnet database to return information about the archived object. In the |
The -site option is not supported for this command. |
|
|
Retrieve information regarding a DIVAnet request from the DIVAnet database. Note: The Additional Information parameter has limitations. The additional information is provided by DIVArchive and represents information from the last DIVA request processed. The information does not reflect the other sites in the DIVAnet network. |
When DIVAnet receives a The -site option does not apply for this command. |
|
|
Retrieve information directly from DIVArchive about the files and folders within a particular archived object. |
Accepts the -site option to query a specific site, or no site to let DIVAnet choose (recommended). |
|
|
Retrieve information from DIVArchive regarding objects and object events. DIVAnet retrieves the object information directly from each DIVArchive system one site at a time, in a round-robin fashion, one batch per site. Each batch contains information from one DIVA site. If the same object exists on two sites, you will receive the object twice (once for each site), once in each batch. Note: The order of the returned entries is not guaranteed. If one DIVA site is down, |
You can retrieve information from one site by prefixing the sitename to the media field separated with an underscore (_). If you do not want to query on media, but still want to retrieve information from one site, you can supply just the sitename in the media field. This command does not accept the -site option. |
|
|
Queries the DIVAnet Database to get a list of Object Name and Categories ( |
There is limited support for this command within DIVAnet. Tape information queries are not supported; and there are limits on number of simultaneous queries. The -site option is not supported. |
|
|
Returns a List of Array Names from all sites including the disks that form each array, and returning the current disk capacities. |
The -site parameter, passed in the options field, can return information for a specific site. |
|
|
Returns a list of Tape Group Names from all sites. The sitename is prefixed to the Group Name. |
Note: This command does not have an options field. As a result, the -site options is not supported. |
|
|
Returns a list of Source and Destination information from all sites. |
In the returned list, the sitename of the Source or Destination is prefixed to the Source or Destination name separated by an underscore (_). The -site parameter, passed in the options field, can return information for a specific site. |
|
|
Retrieves the status of a single DIVArchive site (by default, the local site is returned). It does not return a global view of all sites. |
The -site parameter, passed in the options field, selects which site to gather information from. For example, -site diva1 will route the |
|
|
Retrieves the list of storage plans that are defined in all configured DIVArchive sites. |
In the returned list, the sitename of the Storage Plan is prefixed to the Storage Plan name, separated by an underscore (_). The -site parameter, |
|
|
The DIVArchive AMC product uses calls (for internal use only). The workflows supported in this release are limited to those where all desired DIVArchive AMC objects exist on the local site. Replicas of the content can exist and be restored from other sites. |
DIVAnet invokes these commands on the local site. If the local site is down, |
For application compatibility reasons, these commands will always return success, even though DIVAnet will take no action to satisfy them.
Change Priority
Lock Object
Unlock Object
Link Objects
Require Instance
Release Instance
DIVAnet returns status codes that are similar to what DIVArchive returns. However, DIVAnet will sometimes accept requests that DIVArchive would fail immediately, because DIVAnet often does not have the information needed to perform checking until later during request processing.
In addition, DIVAnet will return the ACCESS_DENIED status for many commands. This status is not returned by DIVArchive. DIVAnet will reject requests that do not pass Access Rules checks, and rejects messages not configured in the WorkflowProfile. For compatibility purposes, API release 5.8 and earlier return INVALID_PARAMETER status instead of ACCESS_DENIED.