DIVArchive 7.4 enables interoperability among systems, helping to ensure long-term accessibility to valued content, and keeping up with evolving storage technologies.
The architecture of DIVArchive allows the integration of many different types of servers and technologies, for example Broadcast Video Servers, Storage Area Networks, and Enterprise Tape Libraries.
The main Oracle DIVArchive API is written in the C++ programming language. All of the definitions are contained in the include file named DIVAapi.h. In this document, parameters in function signatures are qualified by IN and OUT to specify whether the parameter is passed as an input or an output to the function. These qualifiers are not part of the C++ language and are only used for ease of readability. You must consider that these qualifiers are equivalent to the following macro definitions:
#define IN
#define OUT
In this document, the term structure identifies both C-like structures and classes which have only public data members and no function membersFoot 1 . Interfaces described in this document show only data members, not constructors or destructors.
The DIVArchive and DIVAnet API use only standard data types provided directly by the C++ language, and the vector data type provided by the Standard Template Library (STL). For more information about the vector data type refer to the STL documentation on the OTN.
Note:
The DIVArchive API is not supported under the Solaris operating system.DIVArchive 7.4 does not currently support the following API calls and features when used with complex objects. Even if they are enabled, they will not be executed and no warnings will be generated.
VerifyFollowingArchive
VerifyFollowingRestore
DeleteOnSource
DeleteFile
getObjectListbyFileName
The getObjectInfo and getObjectDetailsList will only return a single file
When copying complex objects to legacy-formatted media, the Copy request terminates returning a Can't write a complex object in Legacy format error, and an error code through the API.
The following new and enhanced features and functionality are included in DIVArchive 7.4:
DIVA_getObjectInfo
The file 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 an Object Info message.
DIVA_getObjectDetailsList
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.
DIVA_getFilesAndFolders
The file list contains empty files for non-complex objects.
The folders list contains all folders in a non-complex object.
Both the Folders Only and Files and Folders options are available for use with non-complex objects.
The following sections cover the supported API compilers.
These section describe using the Visual C++ compiler on the Windows operating system.
There are two separate variants of the DIVArchive API for Windows: 32-bit and 64-bit. The 32-bit model can be used on both x86 and x64 platforms. However, the 64-bit variant requires a 64-bit platform. The DIVArchive API for Windows is supported on the following Windows releases:
Microsoft Windows Server 2012
Microsoft Windows Server 2012 R2
Microsoft Windows Server 2008
Microsoft Windows Server 2008 x64
Microsoft Windows Server 2008 R2
The DIVArchive API is compiled and tested using the following compilers:
Including Microsoft Platform SDK 7.0a (April 2010)
Including Microsoft Platform SDK 7.1A (November 2012)
Including Microsoft Platform SDK 8.0A (October 2013)
The API is delivered with both static and dynamic libraries. Each library is available in a standard format with debug support and Unicode compatibility. The different options may be found in the following build directories:
Static_Release
Static_Debug
Dynamic_Release
Dynamic_Debug
Choose the 8 Bytes setting for the Strict Member Alignment option under C/C++ Code Generation in the project settings.
The following list identifies the library path that corresponds to each run time library. The run time library is normally changed automatically depending upon the selected build configuration.
Static_Release
Static_Debug
Dynamic_Release
Dynamic_Debug
You must include the DIVArchive API.lib file, or the path to this file, in the link settings (see "Initiator Sample Program API Usage"). The API can be included in an application compiled with either the IDE or a script using the command line compiler.
Once your application is built, you must either add the folder where the DIVArchive API.dll file is located to your PATH environment variable, or copy the DIVArchive API.dll file into the folder containing your executable file.
The Initiator program is included with the DIVArchive APi and is an example of the API usage. This is a command line program that uses the API to send requests and get data from DIVArchive. Use the following project files to view the compiler settings and build the program:
doc\CppInitiator\InitiatorVc100.vcxproj(64-bit API)
doc\CppInitiator\InitiatorVc110.vcxproj(64-bit API)
doc\CppInitiator\InitiatorVc120.vcxproj(64-bit API)
These sections describe using the C++ compiler on the Linux operating system platform.
The DIVArchive API for Linux is supported on Oracle Linux. The API was built with the C++ compiler and Oracle Solaris Studio library. The following list identifies the supported CC release and Oracle Solaris Studio library release.
Oracle Linux 7 x86_64 (64-bit) operating system
Oracle Solaris Studio 12.4 library
The following command returns the CC release level:
[root@LinuxBuildVM /]# CC -V CC: Sun C++ 5.13 Linux_i386 2014/10/20
The DIVArchive API may work on other Linux platforms; however it is only officially validated in the environment described here. Support for the older release previously built on SuSe Linux 9.0 is discontinued in DIVArchive 7.4. For all development projects, use of the latest release is strongly recommended.
The DIVArchive API is delivered with the x86_64_Release_unicode shared library for the Linux platform. The release is located in the DIVA/api/lib directory. The library is built in Release Mode and does not contain symbolic information.
Header files that may be required to compile an application with the DIVArchive API libraries are delivered in the DIVA/api/include directory.
For reference, a sample application is provided in the DIVA/api/doc/CPPInitiator directory along with its source code. The Visual Studio project file for Microsoft Windows, and sample makefiles for Linux platforms are also provided. Refer to the sample makefiles provided in the DIVA/api/doc/CPPInitiator directory for platform-specific compiler and linker options.
The DIVArchive API supports using multiple threads concurrently with the following restrictions (see the related function's specific documentation for additional information):
The DIVA_connect() and DIVA_disconnect() functions share the same critical section. Although multiple simultaneous connections are supported, they must be opened and closed one at a time.
The init, get, and close functions used to retrieve list information (Objects List or Objects Tape Information List) also use a Critical Section to prevent concurrent threads reinitializing the list while another thread is currently reading it. The critical section is entered when the list is initialized and left when the list is closed. There are two separate critical sections, one for each type of list.
All of the other DIVArchive functions may be called simultaneously by different threads. For example, one thread can call the DIVA_archiveObject() function while another one is calling DIVA_getArchiveSystemInfo().
The number of connections to the Oracle DIVArchive Manager is limited by the Manager and set in the Manager configuration file. The default configuration is thirty connections, which includes GUI connections and all API connections. Once the configured limit is reached, the API will not allow additional connections to be created. See the manager.conf file for additional information.
Caution:
It is recommended that a new connection not be created for each request or command sent to the Manager. Whenever possible allow the connection to remain open for the lifetime of the session, or application.The DIVArchive API (and other DIVArchive components) support wide character strings. Only 64-bit Unicode is delivered with the API. You must define the _UNICODE constant before including the DIVAapi.h header file to be able to use the wchar_t and wstring.
In addition, the application must be linked with one of the Unicode releases in the library (for example, in lib/Release_Unicode).
Defining, or not defining, the _UNICODE macro will change the implementation of the DIVA_STRING and DIVA_CHAR types.
The _T macro is recommended when working with static strings:
Example:
_T("Hello")
DIVArchive and Oracle DIVAnet are backward compatible with all earlier releases of the DIVArchive C++ API. Therefore, DIVArchive C++ API 7.3.x is compatible with any DIVArchive release 7.3 and later.
Any new features added to DIVArchive after the release of the C++ API in use will not be available; the client system must be upgraded to the latest release to use all features.
The API described in this document is for use with applications implemented in C++. However, the following additional APIs are available:
Oracle DIVArchive Java API: A set of libraries, samples and documentation for use with applications implemented in Java. See the Oracle DIVArchive Java API Readme in the Oracle DIVArchive Additional Features Documentation library on OTN for Java API document location information.
Oracle DIVArchive Web Services (WS) API: A set of interface definition files and documentation for universal use by applications supporting Web Services communications. See the Oracle DIVArchive WS API Reference and the Oracle DIVArchive WS API User's Guide in the Oracle DIVArchive Additional Features documentation library on OTN for more information.
Footnote Legend
Footnote 1: The operatorsnew and delete are not considered function members.