DIVArchive 7.6 supports 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. See Appendix A for Oracle DIVArchive options and licensing information.
This chapter includes the following information:
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.6 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.
DIVArchive and Oracle DIVAnet are backward compatible with all earlier releases of the DIVArchive C++ API. Therefore, DIVArchive C++ API 7.6.x is compatible with any DIVArchive release 7.6 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 for Java API document location information.
Oracle DIVA Enterprise Connect and Web Services API: Oracle DIVA Enterprise Connect is a standards-based Web Service API implemented on the Oracle WebLogic Suite. DIVA Enterprise Connect interacts with the Oracle DIVArchive and Oracle DIVAnet systems, acting as a web service binding for the DIVArchive API.
Oracle DIVA Enterprise Connect includes the DIVA Web Services API, which is a set of interface definition files and documentation for universal use by applications supporting Web Services communications.
See the Oracle DIVA Enterprise Connect documentation set in the Oracle DIVA Enterprise Connect documentation library for more information.
The following new and enhanced features and functionality are included in DIVArchive 7.6:
The Source Media Priority is reported in the getArrayList and getGroupsList calls.
The storage options are reported in the getArrayList call, and storage options for each disk instance is returned from the getObjectInfo and getObjectDetailsList calls.
Secure Socket Layer authentication has been added in DIVArchive 7.6. See SSL (Secure Sockets Layer) and Authentication for more information.
A new call named DIVA_SSL_initialize has been added to set the environment for secure communications with the Manager service. Starting with DIVArchive 7.6 you must make this call before calling DIVA_connect or the connection will fail. See DIVA_SSL_initialize for more information on this call.
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 two hundred 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 following sections describe securing communications when using one of the available DIVArchive APIs. The JAVA and C++ Initiators use the default keys and certificates file in the %DIVA_API_HOME%/Program/security folder when connecting to the Manager.
The Manager Service is backward compatible with earlier versions of the DIVArchive JAVA, C++, Web Services APIs, Oracle DIVA Enterprise Connect 1.0, and DIVAnet 2.2 establishing connections over regular sockets. The DIVArchive 7.6 (and later) Java and C++ API releases can establish Manager communications using secure, or unsecure, sockets. Secure communications are only supported by the Manager.
The Manager Service supports both secure and unsecure communication ports simultaneously. The default secure port is tcp/8000, and the default unsecure port is tcp/9000.
See the Oracle DIVArchive Java API documentation for information on the new methods added to the SessionParameters Class for secure communications. See the Oracle DIVArchive Java API Readme in the Oracle DIVArchive Additional Features documentation library for the location of the full Java API documentation (delivered with the API).
The DIVArchive C++ API includes a new call named DIVA_SSL_initialize added to set the environment for secure communication with the Manager Service. You must call DIVA_SSL_initialize before calling DIVA_connect starting with DIVArchive 7.6, otherwise the DIVA_connect call will fail.
DIVArchive consist of services in Java and C++. The format in how certificates and keys are represented are different in each. DIVArchive has the keys and certificates for JAVA services in a Java Keystore file, and in PEM (Privacy Enhanced Mail) format files for the C++ services.
The Manager can simultaneously support two communications ports - one secure, and one unsecure. The default secure port number is 8000 and the unsecure default port number is 9000.
All internal DIVArchive 7.6 services (Control GUI, Configuration Utility, DBBackup, Migration Utility, Actor, SPM, DFM, SNMP, Robot Manager, RDTU, and Migration Services) can only connect to secure ports. The control GUI will report an SSL Handshake Timeout if you attempt to connect to the non-secure port. Clients using the Java or C++ API are allowed to connect to either port.
The following is a relative snippet from the Manager configuration file:
# Port number on which the DIVA Manager is waiting for incoming connections. # Note: If you are using a Sony library and plan to execute the DIVA Manager # on the same machine as the PetaSite Controler (PSC) software, be aware # that the PSC server uses the 9000 port and that this cannot be modified. # In that situation, you have to use a different port for the DIVA Manager. # This same warning applies to FlipFactory which uses ports 9000 and 9001. # The default value is 9000. DIVAMANAGER_PORT=9000 # Secure port number on which the DIVA Manager is waiting for incoming connections. # The default value is 8000. DIVAMANAGER_SECURE_PORT=8000
A new folder called %DIVA_API_HOME%/security is added to the DIVArchive API installation structure as follows:
%DIVA_API_HOME%
security
conf
The conf folder contains the SSLSettings.conf file that is used to configure the SSL handshake timeout.
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.6. 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 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")
Footnote Legend
Footnote 1: The operatorsnew and delete are not considered function members.