This chapter discusses connection management, requests, and commands.
The following three sections describe the commands used to control the session connection.
Returns the string pointed to by version of the major part of the release number.
Opens a connection with the DIVArchive Manager. All of the other API functions are only available when a connection is open. A connection cannot be opened if another connection is already open. To open a new connection, the previous one must be explicitly closed by calling DIVA_disconnect().
#include "DIVAapi.h"
DIVA_STATUS DIVA_connect (
IN string managerAddress,
IN int portNumber
);
DIVA_STATUS DIVA_connect (
IN string managerAddress,
IN int portNumber,
IN string userName,
IN string password,
IN string applicationName
);
DIVA_STATUS DIVA_connect (
IN string managerAddress,
IN int portNumber,
IN string userName,
IN string password,
IN string applicationName
IN string userInfo
);
managerAddressThe IP address of the DIVArchive Manager.
portNumberThe port on which the DIVArchive Manager is listening. The default port is pointed to by the constant value DIVA_MGER_DEFAULT_PORT.
userNameThe user name.
passwordThe password associated with the user name.
applicationNameThe name of the application.
userInfoUser specific and specified information.
Multithreaded Applications:
A critical section protects both the DIVA_connect() and DIVA_disconnect() functions. If a thread is already in the process of closing the connection to the DIVArchive Manager, other threads must wait until the running thread exits the DIVA_connect() function before being able to open or close the connection.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
The DIVArchive system is no longer able to accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
There was a problem when establishing a connection with the specified DIVArchive system.
The release levels of the API and the Manager are not compatible.
A connection is already open.
Also see "DIVA_disconnect".
Closes a connection with the DIVArchive Manager. When a connection is closed, only the DIVA_connect() function can be called. If no connection is currently open, this function has no effect and returns DIVA_OK.
A critical section protects both the DIVA_connect() and DIVA_disconnect() functions. If a thread is already in the process of closing the connection to the DIVArchive Manager, other threads must wait until the running thread exits the DIVA_disconnect() function before being able to open or close the connection.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
There was a problem when disconnecting. The connection is considered to still be open.
Also see "DIVA_connect".
The following sections discuss all of the available API commands for use in your application.
This function adds a new group.
#include "DIVAapi.h" DIVA_STATUS DIVA_addGroup ( IN DIVA_STRING groupName, IN int associatedSet, IN DIVA_STRING comment, IN bool toBeRepacked, IN bool worstFitEnabled, IN int worstFitRepackTapes, IN int mediaFormatId );
groupNameThe name of the group to be added.
associatedSetThe DIVArchive set of tapes to associate with the new group. This value must be strictly greater than zero.
commentA text description of the new group.
toBeRepackedIf true, tapes belonging to this group are eligible for automatic repacking.
worstFitEnabledIf true, Worst Fit Policy (access speed optimization) will apply.
worstFitRepackTapesThe number of tapes reserved for Worst Fit Repacking.
mediaFormatIdThe data format to be used by the tapes assigned to this group. The value can be DIVA_MEDIA_FORMAT_LEGACY or DIVA_MEDIA_FORMAT_AXF. See information on media formats in the "Glossary".
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system can no longer accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. You set the timeout duration using the DIVA_API_TIMEOUT variable. The default value is one hundred-eighty (180) seconds.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The specified group already exists.
Submits an archive request to the DIVArchive Manager. This function returns as soon as the Manager accepts the request. The application must call the function DIVA_getRequestInfo() to check that the operation completed successfully.
#include "DIVAapi.h" DIVA_STATUS DIVA_archiveObject ( IN DIVA_STRING objectName, IN DIVA_STRING objectCategory, IN DIVA_STRING source, IN DIVA_STRING mediaName, IN DIVA_STRING filesPathRoot, IN vector<DIVA_STRING> filenamesList, IN DIVA_ARCHIVE_QOS qualityOfService, IN int priorityLevel, IN DIVA_STRING comments, IN DIVA_STRING archiveOptions, OUT int requestNumber );
The name of the object to be archived.
The category of the object to be archived.
The name of the source (for example, the video server, browsing server, and so on). This name must be known to the DIVArchive configuration description.
The tape group or disk array where the object is to be saved. The media may be defined as follows:
Provide the tape group or disk array name as defined in the configuration. The object is saved to the specified media and assigned to the default Storage Plan (SP).
Provide a Storage Plan Name (SP Name) as defined in the configuration. The object will be assigned to the specified Storage Plan and saved to the default media specified.
The object is saved to the specified media as in Name, and assigned to the specified Storage Plan as in SP Name. The Name and the SP Name must be separated by the & delimiter (this is configurable).
When this parameter is a null string, the default group of tapes called DEFAULT is used. Complex objects can only be saved to AXF media types.
The root folder for the files specified by the filenamesList parameter.
List of file path names relative to the folder specified by the filesPathRoot parameter. Path names must be absolute names when the filesPathRoot is null.
The following is for DIVArchive releases 7.1.2 and later only:
If the -gcinfilelist option is specified the Genuine Checksum is included with a colon separator between the file name and the GC value as follows:
test1.txt:a6f62b73f5a9bf380d32f062f2d71cbc test2.txt:96bf41e4600666ff69fc908575c0319
One of the following codes:
Archiving is performed according to the default Quality Of Service (currently direct and cache for archive operations).
Use cache archive only.
Use direct archive only - no disk instance is created.
Use cache archive if available, or direct archive if cache archive is not available.
Use direct archive if available, or cache archive if direct archive is not available.
Additional and optional services are available. To request those services, use a logical OR between the previously documented Quality Of Service parameter and the following constant:
Delete source files when the tape migration is done. Available for local sources, disk sources, and standard ftp sources. This feature is not available for complex objects.
The priority level for this request. The priorityLevel can be in the range zero to one hundred, or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred the highest priority.
There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred, or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
Optional information describing the object. This can be a null string.
Additional options for performing the transfer of data from the source to DIVArchive. These options supersede any options specified in the DIVArchive configuration database. Currently the possible values for archiveOptions are as follows:
A null string specifies no options.
Using -r specifies that every name in filenamesList that refers to a folder must be scanned recursively. This also applies when FilesPathRoot is specified and an asterisk designates the files to be archived. This option can be used when archiving from a local source or from a standard FTP Server.
A user name and password is required to log in to some sources. This option obsoletes the -gateway option from earlier releases.
The password used with -login.
The following is for DIVArchive releases 7.1.2 and later only:
Specifies that Genuine Checksum (GC) values are included in the file names list. The value of gcType must match the Manager's default checksum type as specified in the DIVArchive configuration (MD5 by default). The GC values are then used to verify the transfer from the source.
The request number assigned to this request. This number is used for querying the status or canceling the request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
DIVArchive can no longer accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. You set the timeout duration using the DIVA_API_TIMEOUT variable. The default value is one hundred-eighty (180) seconds.
An unknown status was received from the DIVArchive Manager.
The DIVArchive Manager or DIVArchive API detected an internal error.
The DIVArchive Manager did not understand a parameter value.
The count of simultaneous requests reached the maximum allowed value. You set this variable in the manager.conf configuration file. The default value is three hundred.
The specified tape group or disk array does not exist.
The specified Source/Destination is unknown by the DIVArchive system.
Submits a request for creating new instances in the group (specified by group). DIVArchive guarantees that these instances are stored sequentially on tapes:
The request is completed only when every object is copied to the same tape.
In the case of drive or tape failure during a write operation, instances currently written are erased and the request is retried once.
The choice of the tape to be used for the copy follows the policy used for the archive operation (written tapes with enough remaining size regardless of optimizations).
Associative Copy does not span tapes - the request terminates (and is retried once) instead of spanning. The request terminates if the sum of the size of the objects to copy exceeds the capacity of every individual tape present in the library.
#include "DIVAapi.h" DIVA_STATUS DIVA_associativeCopy ( IN vector<DIVA_OBJECT_SUMMARY> *objectsInfo, IN DIVA_STRING groupName, IN int priorityLevel, IN DIVA_STRING options, OUT int *requestNumber );
A pointer to a list of objects defined by a name and category pair.
The name of the group where the new instance will be located. Complex objects can only be saved to AXF media types. Associative Copy to a disk array is not available.
The level of priority for this request. The priorityLevel can be in the range zero to one hundred or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred is the highest priority.There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
An optional string attribute for specifying additional parameters to the request.
A number identifying the request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system is no longer able to accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The count of simultaneous requests reached the maximum allowed value. This variable is set in the manager.conf configuration file and the default value is three hundred.
The specified object does not exist in the DIVArchive database.
More than one object with the specified name exists in the DIVArchive database.
No available instance for this object. Tape instances are ejected and no DIVArchive Actor could provide a disk instance.
The specified tape group or disk array does not exist.
The object is currently in use (being archived, restored, deleted, and so on).
The specified object has instances that are partially deleted.
Also see "DIVA_archiveObject" and "DIVA_copyToGroup and DIVA_copy".
Submits a Cancel operation to the DIVArchive Manager. This function returns as soon as the Manager accepts the operation. The application must call the function DIVA_getRequestInfo() to check that the operation was successful.
#include "DIVAapi.h" DIVA_STATUS DIVA_cancelRequest ( IN int requestNumber, IN DIVA_STRING options );
A number identifying the request to be canceled. This parameter can be set to DIVA_ALL_REQUESTS to cancel all cancellable requests.
An optional string attribute for specifying additional parameters to the request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
The requestNumber identifies no request.
Also see "DIVA_getRequestInfo".
Submits a Change Request Priority request to the DIVArchive Manager. This function returns as soon as the Manager accepts the request. The application must call the DIVA_getRequestInfo() function to check that the operation was successful.
#include "DIVAapi.h" DIVA_STATUS DIVA_changeRequestPriority ( IN int requestNumber, IN int priorityLevel, IN DIVA_STRING passThruOptions );
A number identifying the request to be changed.
The level of priority for this request. The priorityLevel can be in the range zero to one hundred. The value zero is the lowest priority and one hundred is the highest priority.There are five predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
The use of DIVA_DEFAULT_REQUEST_PRIORITY is not allowed with this function.
Using a value either outside of the range of zero to one hundred or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
An optional string attribute for specifying additional parameters to the request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
The requestNumber identifies no request.
A parameter value has not been understood by the DIVArchive Manager.
Also see "DIVA_getRequestInfo".
Submits a New Instance Creation request on the media specified by mediaName to the DIVArchive Manager, and the Manager chooses the appropriate instance to be created. This function returns as soon as the Manager accepts the request. The application must call the DIVA_getRequestInfo() function to check that the operation was successful.The request will fail if the requested object is on media that is not available. The Media Names (tape barcodes and disk names) that contain instances of the object will be included in the additionalInfo field of the DIVA_getRequestInfo() response.
A tape group may contain two instances of the same object. In this case, DIVArchive will terminate the request if both instances cannot be written on two different tapes. A disk array can contain two instances of the same object; however DIVArchive will terminate the request if the new instance cannot be written on a different disk. There can be a maximum of only one instance of each object per disk or tape.
DIVA_copyToGroup is a public alias to DIVA_copy and performs the same functionality.
#include "DIVAapi.h" DIVA_STATUS DIVA_copy ( IN DIVA_STRING objectName, IN DIVA_STRING categoryName, IN int instanceID, IN DIVA_STRING mediaName, IN int priorityLevel, IN DIVA_STRING options, OUT int *requestNumber ); DIVA_STATUS DIVA_copyToGroup ( IN DIVA_STRING objectName, IN DIVA_STRING categoryName, IN int instanceID, IN DIVA_STRING mediaName, IN int priorityLevel, IN DIVA_STRING options, OUT int *requestNumber );
The name of the object to be copied.
The category assigned to the object when it was archived. This parameter can be a null string; however this may result in an error if several objects have the same name.
The instance's identifier. DIVA_ANY_INSTANCE as the Instance ID means that DIVArchive will choose the appropriate instance.
The media (tape group or disk array) where the new instance will be located.
The level of priority for this request. The priorityLevel can be in the range zero to one hundred or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred is the highest priority.There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
An optional string attribute for specifying additional parameters to the request.
A number identifying the request to be changed.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value has not been understood by the DIVArchive Manager.
The count of simultaneous requests has reached the maximum allowed value. This variable is set in the manager.conf configuration file. The default is three hundred.
The specified object does not exist in the DIVArchive database.
The instance specified for restoring this object does not exist.
More than one object with the specified name exists in the DIVArchive database.
No available instance for this object. Tape instances are ejected and no Actor could provide a disk instance.
The instance specified for restoring this object is ejected, or the Actor owning the specified disk instance is not available.
The specified group does not exist.
The object is currently in use (being archived, restored, deleted, and so on).
The specified object has instances that are partially deleted.
Also see "DIVA_archiveObject".
Submits a request for copying an archived object to a new object, with another name or category, to the DIVArchive Manager. The Manager chooses the appropriate instance as the source of the copy. This function returns as soon as the Manager accepts the request. The application must call the DIVA_getRequestInfo() function to check that the operation was successful.
The request will fail if the requested object is on an unavailable media. The media names (tape barcodes and disk names) that contain instances of the object will be included in the additionalInfo field of the DIVA_getRequestInfo() response.
All types of transfers (disk to disk, disk to tape, tape to disk, and tape to tape) are supported.
#include "DIVAapi.h" DIVA_STATUS DIVA_copyToNewObject ( IN const DIVA::ObjectInstanceDescriptor &source, IN const DIVA::ObjectInstanceDescriptor &target, IN const DIVA::RequestAttributes &attrs, IN DIVA STRING options, OUT int *requestNumber );
The description of the object or object instance to be copied:
The source object name (required).
The source object category (required).
The source object instance tape group or disk array. This is optional, however if specified DIVArchive will use this instance as the source.
The Instance ID of the source object instance. This is optional, however if specified and not equal to DIVA_ANY_INSTANCE, DIVArchive will use this instance as the source. The source.group parameter will be ignored if source.instanceID is specified.
If both source.group and source.instanceID are omitted, DIVArchive will use the most suitable instance (that provides the best performance) as a source.
The description of the target object:
The target object name (required).
The target object category (required).
See the following paragraph.
This parameter is ignored.
Either the object name or category (or both) must be different from name or category of the source object. The request will fail if the target object already exists in DIVArchive.
The request attributes:
The request priority (optional). If this is not explicitly set the default value is used. Possible values are zero (lowest) to one hundred (highest).
Quality of Service (QOS) is not applicable to this request and this value is ignored.
The target object's comments (optional). If no value is specified the source object's comments are inherited.
This request has no additional options and this is ignored.
The number identifying the request that is returned by DIVArchive.
DIVA_STATUS DIVA_copyToNewObject ( IN const DIVA_STRING &objectName, IN const DIVA_STRING &objectCategory, IN const DIVA_STRING &objectMedia, IN int objectInstanceID, IN const DIVA_STRING &newObjectName, IN const DIVA_STRING &newObjectCategory, IN const DIVA_STRING &newObjectInstanceMedia, IN const DIVA_STRING &comments, IN int priorityLevel, IN DIVA_STRING options, OUT int *requestNumber );
The name of the source object.
The category of the source object.
The tape group or disk array of the source object instance (optional). If specified (not empty), DIVArchive will use this instance as a source. Complex objects can only be saved to AXF formatted media types.
The Instance ID of the source object instance (optional). If specified and not equal to DIVA_ANY_INSTANCE, DIVArchive will use this instance as the source. The objectMedia parameter is ignored if instanceID is specified.
If both objectMedia and instanceID are not specified, DIVArchive will use the most suitable instance (providing the best performance) as the source.
The target object name.
The target object category. Either the object name or category (or both) must be different from name or category of the source object.
This request will fail if the target object already exists in DIVArchive.
The tape group or disk array where the object will be saved. The media may be defined as follows:
Provide the tape group or disk array name as defined in the configuration. The object is saved to the specified media and assigned to the default Storage Plan (SP).
Provide a Storage Plan Name (SP Name) as defined in the configuration. The object will be saved to the default media specified in the Storage Plan and assigned to the specified Storage Plan.
The object is saved to the specified media as in Name above. The object is assigned to the specified SP as in SP Name above. The Name and the SP Name must be separated by the & delimiter (this is configurable).
Optional information describing the target object. If left empty the source object comments are inherited.
Level of priority for this request. The possible values can be in the range zero to one hundred, and the DIVA_DEFAULT_REQUEST_PRIORITY (use default request priority).
Optional string attribute for specifying additional parameters to the request.
The request number assigned to this request by DIVArchive.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The count of simultaneous requests has reached the maximum allowed value. This variable is set in the manager.conf configuration file. The default value is three hundred.
The specified object does not exist in the DIVArchive database.
The instance specified for restoring this object does not exist.
More than one object with the specified name exists in the DIVArchive database.
No available instance for this object. Tape instances are ejected and no Actor could provide a disk instance.
The instance specified for restoring this object is ejected, or the Actor owning the specified disk instance is not available.
The specified group does not exist.
The object is currently in use (being archived, restored, deleted, and so on).
The specified object has instances that are partially deleted.
Also see "DIVA_copyToGroup and DIVA_copy".
Deletes the group passed as an argument. You can only delete a group when the group is empty.
#include "DIVAapi.h" IN DIVA_STRING groupName DIVA_STATUS DIVA_deleteGroup ( );
The name of the group to be deleted.
One of the following DIVA_STATUS constants defined in DIVAapi.h.
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The specified group does not exist.
The group contains at least one object currently in use (being archived, restored, deleted, and so on).
Deletes an object instance.
#include "DIVAapi.h" DIVA_STATUS DIVA_deleteInstance ( IN DIVA_STRING objectName, IN DIVA_STRING categoryName, IN int instanceID, IN int priorityLevel, IN DIVA_STRING options, OUT int *requestNumber ); DIVA_STATUS DIVA_deleteInstance ( IN DIVA_STRING objectName, IN DIVA_STRING categoryName, IN DIVA_STRING mediaName, IN int priorityLevel, IN DIVA_STRING options, OUT int *requestNumber );
The name of the object to be deleted.
The category assigned to the object when it was archived. This parameter can be a null string, however this may result in an error if several objects have the same name.
The instance's identifier
Defines the media that contains the valid instance. If the instanceId is -1, the instance on the media will be deleted. If the media contains 2 or more instances, only one of the instances will be deleted.
The level of priority for this request. The priorityLevel can be in the range zero to one hundred or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred is the highest priority.There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
An optional string attribute for specifying additional parameters to the request.
A number identifying the request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The count of simultaneous requests has reached the maximum allowed value. This variable is set in the manager.conf configuration file. The default value is three hundred.
The specified object does not exist in the DIVArchive database.
More than one object with the specified name exists in the DIVArchive database.
The specified instance does not exist.
DIVA_deleteObject() must be used to delete the last instance of an object.
The object is currently in use (being archived, restored, deleted, and so on).
The specified object has instances that are partially deleted.
See also "DIVA_getObjectInfo".
Submits an Object Delete Request to the DIVArchive Manager. The Manager deletes every instance of the object. This function returns as soon as the Manager accepts the request. To check that the operation was successful the application must call the function DIVA_getRequestInfo().
#include "DIVAapi.h" DIVA_STATUS DIVA_deleteObject ( IN DIVA_STRING objectName, IN DIVA_STRING objectCategory, IN int priorityLevel, IN DIVA_STRING options, OUT int *requestNumber );
The name of the object to be deleted.
The category assigned to the object when it was archived. This parameter can be a null string, however this may result in an error if several objects have the same name.
The level of priority for this request. The priorityLevel can be in the range zero to one hundred or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred is the highest priority.There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
An optional string attribute for specifying additional parameters to the request.
A number identifying the request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The count of simultaneous requests has reached the maximum allowed value. This variable is set in the manager.conf configuration file. The default value is three hundred.
The specified object does not exist in the DIVArchive database.
More than one object with the specified name exists in the DIVArchive database.
The object is currently in use (being archived, restored, deleted, and so on).
The specified object does not exist in the DIVArchive database, but it is currently being archived.
See also "DIVA_getRequestInfo" and "DIVA_deleteInstance".
Submits an Eject Request to DIVArchive. The request completes when the specified tapes are outside of the library.
If at least one of the tapes does not exist, is already ejected, or currently in use by another request, the DIVA_ERR_INVALID_PARAMETER status code is returned and no tapes are ejected.
#include "DIVAapi.h" DIVA_STATUS DIVA_ejectTape ( IN vector<DIVA_STRING> *vsnList, IN bool release IN DIVA_STRING comment, IN int priorityLevel, OUT int *requestNumber );
List of VSNs for identifying the tapes to be ejected.
When true, perform a DIVA_release() on every instance located on the successfully ejected tapes.
Externalization comment.
The level of priority for this request. The priorityLevel can be in the range zero to one hundred or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred is the highest priority.There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
The number identifying the request.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager, or at least one of the barcodes refers to a bad tape (that is, an unknown tape, offline tape, or tape in use).
The count of simultaneous requests has reached the maximum allowed value. This variable is set in the manager.conf configuration file. The default value is three hundred.
See also "DIVA_insertTape".
Enable or disable the automatic repack scheduling in the DIVArchive Manager.
When the automatic repack scheduling is enabled, the schedule defined in the Control GUI is applied and tapes belonging to groups for which repack is allowed can be repacked according to the other automatic repack settings.
When the automatic repack scheduling is disabled, the schedule is ignored, all running automatic repack requests might be canceled (or not, according to other automatic repack settings), and no other automatic repack requests will be started until the automatic repack scheduling is turned on again (either from this API or from the Control GUI).
#include "DIVAapi.h" DIVA_STATUS DIVA_enableAutomaticRepack ( IN bool enable );
Set true to enable automatic repack scheduling, false to disable.
One of these DIVA_STATUS constants defined in DIVAapi.h.
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
Retrieves general information about the DIVArchive system.
A DIVArchive system communicates with a Robotic System composed of one or more independent ACSs (Automated Cartridge Systems). An ACS is composed of one or more LSMs (Library Storage Modules) that can exchange tapes through a PTP (Pass Through Port). Each tape drive is located in a LSM.
#include "DIVAapi.h" DIVA_STATUS DIVA_getArchiveSystemInfo ( IN string options; OUT DIVA_GENERAL_INFO *info );
Pointer to a DIVA_GENERAL_INFO structure that will be modified to include information about the DIVArchive system.
typedef enum {
DIVA_IS_ON = 0,
DIVA_IS_OFF,
DIVA_GLOBAL_STATE_IS_UNKNOWN
} DIVA_GLOBAL_STATE;
typedef enum {
DIVA_LIBRARY_OK = 0,
DIVA_LIBRARY_OUT_OF_ORDER,
DIVA_LIBRARY_STATE_UNKNOWN
} DIVA_LIBRARY_STATE;
class DIVA_ACTOR_AND_DRIVES_DESC {
public:
string actorName;
string actorAddress;
bool actorIsAvailable;
vector<string> *connectedDrives;
bool repackEnabled;
bool classicEnabled;
bool cacheArchiveEnabled;
bool directArchiveEnabled;
bool cacheRestoreEnabled;
bool directRestoreEnabled;
bool deleteEnabled;
bool copyToGroupEnabled;
bool associativeCopyEnabled;
int cacheForRepack;
};
class DIVA_LSM_DESC {
public:
string lsmName;
int lsmID;
bool lsmIsAvailable;
};
class DIVA_DRIVE_DESC {
public:
string driveName;
int driveTypeID;
string driveType;
int lsmID;
bool driveIsAvailable;
bool repackEnabled;
bool classicEnabled;
};
class DIVA_GENERAL_INFO {
public:
DIVA_GLOBAL_STATE status;
DIVA_LIBRARY_STATE lib_status;
int totalNumberOfObjects;
vector<DIVA_ACTOR_AND_DRIVES_DESC> *actorsDrivesList;
vector<DIVA_LSM_DESC> *lsmList;
vector<DIVA_DRIVE_DESC> *drivesList;
int numberOfBlankTapes;
long remainSizeOnTapes;
long totalSizeOnTapes;
int capSize;
vector<int> *pendingRequests;
vector<int> *currentRequests;
int numOfAvailableActors
int numOfAvailableDrives
int numOfAvailableDisks
string siteName
string siteIpAddress
int sitePort
int firstUsedRequestId
int lastUsedRequestId
};
The following parameters are listed in the order they appear in the preceding code example. Therefore there may be duplicates because the same parameter is used in different places in the code to represent different items.
The name of the DIVArchive Actor.
The DIVArchive Actor IP address.
Determines if the Actor is available.
Identifies the connected drives.
This is true if Repack is enabled.
This parameter is maintained for compatibility purposes only. This is only true if all seven standard operations are enabled.
This is true if Cached Archive is enabled.
This is true if Direct Archive is enabled.
This is true if Cached Restore is enabled.
This is true if Direct Restore is enabled.
This is true if Delete is enabled.
This is true if Copy To Group is enabled.
This is true if Associative Copy is enabled.
This is true if Cached Repack is enabled.
User-friendly Library Storage Module name.
This is the unique LSM ID.
This is true if the LSM identified by the preceding lsmID parameter is available for DIVArchive.
This is the Drive Name.
This is the Drive Type ID.
This is the Drive Type Name.
This is the ID of the LSM containing the drive. See lsmList described later.
This is true if the identified drive is available for DIVArchive.
The status of DIVArchive.
This is ok if at least one ACS is online. See lsmList described later.
The number of objects managed by this DIVArchive system.
<DIVA_ACTOR_AND_DRIVES_DESC>
<DIVA_LSM_DESC>
<DIVA_DRIVE_DESC>
The number of blank tapes in a Set associated with at least one group. Tape(s) may be externalized or write disabled.
The sum of the remaining size of tapes (in gigabytes) that are online, in a Set associated with at least one group in an ACS where DIVArchive has a drive that is writable, and the remaining size on disks accepting permanent storage. Only disks that are currently visible are used in the calculation.
Remaining_Size_of_Online_Tapes + Remaining_Size_of_Disks_Accepting_Permanent_Storage
The sum of the total size of all tapes (in gigabytes) in a Set associated with at least one group available for DIVArchive, and of the total size of all disks accepting storage. Only disks that are currently visible are used in the calculation.
Total_Size_of_all_Available_Tapes + Total_Size_of_all_Disks_Accepting_Storage
The number of slots in the default CAP.
The number of pending requests.
The number of current requests.
The number of currently running Actors.
The number of drives currently in online status.
The number of disks currently in online status.
The name of the main site as entered in the Configuration Utility.
The Manager IP Address.
The port number where the Manager is listening.
The first request ID used by the current Manager session. This value is -1 if no requests were processed.
The last request ID used by the current Manager session. This value is -1 if no requests were processed.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
The purpose of this function is to provide a list of arrays and disks associated with the arrays in the DIVArchive system. It also returns arrays without any disks associated with them.
#include "DIVAapi.h" DIVA_STATUS DIVA_getArrayList ( IN string options; OUT vector<DIVA_ARRAY_DESC> *&arraysInfo );
A pointer to a list of DIVA_ARRAY_DESC structures.
#ifndef WIN32
typedef long long __int64;
#endif
class DIVA_ARRAY_DESC {
public:
DIVA_STRING arrayDesc;
DIVA_STRING arrayName;
int numberOfDisk;
int mediaFormatId;
vector<DIVA_DISK_ARRAY> *arrayDiskList;
};
typedef enum {
DIVA_DISK_STATUS_UNKNOWN = 0,
DIVA_DISK_STATUS_ONLINE,
DIVA_DISK_STATUS_OFFLINE,
DIVA_DISK_STATUS_NOT_VISIBLE
} DIVA_DISK_STATUS;
class DIVA_DISK_ARRAY {
public:
__int64 disk_CurrentRemainingSize;
bool disk_isWritable;
__int64 disk_maxThroughput;
__int64 disk_minFreeSpace;
DIVA_STRING disk_name;
DIVA_STRING disk_site;
DIVA_DISK_STATUS disk_status;
__int64 disk_total_size;
DIVA_STRING disk_array_name;
};
The description of the array.
The name of the array.
The number of disks in the array.
The format of the data on disks in this array. The value can be DIVA_MEDIA_FORMAT_LEGACY, DIVA_MEDIA_FORMAT_AXF, or DIVA_MEDIA_FORMAT_AXF_10. See information on media formats in the "Glossary".
A list of the disks in an array.
The disk status is unknown.
The disk status is online.
The disk status is offline.
The disk status is not visible.
The current remaining disk size.
This flag checks to see whether the disk is writable.
The maximum throughput of a disk.
The minimum free space available on a disk.
The name of the disk.
The name of the site where the disk is located.
The current disk status.
The total size of the disk.
The name of the array containing the disk.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
Get all of the finished requests starting from the specified number of seconds before the present. Finished requests are requests that have completed normally or were terminated.
Use this function as follows:
If the list of requests to be processed is greater than the batch size, make successive calls to this function. The first time the function is called, set initialTime to the desired number of seconds earlier, where the list is to start. The maximum is three days. For successive calls set initialTime to zero and set the uniqueId to the value returned by the previous call. The returned list will be empty after all of the requests have been returned.
#include "DIVAapi.h" DIVA_STATUS DIVA_getFinishedRequestList ( IN int batchSize, IN int initialTime, IN DIVA_STRING uniqueId, OUT DIVA_FINISHED_REQUEST_INFO *pFinishedRequestInfo );
The maximum size of the returned list of objects. This must be set to a value no greater than 1000; the recommended setting is 500. This is only a suggestion and may be overridden by the underlying functionality. This parameter should not be used to guarantee that the list will be a certain size.
The first time the function is called this value defines how far back in time to go to look for finished requests. Requests that have finished between this time and the present will be retrieved. The valid range for this parameter is 1 to 259200 (three days). If the number of requests to be returned is greater than the batch size, the call is repeated. For these calls this parameter should be set to zero (0).
The first time the function is called this value must be set to an empty string (_T("")). Do not set this parameter to NULL. If the number of request to be returned is greater than the batch size, the call is repeated. For these calls this value should be set to the uniqueId as found in DIVA_FINISHED_REQUEST_INFO that was returned by the previous call.
This is a pointer to the returned data. See the description of DIVA_FINISHED_REQUEST_INFO later in this section. It is the user's responsibility to allocate and delete instances of this class.
class DIVA_FINISHED_REQUEST_INFO {
public:
DIVA_STRING uniqueId;
vector<DIVA_REQUEST_INFO> *pRequestList;
};
After the first (and any subsequent) call, DIVArchive API libraries update this variable with the current position in the search. Use this value as the input parameter to subsequent calls.
This is a pointer to the returned data. See the description of DIVA_REQUEST_INFO under the description of "DIVA_getRequestInfo".
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
Retrieves the names of the files and folders for the specified object from DIVArchive. This function is included to support complex objects, but is valid for any object.
You set the startIndex to zero to get all of the file and folder names for an object. A list of names of the specified size is returned. You then set startIndex to the value of nextStartIndex and again make the function call. Continue this process until the return value equals DIVA_WARN_NO_MORE_OBJECTS.
#include "DIVAapi.h" DIVA_STATUS DIVA_getFilesAndFolders ( IN DIVA_STRING objectName, IN DIVA_STRING objectCategory, IN int listType, IN int startIndex, IN int batchSize, IN DIVA String options, OUT DIVA_FILES_AND_FOLDERS *pFilesAndFolders );
The name of the object to be queried.
The category assigned to the object when it was archived.
Specifies what the returned list will include. See the definition of DIVA_FILE_FOLDER_LIST_TYPE later in this section.
The position in the list to start this iteration. Set at one (1) to start at the beginning. Values less than one are not valid. Set startIndex equal to nextStartIndex as returned in DIVA_FILES_AND_FOLDERS for all subsequent calls.
The maximum size of the returned list of objects. This must be set to a value no greater than 1000; the recommended setting is 500. This is only a suggestion and may be overridden by the underlying functionality. This parameter should not be used to guarantee that the list will be a certain size.
Field for optional getFilesAndFolders parameters.
This is a pointer to the returned data. See the description of DIVA_FILES_AND_FOLDERS later in this section. It is the responsibility of the user to allocate and delete instances of this class.
Typedef enum {
DIVA_LIST_TYPE_FILES_ONLY = 0,
DIVA_LIST_TYPE_FOLDERS_ONLY = 1,
DIVA_LIST_TYPE_FILES_AND_FOLDERS = 2
} DIVA_FILE_FOLDER_LIST_TYPE;
This function will return files only.
This function will return folders only. This is only valid for complex objects.
This function will return files and folders. This is valid for complex objects only.
class DIVA_FILES_AND_FOLDERS {
public:
DIVA_OBJECT_SUMMARY objectSummary;
bool isComplex;
int nextStartIndex;
DIVA String siteName;
vector<DIVA_FILE_FOLDER_INFO> *pFileFolderList;
};
The ID of the DIVArchive Object. See the description later in this section.
This is true when the object is a complex object.
After the first and any subsequent call, the DIVArchive API libraries update this variable with the current position in the search. Use this value as the input parameter for subsequent calls.
This contains the site name of the Manager that satisfied the request.
This is a pointer to the list of files and folders. See the description of DIVA_FILE_FOLDER_INFO later in this section.
class DIVA_OBJECT_SUMMARY {
public:
string objectName;
string objectCategory;
};
This is the name of the object.
This is the category of the object.
class DIVA_FILE_FOLDER_INFO {
public:
DIVA_STRING fileOrFolderName;
bool isDirectory;
__int64 sizeBytes;
int fileId;
int totalNumFilesFolders;
__int64 totalSizeFilesFolders;
vector<DIVA_CHECKSUM_INFO> pChecksumInfoList;
};
The name of the file or folder.
This is true if the component is a directory and not a file name.
The size of the file in bytes. This is valid only for files.
This is a unique ID for each file created by DIVArchive as part of the processing of this command.
The number of files and sub folders. This is valid only for folders in a complex object.
The total size of all files, including files in sub folders. This is valid only for folders in a complex object.
This is a pointer to a list of checksums for a file. Directories will not contain checksums. It is also possible that some files in the archive will not contain checksum information. See the description later in this section.
class DIVA_CHECKSUM_INFO {
public:
DIVA_STRING checksumType;
DIVA_STRING checksumValue;
bool isGenuine;
};
The type of checksum (MD5, SHA1, and so on).
The value of the checksum in hexadecimal string format.
This is true if this checksum was provided at the time of archiving and verified as a Genuine Checksum.
The DIVArchive 7.4 API includes the following enhancements to the return values for this call:
The file list now contains empty files for non-complex objects.
The folders list now contains all folders in a non-complex object.
Both the Folders Only and Files and Folders options are now available for use with non-complex objects.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
The end of the list was reached during the call.
Returns the description of all groups.
#include "DIVAapi.h" DIVA_STATUS DIVA_getGroupsList ( OUT vector<DIVA_GROUP_DESC> *&groups );
This is a pointer to a list of DIVA_GROUP_DESC structures.
class DIVA_GROUP_DESC {
public:
string group_name;
string group_desc;
int mediaFormatId;
};
The configured name of the tape group.
The description of the tape group.
The format of the tapes added to this group. The value can be DIVA_MEDIA_FORMAT_LEGACY, DIVA_MEDIA_FORMAT_AXF, or DIVA_MEDIA_FORMAT_AXF_10. See information on media formats in the "Glossary".
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
See also "DIVA_getObjectInfo".
The DIVA_getObjectDetailsList is an API call to retrieve object information from the DIVArchive database. Only the latest state of the object is returned. Objects may be repeated across batches if the object is modified multiple times as the call advances (in time) from a user-specified time across objects in the DIVArchive database.
The created-since call retrieves all objects created since a certain time.
The deleted-since call retrieves all objects deleted since a certain time.
If starting from a user-specified time of zero, the modified-since call retrieves all objects created since a certain time, and returns the state of the database from a time of zero.
If starting from a user-specified time greater than zero, the call returns all objects created and deleted since a certain time, and all objects with newly created and (or) deleted instances.
The listPosition vector returned by a GetObjectDetailsList call must be passed in to a subsequent call. Its content must not be altered by the user of the call.
Different detail levels can be specified (see the following Level of Detail Setting information). Level 0 will be the fastest, while Level 3 will return all possible details. Only the highest level of detail is supported. Using a lower level of detail will still return all information for objects.
The output can be structured using the DIVA_OBJECTS_LIST option, or through the DIVA_TAPE_INFO_LIST option. The output structure type is configured by setting the pListType parameter of the call.
The API client application should use the DIVA_OBJECTS_LIST setting in the following cases:
To retrieve a list of objects instances added to DIVArchive.
To retrieve a list of objects instances deleted from DIVArchive.
To retrieve a combined list of all changes in the DIVArchive object database (adding and deleting objects, adding and deleting instances)
To continuously monitor the DIVArchive system to retrieve events of adding and deleting objects, and adding and deleting instances.
The API client application should use the DIVA_TAPE_INFO_LIST setting to retrieve a list of tape instances for any instances added, deleted, repacked, ejected, or inserted.
Note:
The DIVA_TAPE_INFO_LIST will not return any results for deleted instances if all objects are deleted.#include "DIVAapi.h" DIVA_STATUS DIVA_getObjectDetailsList ( IN bool fFirstTime, IN time_t *initialTime, IN int pListType, IN int pObjectsListType, IN int pMaxListSize, IN DIVA_STRING pObjectName, IN DIVA_STRING pObjectCategory, IN DIVA_STRING pMediaName, DIVA_LEVEL_OF_DETAIL pLevelOfDetail, IN vector<DIVA_STRING> listPosition, OUT vector<DIVA_OBJECT_DETAILS_LIST> *&pObjectDetailsList );
The first time this function is called this parameter must be set to true. Every subsequent call should be set to false and listPosition must be copied from the listPosition value returned by the previous call to DIVA_GetObjectDetailsList.
The start time of the list. Data is collected and returned corresponding to this time and later. To retrieve all items in the database, use zero as the start time value.
One of the codes defined by the enumeration DIVA_LIST_TYPE.
One of the codes defined by the enumeration DIVA_OBJECTS_LIST_TYPE.
To retrieve all objects created, deleted, or modified since a certain time, set this to DIVA_OBJECTS_CREATED_SINCE, DIVA_OBJECTS_DELETED_SINCE, or DIVA_OBJECTS_MODIFIED_SINCE, respectively.
To retrieve tape related information for all objects that have been created, deleted, repacked, ejected, and (or) inserted since a certain time, set this parameter to DIVA_INSTANCE_CREATED, DIVA_INSTANCE_DELETED, DIVA_INSTANCE_REPACKED, DIVA_INSTANCE_EJECTED, DIVA_INSTANCE_INSERTED, respectively.
To retrieve any combination of the above, use the pipe operator. For example, to retrieve tape information for objects with tape instances that have been created and repacked since a certain time, use DIVA_INSTANCE_CREATED | DIVA_INSTANCE_REPACKED.
The maximum size of the returned list of objects. This must be set to a value no greater than 1000; the recommended setting is 500. This is only a suggestion and may be overridden by the underlying functionality. This parameter should not be used to guarantee that the list will be a certain size.
Filter the returned list of objects based on the provided object category. The asterisk wildcard can be used (for example, *video).
Filter the returned list of objects based on the provided media name. The asterisk wildcard can be used (for example, soap*).
One of the codes defined by the enumeration DIVA_LEVEL_OF_DETAIL. Filtering by object name, category, and group (media name) is performed at all levels of detail.
The DIVA_OBJECTS_CREATED_SINCE and DIVA_OBJECTS_MODIFIED_SINCE options work with all levels of detail.
The DIVA_OBJECTS_DELETED_SINCE option only works with the DIVA_OBJECTNAME_AND_CATEGORY level of detail.
The DIVA_TAPE_INFO_LIST only works with the DIVA_OBJECTNAME_AND_CATEGORY and DIVA_INSTANCE level of detail.
A vector of DIVA_STRING type. The elements of this list are for internal use only and do not need to be extracted by the user.
When pFirstTime is true, a new empty list must be constructed and included.
When pFirstTime is false, listPosition must be updated with the listPosition attribute of pObjectDetailsList since this attribute points to the last object retrieved by the last call of DIVA_getObjectDetailsList.
This is a pointer to the DIVA_OBJECT_DETAILS_LIST class. This is the output parameter that will contain the response to the call.
Use the listPosition parameter from this response as the listPosition argument in subsequent calls to GetObjectDetailsList.
For pListType = DIVA_OBJECTS_LIST, all of the object and (or) instance information is stored in the objectInfo attribute.
For pListType = DIVA_TAPE_INFO_LIST, all object and tape information is stored in the objectTapeInfo attribute.
typedef enum {
DIVA_OBJECTNAME_AND_CATEGORY = 0,
DIVA_MISC = 1,
DIVA_COMPONENT = 2,
DIVA_INSTANCE = 3
} DIVA_LEVEL_OF_DETAIL;
The getObjectDetailsList function will only return the object name and category.
The getObjectDetailsList function will return the comments, archive date, name and path on the source, and all data returned with the DIVA_OBJECTNAME_AND_CATEGORY level of detail.
The getObjectDetailsList function will return the size of the object, list of components value, and all data returned with the DIVA_MISC level of details.
The getObjectDetailsList function will return all instance information, repack state, related active request information data, and all data returned with the DIVA_COMPONENT level of detail.
typedef enum {
DIVA_OBJECTS_LIST = 1,
DIVA_TAPE_INFO_LIST = 2
} DIVA_LIST_TYPE;
DIVA_OBJECTS_LIST_TYPE is defined as follows:
typedef enum {
DIVA_OBJECTS_CREATED_SINCE = 0x0001,
DIVA_OBJECTS_DELETED_SINCE = 0x0002,
DIVA_OBJECTS_MODIFIED_SINCE = 0x0003,
DIVA_INSTANCE_NONE = 0x0000,
DIVA_INSTANCE_DELETED = 0x0020,
DIVA_INSTANCE_REPACKED = 0x0040,
DIVA_INSTANCE_EJECTED = 0x0080,
DIVA_INSTANCE_INSERTED = 0x0100
} DIVA_OBJECTS_LIST_TYPE;
class DIVA_OBJECT_DETAILS_LIST {
public:
int listType;
DIVA_STRING siteID;
vector<DIVA_STRING> *listPosition;
vector<DIVA_OBJECT_INFO> *objectInfo;
vector<DIVA_OBJECT_TAPE_INFO> *objectTapeInfo;
};
One of the codes defined by the enumeration DIVA_LIST_TYPE.
The DIVArchive system name as configured in manager.conf.
After the first and any subsequent call, the DIVArchive API libraries update this variable with the current position in the search. This object must be provided as the input parameter to any subsequent calls.
This is a pointer to a DIVA_OBJECT_INFO structure. The structure should be allocated and deleted by the caller. The structure contains information about the object details, such as the list of components, tape instances, and other properties described in API call getObjectInfo.
This is a pointer to a list of DIVA_OBJECT_TAPE_INFO structures. The structure should be allocated and deleted by the caller. The structure contains information about the tapes containing instances of the object and other properties described in API call getObjectTapeInfo.
class DIVA_OBJECT_INFO {
public:
DIVA_OBJECT_SUMMARY objectSummary;
DIVA_STRING uuid;
int lockStatus;
__int64 objectSize;
__int64 objectSizeBytes;
vector<string> *filesList;
string objectComments;
time_t archivingDate;
bool isInserted;
vector<DIVA_TAPE_INSTANCE_DESC> *tapeInstances;
vector<DIVA_ACTOR_INSTANCE_DESC> *actorInstances;
string objectSource;
string rootDirectory;
vector<int> *relatedRequests;
bool toBeRepacked;
int modifiedOrDeleted;
bool isComplex;
int nbFilesInComplexComponent;
int nbFoldersInComplexComponent;
};
The object name and category.
Universally Unique Identifier to uniquely identify each object created in DIVArchive across all Oracle customer sites. This does not include objects created using Copy As requests. An object created through a Copy As request will contain the same UUID as that of the source object.
This is the locking status of the object. Objects in the archive can be locked. When an object is locked it cannot be restored or copied to a new name. This feature prevents the use of an object that has an expired copyright, and so on. The object is unlocked when this value is zero.
This is the object size in kilobytes.
This is the object size in bytes.
This is a list of the files in the object. A single wrapper file name is returned for complex objects.
This is the comments saved when the object was archived.
Then number of seconds since January 1, 1970.
This is true if at least one instance of this object is either on a tape that is currently inserted in the library, or a disk that is online.
This is a list of object instances saved to tape.
This is a list of object instances saved to disk.
The source system used to archive the object.
The root directory containing the object files on the objectsource.
This is non-terminated requests.
This is false unless all instances are going to be repacked.
One of DIVA_MODIFIED_OR_DELETED as follows:
UNDEFINED - The levelOfDetail does not equal DIVA_INSTANCE.
DIVA_CREATED_OR_MODIFIED - The object was created, or an instance was either added or removed.
DIVA_DELETED - The object was removed.
This is true if this is a complex object.
This is the number of files in the object. This is used only for complex objects. The value is zero for non-complex objects.
This is the number of folders in the object. This is used only for complex objects. The value is zero for non-complex objects.
class DIVA_OBJECT_SUMMARY {
public:
string objectName;
string objectCategory;
};
This is the object name.
This is the object category.
class DIVA_TAPE_INSTANCE_DESC {
public:
int instanceID;
string groupName;
vector<DIVA_TAPE_DESC> *tapeDesc;
bool isInserted,
DIVA_REQUIRE_STATUS reqStatus;
};
The numeric instance identifier.
The name of the group this tape is assigned to.
Additional information about this tape.
This is true if at least one instance of this object is either on a tape that is currently inserted in the library, or a disk that is online.
Determines if the instance is Required or Released.
DIVA_REQUIRED - The instance is requested to be inserted into the library.
DIVA_RELEASED - There is no need to have this instance present into the library.
class DIVA_TAPE_DESC {
public:
string vsn;
bool isInserted;
string externalizationComment;
bool isGoingToBeRepacked;
int mediaFormatId;
};
The volume serial number (barcode).
This is true if at least one instance of this object is either on a tape that is currently inserted in the library or a disk that is online.
Comment saved when the tape was exported.
This is false unless all instances are going to be repacked.
The format of the data on to be used. The value can be DIVA_MEDIA_FORMAT_DEFAULT, DIVA_MEDIA_FORMAT_LEGACY, DIVA_MEDIA_FORMAT_AXF, or DIVA_MEDIA_FORMAT_AXF_10. This is only used when the listType is Tape.
class DIVA_ACTOR_INSTANCE_DESC {
public:
int instanceID;
string actor;
};
The numeric ID of the instance.
This field reports the name of the disk array where the instance is stored instead of the Actor name.
typedef enum {
DIVA_REQUIRED = 0,
DIVA_RELEASED
} DIVA_REQUIRE_STATUS;
typedef enum {
DIVA_UNDEFINED = 0,
DIVA_CREATED_OR_MODIFIED,
DIVA_DELETED
} DIVA_MODIFIED_OR_DELETED;
The file list of each object in the objects list now contains empty files (that is, files of size 0 bytes). Client applications developed against API releases before release 7.4 will now receive empty files in the file list that accompanies a Details List message. Depending on the input parameters, the DIVA_getObjectDetailsList function will return values as described in the following table.
Table 2-1 DIVA_getObjectDetailsList Function Values
| List Type | Objects List Type | Supported Detail Level | Return Value |
|---|---|---|---|
|
DIVA_OBJECTS_LIST |
DIVA_OBJECTS_CREATED_SINCE |
All |
List Objects that have been created since a specified time. |
|
DIVA_OBJECTS_LIST |
DIVA_OBJECTS_DELETED_SINCE |
Only DIVA_OBJECTNAME_AND_CATEGORY |
List Objects that have been deleted since a specified time. |
|
DIVA_OBJECTS_LIST |
DIVA_OBJECTS_MODIFIED_SINCE |
Only DIVA_INSTANCE |
List Objects that have been created/deleted since a certain time, plus Objects with new or deleted instances. If the list of instances is empty, objects were deleted. If the list of instances is not empty, objects were created or updated. |
|
DIVA_TAPE_INFO_LIST |
DIVA_INSTANCE_NONE (0x0000) |
Only DIVA_OBJECTNAME_AND_CATEGORY and DIVA_INSTANCE level. |
List objects and tape information for all tape instances (no filter). |
|
DIVA_TAPE_INFO_LIST |
DIVA_INSTANCE_CREATED (0x0010) |
Only DIVA_OBJECTNAME_AND_CATEGORY and DIVA_INSTANCE level. |
List objects and tape information for all tape instances created since a specified time. |
|
DIVA_TAPE_INFO_LIST |
DIVA_INSTANCE_DELETED (0x0020) |
Only DIVA_OBJECTNAME_AND_CATEGORY and DIVA_INSTANCE level. |
List objects and tape information for all tape instances deleted since a specified time. |
|
DIVA_TAPE_INFO_LIST |
DIVA_INSTANCE_REPACKED (0x0040) |
Only DIVA_OBJECTNAME_AND_CATEGORY and DIVA_INSTANCE level. |
List objects and tape information for all tape instances repacked since a specified time. |
|
DIVA_TAPE_INFO_LIST |
DIVA_INSTANCE_EJECTED (0x0080) |
Only DIVA_OBJECTNAME_AND_CATEGORY and DIVA_INSTANCE level. |
List objects and tape information for all tape instances ejected since a specified time. |
|
DIVA_TAPE_INFO_LIST |
DIVA_INSTANCE_INSERTED (0x0100) |
Only DIVA_OBJECTNAME_AND_CATEGORY and DIVA_INSTANCE level. |
List objects and tape information for all tape instances inserted since a specified time. |
All filters are applied at an object level as follows:
If you request objects satisfying certain filter constraints, those constraints are applied to the object and not to individual instances of an object.
If you specify an object name and category filter, the list will be filtered to contain only objects satisfying the specified object name and category.
Media name is defined at an instance level, not at an object level. A media name filter will only allow objects with at least one instance satisfying the requested media name filter.
Note:
If an instance of an object is created or deleted, and you request all modified objects with a particular media name, the object will be returned if and only if any instance of the object satisfies the media name filter.Example:
A new instance Object-A was added at time 101 with the media name CAR. Object-A has a total of two instances. One instance has the media name TRUCK and the other has the media name CAR.
An instance of Object-B was removed at time 101 with the media name CAR. Object-B has only one instance.
A new instance of Object-C was added at time 99 with the media name TRAIN. Object-C has a total of two instances. One instance has the media name TRAIN and the other has the media name HANG GLIDE.
A user executes a getObjectDetailsList call with MODIFIED SINCE TIME 100 and MEDIA NAME FILTER = T*.
The only object that was modified since time 100, and has at least one instance with a media name of T is Object-A. Therefore, the result is that the list returned by the getObjectDetailsList call contains only Object-A.
Oracle recommends that the DIVArchive API client application adhere to the following sequence of actions:
Create a variable of DIVA_OBJECT_DETAILS_LIST type to store the object information returned by the call.
Create a variable of vector<DIVA_STRING> type to serve as the listPosition object. This will be used as the listPosition argument to DIVA_GetObjectDetailsList.
Create a variable of time_t type and set to the time at which the list is to start. Set this to zero to include all objects in the database.
Create a variable of Boolean type and set it to true to indicate that this is the first call in a sequence of calls.
Create a variables of Integer type to hold the listType and objectsListType to specify the type of call.
Example: Use DIVA_OBJECTS_LIST and DIVA_OBJECTS_MODIFIED_SINCE to indicate that you want object information for modified objects.
Create a variable of Integer type to hold the suggested number of objects you want returned by the call.
Create list filtering variables of DIVA_CHAR[] type to hold the object name, category and media filters.
Create a variable of Integer type to hold the level of detail you want returned.
Execute DIVA_GetObjectDetailsList with the variables previously mentioned.
Use the data stored in the variable from Step 1 as needed by your application.
Copy the listPosition attribute of the call's output created in Step 1 into the listPosition variable created in Step 2.
Continue repeating steps 8, 9, and 10 until you no longer need to monitor DIVArchive.
All variables must be unallocated after exiting the loop.
Multiple simultaneous calls to DIVA_getObjectDetailsList are supported. However, this call places a heavy demand on the database. Therefore simultaneous and (or) frequent calls to this function should be avoided.
Continuous monitoring of DIVArchive requires a procedure similar to the one defined in the section "Recommended Practices for Continuous Updates Notification Design Pattern (No Media Filter)".
Duplication of objects can occur across different return portions. It is important to handle these cases by examining the data returned by the call. For a MODIFIED_SINCE call, you must compare the instances of the duplicate object returned by successive calls to identify whether new information about the object is available and update your local repository accordingly.
An empty list may be returned as a valid result. This indicates that there were no changes to the system after the time specified in the last call. It is important to continue querying DIVArchive with the DIVA_getObjectDetailsList call using the ID from the previous call. However, the call frequency must be reduced after you receive an empty list. This reduces the load on the DIVArchive database.
The same application can use the DIVA_getObjectDetailsList function effectively for both the initial database synchronization (if the client application maintains a database) and later use it for continuous monitoring after the database is updated.
During the initial database synchronization phase, it is necessary for the application to make frequent sequential calls to synchronize the local database with the DIVArchive database. The application must call DIVA_getObjectDetailsList, wait for a response, and then repeat the process.
After the synchronization phase, it is necessary for the application to go into the continuous monitoring phase, where it must make periodic calls to update the system with the latest object information. Oracle recommends a call interval of once every several minutes. Continuous, frequent execution of this call can heavily impact the database and degrade system performance.
The amount of data retrieved by the CREATED_SINCE and MODIFIED_SINCE call is substantial (object, instance, and component data for each object). Therefore, Oracle recommends that most applications use 500 as the maximum list size setting.
The continuous updates notification design pattern is used in multiple applications, and is important when using the DIVArchive API. The client application can use the internal database to continuously update the local database information with changes in the DIVArchive database. Following the design pattern helps develop the performance-optimized updates notification workflow.
The application must submit the call with the objectListType set to MODIFIED_SINCE with the level of detail required to collect instance-level information. Additionally, the First Time flag must be set true, and all necessary filter parameters must be set (object name and category).
This is the process the application will follow:
The application receives a list of objects and a new listPosition.
On the next cycle, the application will execute the call using the listPosition obtained in Step 1 and the First Time flag set to false. It is acceptable to submit another call immediately after receiving the list if the system is being used solely for synchronization purposes. Otherwise, it is recommended to wait for a period of time between calls to allow other DIVArchive requests to process.
Repeat Steps 1 and 2 for the course of execution to keep the internal database synchronized with DIVArchive database.
If none of the objects in DIVArchive have been modified, the list will be EMPTY, which indicates there were no updates since the last call. The application should wait for a specific amount of time, and then retry.
The application must check the list of instances to see if the following occurred:
The value of modifiedOrDeleted in the DIVA_OBJECT_INFO equals DELETED, objects were deleted and the database must be updated.
The value of modifiedOrDeleted in the DIVA_OBJECT_INFO equals CREATED_OR_MODIFIED, the object was either created or updated.
If the object previously existed in the database, the database list of instances must be updated.
If the object does not exist in the database, it must be added to the database.
Note:
To ensure continuous updates, thelistPosition object should be preserved throughout the course of operations.Example:
MAIN:
CREATE LIST_POSITION VARIABLE
CREATE DETAILS_LIST VARIABLE
SET FIRST_TIME = TRUE
SET INITIAL_TIME = 0
SET LIST_TYPE = DIVA_OBJECTS_LIST
SET OBJECTS_LIST_TYPE = DIVA_OBJECTS_MODIFIED_SINCE
SET LEVEL_OF_DETAIL = DIVA_OBJECTS_MODIFIED_SINCE
SET SIZE = 500
SET OBJECT_NAME = "*"
SET CATEGORY = "*"
SET MEDIA_NAME = "*"
CALL GetObjectDetailsList(FIRST_TIME, LIST_TYPE, OBJECTS_LIST_TYPE, LIST_POSITION , SIZE, INITIAL_TIME, OBJECT_NAME, CATEGORY, MEDIA_NAME, LEVEL_OF_DETAIL, DETAILS_LIST) // 1
UNIQUE_ID AND DETAILS_LIST VARIABLES WERE UPDATED BY CALL // 2
CALL SYNC_OBJECTS // 6
START LOOP
SET FIRST TIME = FALSE
CALL GetObjectDetailsList(…) // 3
LIST_POSITION AND DETAILS_LIST VARIABLES WERE UPDATED BY CALL
CALL SYNC_OBJECTS // 6
END LOOP (TERMINATE AT END OF APPLICATION LIFE) // 4
SYNC_OBJECTS:
IF (DETAILS_LIST IS NOT EMPTY) // 5
FOR(OBJECT IN DETAILS_LIST)
IF (OBJECT.modifiedOrDeleted EQUALS DELETED)
DELETE OBJECT FROM DATABASE // 6a
ELSE
IF (OBJECT.modifiedOrDeleted EQUALS CREATED_OR_MODIFIED)
ADD OR UPDATE OBJECT TO DATABASE // 6b
END IF
END IF
END FOR
END IF
Return Values
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
The end of the list was reached during the call.
Returns information about a particular object in the DIVArchive system.
The vector<DIVA_ACTOR_INSTANCE_DESC> *actorInstances parameter is kept unchanged for compatibility, although it is formally a vector of diskInstance and not actorInstance.The DIVArchive 7.4 file list can contain empty files (that is, files of size 0 bytes). Client applications developed against API releases before release 7.4 will also receive empty files in the file list that accompanies an objectInfo message.For compatibility reasons, the class DIVA_ACTOR_INSTANCE_DESC designates a disk instance (not an actor instance) and its string actor field now contains the array name instead of an Actor name.
#include "DIVAapi.h" DIVA_STATUS DIVA_getObjectInfo ( IN DIVA_STRING objectName, IN DIVA_STRING objectCategory, IN DIVA_STRING options, OUT DIVA_OBJECT_INFO *objectInfo );
The name of the queried object.
The category assigned to the object when it was archived. This parameter can be a null string, however this may result in an error if several objects have the same name.
Optional string attribute for specifying additional parameters to the request.
Pointer to a DIVA_OBJECT_INFO structure allocated and deleted by the caller. See "DIVA_getObjectDetailsList" for a description of DIVA_OBJECT_INFO.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
The specified object does not exist in the DIVArchive Database.
More than one object with the specified name exists in the DIVArchive Database.
See also "DIVA_archiveObject", "DIVA_restoreObject", and "DIVA_deleteObject".
When processing the request DIVA_PartialRestoreObject(), and the format for the offsets was specified as timecodes, the offsets that are actually used may differ (somewhat) from what was specified in the request. Once the Oracle DIVArchive Partial File Restore request is complete, you can use this command to obtain the actual offsets of the restored files.
This is a special purpose command that is valid only as follows:
The request number to be queried must be a partial file restore request that has been successfully completed.
The format specified in the partial file restore request must be a timecode type. This command is therefore not valid when the format of the request was folder-based or DPX.
#include "DIVAapi.h" DIVA_STATUS DIVA_getPartialRestoreRequestInfo ( IN int requestNumber, OUT vector <DIVA_OFFSET_SOURCE_DEST> *fileList );
Identifies the completed Oracle DIVArchive Partial File Restore request to be queried.
List of the files of an object that have been partially restored. Each structure contains the source file name, a vector of the offsets used for the transfer, and a destination file name. This vector must be similar to the vector provided to the DIVA_partialRestoreObject() function in terms of files and offset pairs. This function is provided to eventually detect that the actual offsets used for the transfer to the destination server have been adapted based on the format of the data to transfer.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
The requestNumber identifies no request
The requestNumber identifies no completed partial file restore request.
See also "DIVA_partialRestoreObject" and "DIVA_getRequestInfo".
Obtains information about an archive, restore, delete, or repack request.
#include "DIVAapi.h" DIVA_STATUS DIVA_getRequestInfo ( IN int requestNumber, OUT DIVA_REQUEST_INFO *requestInfo );
Identifies the queried request.
Pointer to a DIVA_REQUEST_INFO structure. This is allocated and deleted by the caller.
class DIVA_REQUEST_INFO {
public:
int requestNumber;
DIVA_REQUEST_TYPE requestType ;
DIVA_REQUEST_TYPE
DIVA_REQUEST_STATE requestState;
DIVA_REQUEST_STATE
int progress;
DIVA_ABORTION_REASON abortionReason;
DIVA_OBJECT_SUMMARY objectSummary;
DIVA_REPACK_TAPES_INFO repackTapes;
int currentPriority;
DIVA_STRING additionalInfo;
time_t submissiondate
time_t completiondate
};
The DIVArchive request number.
See the definition of DIVA_REQUEST_TYPE later in this section.
See the definition of DIVA_REQUEST_STATE later in this section.
The progress of the request from zero to one hundred percent if the requestState is DIVA_TRANSFERRING or DIVA_MIGRATING.
The reason the request was terminated if the requestState is DIVA_ABORTED, otherwise this is zero.
See the definition of DIVA_OBJECT_SUMMARY later in this section.
Used if the requestType is REPACK.
See "Additional_Info" later in this section for use of this field.
The date and time the request was submitted. This is UTC time in seconds (that is, seconds since January 1, 1970).
The date and time the request completed. This is UTC time in seconds and will be -1 if the request is still processing.
Typedef enum {
DIVA_ARCHIVE_REQUEST = 0,
DIVA_RESTORE_REQUEST,
DIVA_DELETE_REQUEST,
DIVA_EJECT_REQUEST,
DIVA_INSERT_REQUEST,
DIVA_COPY_REQUEST,
DIVA_COPY_TO_NEW_REQUEST,
DIVA_RESTORE_INSTANCE_REQUEST,
DIVA_DELETE_INSTANCE_REQUEST,
DIVA_UNKNOW_REQUEST_TYPE,
DIVA_AUTOMATIC_REPACK_REQUEST,
DIVA_ONDEMAND_RAPACK_REQUEST,
DIVA_ASSOC_COPY_REQUEST,
DIVA_PARTIAL_RESTORE_REQUEST,
DIVA_MULTIPLE_RESTORE_REQUEST,
DIVA_TRANSCODE_ARCHIVED_REQUEST,
DIVA_EXPORT_REQUEST,
DIVA_TRANSFER_REQUEST,
DIVA_AUTOMATIC_VERIFY_TAPES_REQUEST,
DIVA_MANUAL_VERIFY_TAPES_REQUEST,
} DIVA_REQUEST_TYPE ;
typedef enum {
DIVA_PENDING = 0,
DIVA_TRANSFERRING,
DIVA_MIGRATING,
DIVA_COMPLETED,
DIVA_ABORTED,
DIVA_CANCELLED,
DIVA_UNKNOWN_STATE,
DIVA_DELETING,
DIVA_WAITING_FOR_RESOURCES,
DIVA_WAITING_FOR_OPERATOR,
DIVA_ASSIGNING_POOL,
DIVA_PARTIALLY_ABORTED,
DIVA_RUNNING
} DIVA_REQUEST_STATE;
typedef enum {
DIVA_AR_NONE = 0,
DIVA_AR_DRIVE,
DIVA_AR_TAPE,
DIVA_AR_ACTOR,
DIVA_AR_DISK,
DIVA_AR_DISK_FULL,
DIVA_AR_SOURCE_DEST,
DIVA_AR_RESOURCES,
DIVA_AR_LIBRARY,
DIVA_AR_PARAMETERS,
DIVA_AR_UNKNOWN,
DIVA_AR_INTERNAL,
DIVA_AR_SOURCE_DEST2
} DIVA_ABORTION_CODE;
Request not terminated.
Drive trouble
Tape trouble
Actor trouble
Disk trouble
The disk is full.
Source/Destination trouble
Resource attribution trouble
Library trouble
Incorrect request parameters
Unknown code
Internal DIVArchive Manager error
This parameter has been deprecated but left intact for software compatibility.
class DIVA_ABORTION_REASON {
public:
DIVA_ABORTION_CODE code;
string description;
};
class DIVA_OBJECT_SUMMARY {
public:
string objectName;
string objectCategory ;
};
The name of the object.
The category of the object.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
The requestNumber identifies no request
The Additional_Info field of the DIVA_REQUEST_INFO structure can contain one or more of the following depending on the request type:
MOB ID is a unique object identifier generated and used by AVID software. The DIVArchive API provides the interface to retrieve the MOB ID for third party vendors after restoring archived objects to Unity. The MOB ID is available in the additionalInfo field of the DIVA_REQUEST_INFO structure. The MOB ID can be retrieved only when the object is restored to the AVID Unity system.
Example MOB ID:
060c2b34020511010104100013-000000-002e0815d552002b-060e2b347f7f-2a80
Depending on the type of request the XML document may be empty, or it may contain any combination of the following elements. See the schema additionalInfoRequestInfo.xsd found in the program\Common\schemas folder of the DIVArchive installation.
When the request was a Restore, N-Restore, Partial File Restore, Copy, or Copy To New the list of media that contains the requested object is provided as follows:
<ADDITIONAL_INFO xmls="http://www.fpdigital.com/divarchive/additionalInfoRequestInfo/v1.0>" <Object>
<Name>Object Name</Name>
<Category>category</Category>
<Instances>
<DiskInstance>
<Id>0</Id>
<Disk>
<MediaName>disk name</MediaName>
</Disk>
</DiskInstance>
<TapeInstance>
<Id>1</Id>
<Tape>
<MediaName>barcode</MediaName>
</Tape>
</TapeInstance>
</Instances>
</Object>
</ADDITIONAL_INFO>
The following is included when the request was a Multiple Restore. If the restore is OK for one of the destinations, but NOT OK for another, the Request State Parameter is DIVA_PARTIALLY_ABORTED and the Request Abortion Code is DIVA_AR_SOURCE_DEST. The status of each destination is as follows:
<ADDITIONAL_INFO xmls="http://www.fpdigital.com/divarchive/additionalInfoRequestInfo/v1.0">"
<request id="12345" type="Restore">
<destination name="destination name one" success="true"/>
<destination name="destination name two" success="false"/>
</request>
</ADDITIONAL_INFO>
The ClipID is included when the request was for a restore to a Quantel device. An ISA gateway never overwrites clips. A new ClipID is created for every imported clip. The ClipID of the created clip will be supplied after the Transfer Complete message as follows:
226 Transfer Complete. [new ClipID]
The Actor captures this new ClipID after the transfer and forwards it to the Manager. To use the DIVArchive API, DIVA_GetRequestInfo must be called. If the request is completed, the new ClipID will be in the Additional Request Information field as follows:
<ADDITIONAL_INFO xmls="http://www.fpdigital.com/divarchive/additionalInfoRequestInfo/v1.0">" <ClipID>98765</ClipID> </ADDITIONAL_INFO>
This function returns a list of Source Servers present in a particular DIVArchive System.
#include "DIVAapi.h" DIVA_STATUS DIVA_getSourceDestinationList ( IN string options; OUT vector<DIVA_SOURCE_DESTINATION_LIST> *&arraysInfo )
Pointer to a list of DIVA_SOURCE_DESTINATION_LIST structures.
#ifndef WIN32
typedef long long __int64;
#endif
typedef enum {
DIVA_SOURCE_TYPE_UNKNOWN = 0,
DIVA_SOURCE_TYPE_MSS,
DIVA_SOURCE_TYPE_PDR,
DIVA_SOURCE_TYPE_SEACHANGE_BMC,
DIVA_SOURCE_TYPE_SEACHANGE_BML,
DIVA_SOURCE_TYPE_SEACHANGE_FTP,
DIVA_SOURCE_TYPE_LEITCH,
DIVA_SOURCE_TYPE_FTP_STANDARD,
DIVA_SOURCE_TYPE_SFTP,
DIVA_SOURCE_TYPE_DISK,
DIVA_SOURCE_TYPE_LOCAL,
DIVA_SOURCE_TYPE_CIFS,
DIVA_SOURCE_TYPE_SIMULATION,
DIVA_SOURCE_TYPE_OMNEON,
DIVA_SOURCE_TYPE_MEDIAGRID,
DIVA_SOURCE_TYPE_AVID_DHM,
DIVA_SOURCE_TYPE_AVID_DET,
DIVA_SOURCE_TYPE_AVID_AMC,
DIVA_SOURCE_TYPE_QUANTEL_ISA,
DIVA_SOURCE_TYPE_QUANTEL_QCP,
DIVA_SOURCE_TYPE_SONY_HYPER_AGENT,
DIVA_SOURCE_TYPE_METASOURCE,
DATA_SOURCE_TYPE_MOVIETOME,
DATA_SOURCE_TYPE_EXPEDAT,
DATA_SOURCE_TYPE_AVID_DIRECT
} DIVA_SOURCE_TYPE;
class DIVA_SOURCE_DESTINATION_LIST{
public:
DIVA_STRING server_Address;
DIVA_STRING server_ConnectOption;
int server_MaxAccess;
int server_MaxReadAccess;
__int64 server_MaxThroughput;
int server_MaxWriteAccess;
DIVA_STRING server_Name;
DIVA_STRING server_ProductionSystem;
DIVA_STRING server_RootPath;
DIVA_SOURCE_TYPE server_SourceType;
};
The server IP address.
The server connection options.
The server maximum number of accesses.
The server maximum number of read accesses.
The server maximum throughput.
The server maximum write access.
The server name.
The server production system name.
The server root path.
The server source type.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
This function returns the list of Storage Plan Names that are defined in the DIVArchive system.
#include "DIVAapi.h" DIVA_STATUS DIVA_getStoragePlanList ( IN string options; OUT vector<DIVA_STRING> *&spList );
A pointer to a list of Storage Plan Names.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
Returns detailed information about a given tape identified by its barcode.
#include "DIVAapi.h"
DIVA_STATUS DIVA_getTapeInfo (
IN DIVA_STRING barcode,
OUT DIVA_DETAILED_TAPE_DESC *tapeInfo
);
The barcode of the tape for which information is to be returned.
The returned information.
class DIVA_DETAILED_TAPE_DESC {
public:
string vsn;
int setID;
string group;
int typeID;
string type;
int fillingRatio;
int fragmentationRatio;
__int64 remainingSize ;
__int64 totalSize ;
bool isInserted;
string externalizationComment;
bool isGoingToBeRepacked;
int mediaFormatId;
};
Tape Set ID
Tape Type ID
Tape Type Name
The tape filling ratio using the equation:
last_written_block / total_block_count.
The tape fragmentation ration using the equation:
1 - (valid_blocks_count) / (last_written_block)
Valid blocks are blocks used for archived objects not currently deleted.
The format of the data on to be used. The value can be DIVA_MEDIA_FORMAT_DEFAULT, DIVA_MEDIA_FORMAT_LEGACY, DIVA_MEDIA_FORMAT_AXF, or DIVA_MEDIA_FORMAT_AXF_10.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
There is no tape associated with the given barcode.
Submits an Insert request to DIVArchive. This request completes when the operator has entered the requested tapes into the library. The application is responsible for managing which tapes must be entered.
#include "DIVAapi.h" DIVA_STATUS DIVA_insertTape ( IN bool require, IN int priorityLevel, OUT int *requestNumber ) DIVA_STATUS DIVA_insertTape ( IN bool require, IN int priorityLevel, IN int acsId, IN int capId, OUT int *requestNumber );
When true, perform a DIVA_require() on every instance located on the successfully inserted tapes.
The priority level for this request. The priorityLevel can be in the range zero to one hundred, or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred the highest priority.
There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred, or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
The numeric ID of the ACS where the Insert operation must be executed.
When acsId = -1 (default used for the first form), the Insert attempt will be performed in all known ACSs.
The numeric ID of the CAP from where tapes will be inserted.
When capId = -1 (default used for the first form), the Insert attempt will be performed in the first available CAP in the specified ACS.
The number identifying the request.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The count of simultaneous requests reached the maximum allowed value. This variable is set in the manager.conf configuration file. The default value is 300.
See also "DIVA_ejectTape".
This function provides the opportunity to link together two existing objects; parent and child. If the objects are linked for Delete, anytime the parent object is deleted, the child will also be deleted. If objects are linked for Restore, anytime the parent object is restored, the child will be restored to the original location from where the child object was archived.
#include "DIVAapi.h" DIVA_STATUS DIVA_linkObjects ( IN DIVA_STRING parentName, IN DIVA_STRING parentCategory, IN DIVA_STRING childName, IN DIVA_STRING childCategory, IN bool cascadeDelete, IN bool cascadeRestore );
The parent object name.
The parent object category.
The child object name.
The child object category.
Indicates if the child object should be deleted along with parent.
Indicates if the child object should be restored along with parent.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
An object with this name and category already exists in the DIVArchive system.
A parameter value was not understood by the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A call to this function will lock an object. Locked objects cannot be restored.
#include "DIVAapi.h" DIVA_STATUS DIVA_lockObject ( IN DIVA_STRING objectName, IN DIVA_STRING category, IN string options );
The name of the object.
The category assigned to the object when it was archived.
Not currently in use.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
Submits an object Restore request to the DIVArchive Manager using several destinations. DIVArchive Manager chooses the appropriate instance to be restored. This function returns as soon as the Manager accepts the request.
The request will continue even if an error occurs with one of the destinations. To check that the operation was successful the application must call the function DIVA_getRequestInfo().
If DIVA_MultipleRestoreObject() is launched with a single destination, the restore automatically converts to a DIVA_RestoreObject().
#include "DIVAapi.h"
DIVA_STATUS DIVA_MultipleRestoreObject (
IN DIVA_STRING objectName,
IN DIVA_STRING objectCategory,
IN vector <DIVA_DESTINATION_INFO> destinations,
IN DIVA_RESTORE_QOS qualityOfService,
IN int priorityLevel,
IN DIVA_STRING restoreOptions,
OUT int *requestNumber
)
public typedef struct _DIVA_DESTINATION_INFO {
DIVA_STRING destination;
DIVA_STRING filePathRoot;
} DIVA_DESTINATION_INFO, *PDIVA_DESTINATION_INFO;
The name of the object to be restored.
The category assigned to the object when it was archived. This parameter can be a null string, however this may result in an error if several objects have the same name.
A list of available destinations (for example, a video server or browsing server) where object files can be restored. The names must be known by the DIVArchive configuration description.
A root folder where the object files will be placed is associated with each destination. If null (string("")), the files will be placed in the FILES_PATH_ROOT folder specified when archiving the object using the DIVA_archiveObject() function.
One of the following codes:
Restoring is performed according to the default Quality Of Service (currently direct and cache for restore operations).
Use cache restore only.
Use direct restore only - no disk instance is created.
Use cache restore if available, or direct restore if cache restore is not available.
Use direct restore if available, or cache restore if direct restore is not available.
Use nearline restore only. Nearline restore will restore from a disk instance if a disk instance exists, otherwise, it will create a disk instance and restore from the newly created disk instance.
Use nearline restore if available, or direct restore if nearline restore is not available.
Additional and optional services are available. To request those services, use a logical OR between the previously documented Quality Of Service parameter and the following constant:
Do not overwrite existing files on the destination server.
The priority level for this request. The priorityLevel can be in the range zero to one hundred, or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred the highest priority.
There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred, or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
Additional options that must be used for performing the transfer of data from DIVArchive to the destination. These options supersede any options specified in the DIVArchive configuration database. Currently the possible values for restoreOptions are:
A null string to specify no objects
-login represents the log in required for some sources. This option obsoletes the -gateway option in earlier releases.
-pass represents the password used with the -login option for some sources.
The request number assigned to this request. This number is used for querying the status or canceling the request.
One of these DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system cannot accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The count of simultaneous requests reached the maximum allowed value. This variable is set in the manager.conf configuration file. The default is 300.
The specified object does not exist in the DIVArchive database.
There is no inserted instance in the library and no Actor could provide a disk instance.
More than one object with the specified name exists in the DIVArchive database.
The object is currently in use (for example, Archived, Restored, Deleted, and so on).
The specified Source/Destination is unknown by the DIVArchive system.
The specified object has instances that are partially deleted.
See also "DIVA_restoreObject", "DIVA_getRequestInfo", and "DIVA_copyToGroup and DIVA_copy".
Submits a Partial Object Restore request to the DIVArchive Manager and the Manager chooses the appropriate instance to be restored. This function returns as soon as the Manager accepts or rejects the request. To check that the operation was successful the application must call the DIVA_getRequestInfo() function.
If the request was not accepted (for example, if the requested object is on media not currently available) the request will generate an error. The media names (tape barcodes and disk names) that contain instances of the object are included in the additionalInfo field of the DIVA_getRequestInfo() response.
The Manager will use the instanceID field to select the instance of the object to use for the Partial Restore operation. The Manager will choose an appropriate instance to restore if DIVA_ANY_INSTANCE is used
DIVArchive supports four types of Partial Restore. The type implemented is determined by the format parameter in the request.
The following describes each type of Partial Object Restore:
The format equals DIVA_FORMAT_BYTES and provides for a range of bytes to be extracted from a particular file in the archive. For example, you can extract bytes 1 to 2000 (the first 2000 bytes of the file), or byte 5000 to the end of the file (or both) and store them to an output file such as movie.avi.
The result of the Byte Offset Partial Restore is usually not playable when applied to video files. Actor will not apply the header, footer, and so on, according to the video format.
To issue a Byte Offset Partial Restore, pass DIVA_FORMAT_BYTES in the format field of the request. Create a DIVA_OFFSET_SOURCE_DEST object (in the fileList parameter of the request). In the object you must specify the sourceFile in the archive and name the output file (destFile). One or more DIVA_OFFSET_PAIR objects must be inserted within the DIVA_OFFSET_SOURCE_DEST object. These offset objects contain the ranges of bytes to be restored to the output file. The fileFolder and range fields within the DIVA_OFFSET_SOURCE_DEST object do not need to be populated.
Example:
start=10000 end=50000
The format equals DIVA_FORMAT_VIDEO_* and provides for a selected portion of a particular media file based on timecode. For example, you could extract from 00:00:04:00 to 00:10:04:00 (a 10 minute segment starting 4 seconds in and ending at 10 minutes and 4 seconds) and place that segment into an output file such as movie.avi. The file is a smaller version of the original movie file.
The result of the Timecode Partial Restore is a valid clip when applied to video files. Actor will apply the header, footer, and so on, according to the video format. The request will be terminated if the Actor cannot parse the format. This type of Partial Restore can only be applied to a valid video clip.
To issue a Timecode Partial Restore populate the format field in the request with the format of the file being partially restored. For example, if the file being restored is a GXF file, specify a value of DIVA_FORMAT_VIDEO_GXF in the format field of the request. DIVArchive provides an auto-detect feature that works for many types of media. Specify DIVA_FORMAT_AUTODETECT in the format field to use auto-detect.
Create a DIVA_OFFSET_SOURCE_DEST object in the fileList parameter of the request. In this object, add a DIVA_OFFSET_PAIR object using the offsetVector parameter that contains the start and end time. Use DIVA_OFFSET_TC_END to indicate the final timecode in the media file. The fileFolder and range fields within the DIVA_OFFSET_SOURCE_DEST object do not need to be populated.
Example:
start=01:01:01:00 end=02:02:02:00
Caution:
In the following process The offsetVector, sourceFile, destFile, and range parameters should not be specified for the Files and Folders Partial Object restore type.The format equals DIVA_FORMAT_FOLDER_BASED and provides for extracting entire files from the archive, or extracting entire directories and their contents. In DIVArchive you can extract multiple files and directories in the same request. The files are restored with the file names and path names that were specified in the archive. No renaming option is valid in Files and Folders Partial Restore. For example, a file archived as misc/12-2012/movie.avi would be partially restored to a misc/12-2012 subdirectory with the name movie.avi.
When a folder is specified in a Files and Folders Partial Restore, the folder and all files within that folder are restored. Each directory to be restored can have the -r option to recursively restore all folders nested within the target folder.
To issue a Files and Folders Partial Restore, the format field in the request must be populated with the DIVA_FORMAT_FOLDER_BASED value. Create a DIVA_OFFSET_SOURCE_DEST object in the fileList parameter of the request. In the object add a DIVA_FILE_FOLDER object in the fileFolder parameter containing the name of the file or folder to be restored, and any options (such as the recursive option) for that directory.
The format equals DIVA_FORMAT_DPX and provides for extracting a range of DPX files from the archive. In this type of restore, the entire object is viewed as a single media item. One DPX file represents one frame of media. Only .dpx, .tif, and .tiff files in the archive are considered frames for the purposes of this command.
The first .dpx, .tif, or .tiff file in the archived object is considered Frame 1, the second .dpx in the archive is Frame 2, and so on.
For example, if you extract frame 10 through frame 15 using DPX Partial Restore, it would restore the 10th .dpx file that appears in the archive, through (and including) the 15th .dpx file, resulting in six total files. Any other files (such as .wav files) are skipped by DPX Partial Restore.
Special frame numbers 0 and -1 may be used to refer to the first and last frame respectively. Frame 0 is valid as the start of a frame range and Frame -1 is valid as the end of a range.
Valid frames and ranges are as follows:
Frame 0 = first frame
Frame 1 = the first frame in the sequence.
Frame n = the nth frame in the sequence.
Frame -1 = last frame
Specifying frame 0 as the last frame is invalid.
Specifying Frame 0 to 0 is invalid and will not return the first frame as you have intended.
Specifying Frame 0 to 1 or Frame 1 to 1 will return the first frame.
Specifying the Frame -1 in the first frame produces an error. If the frame number of the last frame is unknown, you cannot specify Frame -1 to -1 to return the exact last frame.
Examples:
start=0 - end=1This will restore only the first frame.
start=600 - end=635, start=679 - end=779This will restore frames 600 through 635, and frames 679 through 779.
start=810 - end=-1This will restore all frames from frame 810 to the end of the archive.
Caution:
In the following process the offsetVector, sourceFile, destFile, and fileFolder parameters should not be specified for the DPX Partial Object restore type.To issue a DPX Partial Restore you populate the format field in the request with the value DIVA_FORMAT_DPX. Create a DIVA_OFFSET_SOURCE_DEST object in the fileList parameter of the request. In this object, you add a DIVA_RANGE object in the range parameter that contains the start and end frames of the range to be restored.
To specify another range of frames within the same request, another DIVA_OFFSET_SOURCE_DEST object should be added to the request in the same manner.
The actual file name may, or may not, match the frame number in DIVArchive. During the restore process DIVArchive interrogates the archive, finds the file order, and determines the frame number from the resulting file order. It does not consider the file name. The first .dpx, .tif, or .tiff file found is considered frame 1.
You must be careful when archiving DPX files to ensure they can be partially restored properly, in part because DPX Partial Restore does not examine the file name or the DPX header information to determine which file is assigned to which frame. The assignment is based purely on the order in which the .dpx files appear in the archive. By default, the ordering is established by the source and is typically alphanumeric. For example, NTFS DISK Source/Destinations order files and folders case insensitively as a general rule except where diacritical marks such as ', `, ^, and so on are applied.
By default, when DIVArchive encounters a subfolder it recursively processes all of the children of that folder before continuing with other files. If a folder appears in the alphanumeric folder listing it is archived recursively in the order that it appears.
However, this can create some issues. For example, if you want all of the subdirectories of a given directory processed first, followed by the files in the directory, or you might want all files processed first and then subdirectories. In DIVArchive 7.4 the Actor allows the archive options -file_order DIRS_FIRST or -file_order FILES_FIRST to address these issues.
DPX Partial Restore looks at the entire object as a single piece of media. If multiple reels or clips appear in an archive they can be stored in folders and partially restored through a Files and Folders Partial Restore. However, they will be viewed as one long movie clip to DPX Partial Restore. If this is desired, ensure that the directories are sorted alphanumerically in the order the frames should be arranged.
DIVArchive does not perform any special audio handling for DPX media other than what might be embedded in DPX files themselves. DIVArchive supports transcoding of DPX media; however a transcoder may change the file names and (or) file order of the DPX archive.
#include "DIVAapi.h" DIVA_STATUS DIVA_SPEC DIVA_partialRestoreObject ( IN string objectName, IN string objectCategory, IN int instanceID, IN vector <DIVA_OFFSET_SOURCE_DEST> fileList, IN string destination, IN string filesPathRoot, IN DIVA_RESTORE_QOS qualityOfService, IN int priorityLevel, IN string restoreOptions, IN DIVA_FORMAT format, OUT int *requestNumber );
The name of the object to be partially restored.
Category assigned to the object when it was archived. This parameter can be a null string, which can result in an error if several objects have the same name.
The ID of a non-spanned tape instance or DIVA_ANY_INSTANCE.
List of the files of the object to be partially restored. Each structure contains the source file name, a vector of offset pairs, and a destination file name. The same source file can be used in several structures, but destination files must be unique. A file present in the DIVArchive object cannot be in any structure or it won't be restored.
Destination (for example, a video server or browsing server) to put the object files. This name must be known by the DIVArchive configuration description.
The root folder on the destination where the object files will be placed. If this is null (string("")), the files will be placed in the FILES_PATH_ROOT folder specified when archiving the object using the DIVA_archiveObject() function.
One of the following codes:
Restoring is performed according to the default Quality Of Service (currently direct restore).
Use cache restore only.
Use direct restore only.
Use cache restore if available, or direct restore if cache restore is not available.
Use direct restore if available, or cache restore if direct restore is not available.
Additional and optional services are available. To request those services, use a logical OR between the previously documented Quality Of Service parameter and the following constant:
Do not overwrite existing files on the destination server.
The priority level for this request. The priorityLevel can be in the range zero to one hundred, or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred the highest priority.
There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred, or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
Additional options that must be used for performing the transfer of data from DIVArchive to the destination. These options supersede any options specified in the DIVArchive configuration database. Currently the possible values for restoreOptions are:
A null string to specify no objects
-login represents the log in required for some sources. This option obsoletes the -gateway option in earlier releases.
-pass represents the password used with the -login option for some sources.
Offsets must be given as byte offsets. When the offsetVector field of a DIVA_OFFSET_SOURCE_DEST structure contains more than one DIVA_OFFSET_PAIR element DIVArchive creates the destination file by concatenating every corresponding extract.
This has been deprecated but left for compatibility purposes only.
Offsets must be given as timecodes, and the file to be partially restored must be in GXF format.
The fileList vector parameter must contain only one DIVA_OFFSET_SOURCE_DEST element.
The offsetVector vector parameter must contain only one DIVA_OFFSET_PAIR element.
Only the DIVA_QOS_DIRECT_ONLY Quality Of Service is supported for this format.
Offsets must be given as timecodes. The file to be partially restored must be in SAF format and provide an index file.
A part description then contains one DIVA_OFFSET_SOURCE_DEST structure for each WAV file of the clip. There must be at least one WAV file per clip part.
The source file name in each structure must have the .wav or the .WAV extension.
Each structure must contain exactly one DIVA_OFFSET_PAIR structure with a timecode pair equal to the timecode pair associated with the AVI file.
The next part is delimited by the first DIVA_OFFSET_SOURCE_DEST structure associated with an AVI file.
The destination server must support the successive restore of each part, with the AVI file (without WAV file) and then of the WAV files all at once in the same connection session.
Offsets must be given as timecodes. The video file must be encoded using the MPEG2 Transport Stream format. Use this for VELA encoders.
Offsets must be given as timecodes. The file format expected by this type of Partial File Restore is a single MXF file. A detailed matrix of supported MXF files is given in the product description.
Offsets must be given as timecodes. This Partial File Restore format expects a specific object structure. This is applicable to Pinnacle clips composed of three files (header, ft, and std). DIVArchive prefers the MSS Source/Destination type for creating this clip.
The fileList vector parameter must contain only one DIVA_OFFSET_SOURCE_DEST element. The offsetVector vector must contain only one DIVA_OFFSET_PAIR element. The DIVA_OFFSET_SOURCE_DEST element must be associated with the header file only. The destination name is also the header.
Offsets must be given as timecodes. This type of Partial File Restore partially restores QuickTime files (referenced and self-contained clips are supported). A detailed matrix of supported QuickTime clips is given in the product description.
The fileList vector parameter must contain only one DIVA_OFFSET_SOURCE_DEST element. The offsetVector vector must contain only one DIVA_OFFSET_PAIR element. The DIVA_OFFSET_SOURCE_DEST element must be associated with the .mov file only if it's not a self-contained clip.
Offsets must be given as timecodes. The video file must be encoded using the LEITCH Video Server and the format is LXF.
Offsets must be given as timecodes. This type of Partial File Restore partially restores Quantel clips that have been archived with a QUANTEL_QCP Source/Destination type.
Offsets must be given as timecodes. This type of Partial File Restore can detect video clips with the following archive formats:
QuickTime self-contained
QuickTime with referenced media files (the .mov file must be in the first position)
DIF + WAV files
AVI with audio interleaved (separated WAV is not currently supported)
MXF (self-contained)
MPEG PS
LXF
Seachange (the .pd file must be in the first position)
The fileList vector parameter must contain only one DIVA_OFFSET_SOURCE_DEST element. The offsetVector vector must contain only one DIVA_OFFSET_PAIR element. The DIVA_OFFSET_SOURCE_DEST element must be associated with the following:
The .mov file if it is a QuickTime clip.
The .dif file if it is a DV file.
The .avi file if it is an AVI clip.
Specifies a set of files and folders to be restored. You can set a recursive flag to restore subfolders. All specified files and folders are restored.
Specifies a set of intervals, frame X through frame Y, where frames are sorted and traversed alphanumerically.
Only files with .tif or .tiff data formats are supported. All files must have a .dpx extension. The first frame of a DPX object is Frame 1. Frame numbers 0 and -1 refer to the first and last frame respectively.
The request number assigned to this request. This number is used for querying the status or canceling this request.
class DIVA_OFFSET_SOURCE_DEST {
public:
DIVA_STRING sourceFile;
vector<DIVA_OFFSET_PAIR> offsetVector;
DIVA_STRING destFile;
DIVA_FILE_FOLDER fileFolder;
DIVA_RANGE range;
};
The source file name when the format is other than DIVA_FORMAT_FOLDER_BASED or DIVA_FORMAT_DPX.
The vector of intervals to restore. The type of all offsets in all DIVA_OFFSET_SOURCE_DEST structures must be compliant with the format parameter of the Partial File Restore request. Valid only when the format is other than DIVA_FORMAT_FOLDER_BASED or DIVA_FORMAT_DPX.
The file name to be used at the destination. Valid only when format is other than DIVA_FORMAT_FOLDER_BASED or DIVA_FORMAT_DPX.
The file or folder name. Used only when the format is DIVA_FORMAT_FOLDER_BASED.
The range of frames to be restored. Used only when the format is DIVA_FORMAT_DPX.
DIVA_OFFSET_PAIR // This class only has public functions.
The following are the constructors:
DIVA_SPEC DIVA_OFFSET_PAIR (__int64 pBegin, __int64 pEnd, bool _isTimeCode)Constructor for use with byte offsets. DIVA_OFFSET_BYTE_BEGIN and DIVA_OFFSET_BYTE_end are valid.
DIVA_SPEC DIVA_OFFSET_PAIR (const DIVA_STRING &pBegin, const DIVA_STRING &pEnd)Constructor for use with timecode offsets. Timecodes are formatted as HH:MM:SS:FF.
The following are the attribute accessors:
DIVA_SPEC bool isTimeCode();This is true if the offset pair was constructed with timecode offsets.
DIVA_SPEC DIVA_STRING getTimeCodeBegin();Return the beginning offset as a timecode.
DIVA_SPEC DIVA_STRING getTimeCodeEnd();Return the ending offset as a timecode.
DIVA_SPEC __int64 getByteBegin();Return the beginning offset as bytes.
DIVA_SPEC __int64 getByteEnd();Return the ending offset as bytes.
class DIVA_FILE_FOLDER {
public:
DIVA_STRING fileFolder;
DIVA_STRING option
};
The file or folder name.
Options (for example, -r to recurse folders).
class DIVA_RANGE {
public:
int startRange;
int endRange;
};
The first frame number to be restored.
The last frame number to be restored.
The format gives information about how to interpret the interval and about which specific operation should eventually be performed.
typedef enum {
DIVA_FORMAT_BYTES = 0,
DIVA_FORMAT_BYTES_HEADER,
DIVA_FORMAT_VIDEO_GXF,
DIVA_FORMAT_VIDEO_SEA,
DIVA_FORMAT_VIDEO_AVI_MATROX,
DIVA_FORMAT_VIDEO_MPEG2_TS,
DIVA_FORMAT_VIDEO_MXF,
DIVA_FORMAT_VIDEO_PINNACLE,
DIVA_FORMAT_VIDEO_OMNEON,
DIVA_FORMAT_VIDEO_LEITCH,
DIVA_FORMAT_VIDEO_QUANTEL,
DIVA_FORMAT_AUTODETECT,
DIVA_FORMAT_FOLDER_BASED,
DIVA_FORMAT_DPX
} DIVA_FORMAT;
Raw bytes
GXF video format
Seachange video format
Matrox-specific AVI format (+ WAV files)
MPEG Transport Stream
MXF video format
Pinnacle video format
Omneon video format
Leitch video format
Quantel QCP video format
Automatic format detection
Fully restore the specified files and (or) folders
DPX video format
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
DIVArchive can no longer accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. You set the timeout duration using the DIVA_API_TIMEOUT variable. The default value is one hundred-eighty (180) seconds.
An unknown status was received from the DIVArchive Manager.
The DIVArchive Manager or DIVArchive API detected an internal error.
The DIVArchive Manager did not understand a parameter value.
The count of simultaneous requests reached the maximum allowed value. You set this variable in the manager.conf configuration file. The default value is three hundred.
The specified object does not exist in the DIVArchive database.
There is no inserted instance in the library and no Actor could provide a disk instance.
More than one object with the specified name exists in the DIVArchive database.
The instance specified for restoring this object is ejected, or the Actor owning the specified disk instance is not available.
The instance specified for restoring this object does not exist.
The object is currently in use (that is, being Archived, Restored, Deleted, and so on).
The specified Source/Destination is unknown by the DIVArchive system.
The specified object has instances that are partially deleted.
See also "DIVA_restoreObject", "DIVA_getRequestInfo", and "DIVA_getPartialRestoreRequestInfo".
Indicates to the DIVArchive Manager that this instance can be externalized. This function has no effect if the instance has already been released. The list of instances that are RELEASED and INSERTED may be retrieved and shown at the Control GUI.
#include "DIVAapi.h" DIVA_STATUS DIVA_release ( IN DIVA_STRING objectName, IN DIVA_STRING categoryName, IN int instanceID );
The name of the object to be copied.
The category assigned to the object when it was archived. This parameter can be a null string; however this may result in an error if several objects have the same name.
A value of DIVA_EVERY_INSTANCE forces this function to apply to every instance of the given object.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
DIVArchive can no longer accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. You set the timeout duration using the DIVA_API_TIMEOUT variable. The default value is one hundred-eighty (180) seconds.
An unknown status was received from the DIVArchive Manager.
The DIVArchive Manager or DIVArchive API detected an internal error.
The DIVArchive Manager did not understand a parameter value.
The specified object does not exist in the DIVArchive database.
The instance specified for restoring this object does not exist.
No tape instance exists for this object.
The specified object has instances that are partially deleted.
More than one object with the specified name exists in the DIVArchive database.
See also "DIVA_require".
Indicates to the DIVArchive Manager that this instance must be inserted. If the instance is already inserted, this function has no effect. The list of instances that are REQUIRED and EJECTED can be retrieved and shown at the Control GUI.
#include "DIVAapi.h" DIVA_STATUS DIVA_require( IN DIVA_STRING objectName, IN DIVA_STRING categoryName, IN int instanceID );
Name of the object to be copied.
Category assigned to the object when it was archived. This parameter can be a null string, however this may result in an error if several objects have the same name.
A value of DIVA_EVERY_INSTANCE forces the function to apply to every instance of the given object.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
DIVArchive can no longer accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. You set the timeout duration using the DIVA_API_TIMEOUT variable. The default value is one hundred-eighty (180) seconds.
An unknown status was received from the DIVArchive Manager.
The DIVArchive Manager or DIVArchive API detected an internal error.
The DIVArchive Manager did not understand a parameter value.
The specified object does not exist in the DIVArchive database.
The instance specified for restoring this object does not exist.
No tape instance exists for this object.
The specified object has instances that are partially deleted.
More than one object with the specified name exists in the DIVArchive database.
See also "DIVA_release".
Restores an object from a specific instance. If the instance is externalized the operation fails even if there are other instances available for the object.
#include "DIVAapi.h" DIVA_STATUS DIVA_restoreInstance ( IN DIVA_STRING objectName, IN DIVA_STRING categoryName, IN int instanceID, IN DIVA_STRING destination, IN DIVA_STRING filesPathRoot, IN DIVA_RESTORE_QOS qualityOfService, IN int priorityLevel, IN DIVA_STRING restoreOptions, OUT int *requestNumber );
Name of the object to be restored.
Category assigned to the object when it was archived. This parameter can be a null string, however this may result in an error if several objects have the same name.
The instance identifier.
The destination (for example, a video server or browsing server) where the object files will be restored. This name must be known by the DIVArchive configuration description.
Root folder on the destination where the object files will be placed. If this is null (string("")), the files will be placed in the FILES_PATH_ROOT folder specified when archiving the object using the DIVA_archiveObject() function.
One of the following codes:
Restoring is performed according to the default Quality Of Service (currently direct and cache for restore operations).
Use cache archive only.
Use direct restore only - no disk instance is created.
Use cache restore if available, or direct restore if cache restore is not available.
Use direct restore if available, or cache restore if direct restore is not available.
Additional and optional services are available. To request those services, use a logical OR between the previously documented Quality Of Service parameter and the following constant:
Do not overwrite existing files on the destination server.
The priority level for this request. The priorityLevel can be in the range zero to one hundred, or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred the highest priority.
There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred, or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
Additional options that must be used for performing the transfer of data from DIVArchive to the destination. These options supersede any options specified in the DIVArchive configuration database. Currently the possible values for restoreOptions are as follows:
A null string specifies no options.
A user name and password is required to log in to some sources. This option obsoletes the -gateway option from earlier releases.
The password used with -login.
A number identifying this request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
DIVArchive can no longer accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. You set the timeout duration using the DIVA_API_TIMEOUT variable. The default value is one hundred-eighty (180) seconds.
An unknown status was received from the DIVArchive Manager.
The DIVArchive Manager or DIVArchive API detected an internal error.
The DIVArchive Manager did not understand a parameter value.
Count of simultaneous requests has reached the maximum allowed value. This variable is set in the manager.conf configuration file. The default is 300.
The specified object does not exist in the DIVArchive database.
More than one object with the specified name exists in the DIVArchive database.
The specified instance for restoring this object is ejected, or the Actor owning the specified disk instance is not available.
The instance specified for restoring this object does not exist.
The object is currently in use (being Archived, Restored, Deleted, and so on).
The specified Source/Destination is not known by the DIVArchive system.
The specified object has instances that are partially deleted.
See also "DIVA_archiveObject" and "DIVA_getObjectInfo".
Submits an Object Restore request to the DIVArchive Manager and the Manager chooses the appropriate instance to be restored. This function returns as soon as the Manager accepts the request. To check that the operation was successful, the application must call the function DIVA_getRequestInfo().
If the requested object is on media that is not available, the request will fail. The media names (tape barcodes and disk names) that contain instances of the object will be included in the additionalInfo field of the DIVA_getRequestInfo() response.
#include "DIVAapi.h" DIVA_STATUS DIVA_restoreObject ( IN DIVA_STRING objectName, IN DIVA_STRING objectCategory, IN DIVA_STRING destination, IN DIVA_STRING filesPathRoot, IN DIVA_RESTORE_QOS qualityOfService, IN int priorityLevel, IN DIVA_STRING restoreOptions, OUT int *requestNumber );
Name of the object to be restored.
Category assigned to the object when it was archived. This parameter can be a null string, but this may result in an error if several objects have the same name.
The destination (for example, a video server or browsing server) where the object files will be restored. This name must be known by the DIVArchive configuration description.
Root folder on the destination where the object files will be placed. If this is null (string("")), the files will be placed in the FILES_PATH_ROOT folder specified when archiving the object using the DIVA_archiveObject() function.
One of the following codes:
Restoring is performed according to the default Quality Of Service (currently direct and cache for restore operations).
Use cache restore only.
Use direct restore only - no disk instance is created.
Use cache restore if available, or direct restore if cache restore is not available.
Use direct restore if available, or cache restore if direct restore is not available.
Additional and optional services are available. To request those services, use a logical OR between the previously documented Quality Of Service parameter and the following constant:
Use nearline restore only. Nearline restore will restore from a disk instance if it exists, otherwise, it will create a disk instance and restore from the newly created disk instance.
Use Nearline restore if available, or direct restore if Nearline restore is not available. Additional and optional services are available. To request those services use a logical OR between the previously documented Quality Of Service parameter and the following constants:
Do not overwrite existing files on the destination server.
Do not check existence of the clip on the server.
Force delete and rewrite if object exists on the server.
Operate using the default setting in the Manager configuration.
The priority level for this request. The priorityLevel can be in the range zero to one hundred, or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred the highest priority.
There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred, or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
Additional options that must be used for performing the transfer of data from DIVArchive to the destination. These options supersede any options specified in the DIVArchive configuration database. Currently the possible values for restoreOptions are as follows:
A null string specifies no options.
A user name and password is required to log in to some sources. This option obsoletes the -gateway option from earlier releases.
The password used with -login.
Request number assigned to this request. This number is used for querying the status or canceling this request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
DIVArchive can no longer accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. You set the timeout duration using the DIVA_API_TIMEOUT variable. The default value is one hundred-eighty (180) seconds.
An unknown status was received from the DIVArchive Manager.
The DIVArchive Manager or DIVArchive API detected an internal error.
The DIVArchive Manager did not understand a parameter value.
The count of simultaneous requests reached the maximum allowed value. You set this variable in the manager.conf configuration file. The default value is three hundred.
The specified object does not exist in the DIVArchive database.
There is no inserted instance in the library and no Actor could provide a Disk Instance.
More than one object with the specified name exists in the DIVArchive database.
The object is currently in use (being Archived, Restored, Deleted, and so on).
The specified Source/Destination is not known by the DIVArchive system.
The specified object has instances that are partially deleted.
See also "DIVA_getRequestInfo" and "DIVA_copyToGroup and DIVA_copy".
Submits a Transcode Archive request to the DIVArchive Manager. The original object will be restored to the local Actor cache then transcoded to the format defined in the option field. A new object containing the transcoded clip will then be archived back to DIVArchive.
#include "DIVAapi.h" DIVA_STATUS DIVA_transcodeArchive ( IN DIVA_STRING parentObjectName, IN DIVA_STRING parentObjectCategory, IN int instance, IN DIVA_STRING objectName, IN DIVA_STRING objectCategory, IN DIVA_STRING mediaName, IN DIVA_STRING comments, IN DIVA_STRING archiveOptions, IN DIVA_ARCHIVE_QOS qualityOfService, IN bool bCascadeDelete, IN int priorityLevel, OUT int *requestNumber );
Name of the original object to be transcoded.
Category assigned to the original object.
Instance of the parent object. The default is -1.
Name of the resulting transcoded object from the transcoding operation.
Category of the transcoded object.
The tape group or disk array where the object is to be saved. The media may be defined as follows:
Provide the tape group or disk array name as defined in the configuration. The object is saved to the specified media and assigned to the default Storage Plan (SP).
Provide a Storage Plan Name (SP Name) as defined in the configuration. The object will be assigned to the specified Storage Plan and saved to the default media specified.
The object is saved to the specified media as in Name, and assigned to the specified Storage Plan as in SP Name. The Name and the SP Name must be separated by the & delimiter (this is configurable).
When this parameter is a null string, the default group of tapes called DEFAULT is used. Complex objects can only be saved to AXF media types.
Optional information describing the object. This can be a null string.
Additional options that must be used for performing the transfer of data from the source to DIVArchive. These options supersede any options specified in the DIVArchive configuration database. Currently the possible values for archiveOptions are:
-tr_archive_format FORMATDestination format of the retrieved object. This is required.
-tr_names trans1Names of the transcoders that have to perform this operation. If more than one transcoder is selected, the performing transcoder will be chosen based on the current loading. If this option is not specified, the performing transcoder will be chosen from all DIVArchive transcoders based on the current loading. This is optional.
-tr_names trans1,trans2Names of the transcoders that have to perform this operation. Multiple transcoders are identified in a comma separated list (trans1, trans2, and so on). If more than one transcoder is selected, the performing transcoder will be chosen based on the current loading. If this option is not specified, the performing transcoder will be chosen from all DIVArchive transcoders based on the current loading. This is optional.
One of the following codes:
Restoring is performed according to the default Quality Of Service (currently cache for archive operations).
Use cache archive only.
Use direct archive only - no disk instance is created.
Use cache archive if available, or direct archive if cache archive is not available.
Use direct archive if available, or cache archive if direct archive is not available.
Shows if transcoded object is linked to the original object. If true both the original object and the transcoded object will be deleted.
The priority level for this request. The priorityLevel can be in the range zero to one hundred, or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred the highest priority.
There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred, or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
Request number assigned to this request. This number is used for querying the status or canceling this request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system can no longer accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. You set the timeout duration using the DIVA_API_TIMEOUT variable. The default value is one hundred-eighty (180) seconds.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The count of simultaneous requests reached the maximum allowed value. You set this variable in the manager.conf configuration file. The default value is three hundred.
The specified object already exists in the DIVArchive database.
The specified object has instances that are partially deleted.
See also "DIVA_linkObjects".
Submits a Transfer Files request to the DIVArchive Manager. The request will transfer files from a remote server (the source) to another remote server (the destination). This function returns as soon as the Manager accepts the request. The application must call the function DIVA_getRequestInfo()to confirm that the operation completed successfully.
#include "DIVAapi.h" DIVA_STATUS DIVA_transferFiles ( IN DIVA_STRING source, IN DIVA_STRING sourcePathRoot, IN vector<DIVA_STRING> filenamesList, IN DIVA_STRING destination, IN DIVA_STRING destinationPathRoot, IN int priorityLevel, OUT int *requestNumber );
Name of the source (for example, a video server or browsing server). This name must be known by the DIVArchive configuration description.
Root folder for the files specified by the filenamesList parameter.
List of file path names relative to the folder specified by the sourcePathRoot parameter. When the sourcePathRoot is null, path names must be absolute names.
Name of the destination (for example a video server or browsing server). This name must be known by the DIVArchive configuration description.
Root folder where the files will be placed at the destination.
The priority level for this request. The priorityLevel can be in the range zero to one hundred, or the value DIVA_DEFAULT_REQUEST_PRIORITY. The value zero is the lowest priority and one hundred the highest priority.
There are six predefined values as follows:
DIVA_REQUEST_PRIORITY_MIN
DIVA_REQUEST_PRIORITY_LOW
DIVA_REQUEST_PRIORITY_NORMAL
DIVA_REQUEST_PRIORITY_HIGH
DIVA_REQUEST_PRIORITY_MAX
DIVA_DEFAULT_REQUEST_PRIORITY
When the DIVA_DEFAULT_REQUEST_PRIORITY value is used, the Manager uses the default priority defined in the Manager configuration for the request.
Using a value either outside of the range of zero to one hundred, or predefined values yields a DIVA_ERR_INVALID_PARAMETER error.
Request number assigned to this request. This number is used for querying the status or canceling this request.
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system is no longer able to accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.
A parameter value was not understood by the DIVArchive Manager.
The count of simultaneous requests reached the maximum allowed value. This variable is set in the manager.conf configuration file and the default value is three hundred.
The specified Source/Destination is not known by the DIVArchive system.
Also see "DIVA_getRequestInfo".
A call to this function will unlock an object. Locked objects cannot be restored.
#include "DIVAapi.h" DIVA_STATUS DIVA_unlockObject ( IN DIVA_STRING objectName, IN DIVA_STRING category, IN string options );
Name of the object.
The category assigned to the object when it was archived.
TBD
One of the following DIVA_STATUS constants defined in DIVAapi.h:
The request was correctly submitted and accepted by the DIVArchive Manager.
No connection is open.
The DIVArchive system is no longer able to accept connections and queries.
The connection with the DIVArchive Manager was broken.
The timeout limit was reached before communication with the DIVArchive Manager could be performed. The timeout duration is set by the DIVA_API_TIMEOUT variable and equals one hundred-eighty (180) seconds by default.
An unknown status was received from the DIVArchive Manager.
An internal error was detected by the DIVArchive Manager or by the DIVArchive API.