Using The Application Programming Interface
Using The Application Programming Interface
Version 8.1.2
IBM
IBM Spectrum Protect
Version 8.1.2
IBM
Note:
Before you use this information and the product it supports, read the information in “Notices” on page 207.
This edition applies to version 8, release 1, modification 2 of IBM Spectrum Protect (product numbers 5725-W98,
5725-W99, and 5725-X15) and to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 1993, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this publication . . . . . . . . v Buffer copy elimination . . . . . . . . . 42
Who should read this publication . . . . . . . v API encryption . . . . . . . . . . . . 44
Publications . . . . . . . . . . . . . . v Data deduplication . . . . . . . . . . . . 48
Conventions used in this publication . . . . . . v API client-side data deduplication . . . . . . 50
Server-side data deduplication . . . . . . . 53
What's new in Version 8.1.2. . . . . . vii Application failover . . . . . . . . . . . 53
Failover status information . . . . . . . . 54
Example flow diagrams for backup and archive . . 56
Chapter 1. API overview . . . . . . . . 1 Code example of API functions that send data to
Understanding configuration and options files . . . 1 IBM Spectrum Protect storage . . . . . . . 59
Setting up the API environment . . . . . . . . 3 File grouping . . . . . . . . . . . . . . 60
Receiving data from a server . . . . . . . . 63
Chapter 2. Building and running the Partial object restore or retrieve. . . . . . . 63
sample API application . . . . . . . . 5 Restoring or retrieving data . . . . . . . . 64
UNIX or Linux sample application source files . . . 5 Example flow diagrams for restore and retrieve 68
Building the UNIX or Linux sample application . 6 Code example of receiving data from a server . . 69
Windows 64-bit sample application . . . . . . . 7 Updating and deleting objects on the server . . . 70
Deleting objects from the server . . . . . . 71
Chapter 3. Considerations for designing Logging events . . . . . . . . . . . . . 71
State diagram summary for the IBM Spectrum
an application . . . . . . . . . . . . 9 Protect API . . . . . . . . . . . . . . 72
Determining size limits . . . . . . . . . . 12
Maintaining API version control . . . . . . . 12
Using multithreading . . . . . . . . . . . 14
Chapter 4. Understanding
Signals and signal handlers . . . . . . . . . 14 interoperability . . . . . . . . . . . 75
Starting or ending a session . . . . . . . . . 15 Backup-archive client interoperability. . . . . . 75
Session security . . . . . . . . . . . . 16 Naming your API objects . . . . . . . . . 75
Controlling access to password files . . . . . 19 Backup-archive client commands you can use
Creating an administrative user with client with the API . . . . . . . . . . . . . 77
owner authority . . . . . . . . . . . . 20 Operating system interoperability . . . . . . . 78
Object names and IDs . . . . . . . . . . . 21 Backing up multiple nodes with client node proxy
File space name . . . . . . . . . . . . 21 support. . . . . . . . . . . . . . . . 78
High-level and low-level names . . . . . . 22
Object type . . . . . . . . . . . . . 22 Chapter 5. Using the API with Unicode 81
Accessing objects as session owner . . . . . . 23 When to use Unicode . . . . . . . . . . . 81
Accessing objects across nodes and owners . . . . 23 Setting up Unicode . . . . . . . . . . . . 81
Managing file spaces . . . . . . . . . . . 24
Associating objects with management classes . . . 26 Chapter 6. API function calls . . . . . 83
Query management classes . . . . . . . . 28 dsmBeginGetData . . . . . . . . . . . . 85
Expiration/deletion hold and release . . . . . . 28 dsmBeginQuery . . . . . . . . . . . . . 87
Archive data retention protection . . . . . . 29 dsmBeginTxn . . . . . . . . . . . . . . 91
Querying the IBM Spectrum Protect system . . . 31 dsmBindMC . . . . . . . . . . . . . . 92
Example of querying the system . . . . . . 32 dsmChangePW . . . . . . . . . . . . . 93
Server efficiency . . . . . . . . . . . . . 33 dsmCleanUp . . . . . . . . . . . . . . 94
Sending data to a server . . . . . . . . . . 34 dsmDeleteAccess . . . . . . . . . . . . 95
The transaction model . . . . . . . . . . 34 dsmDeleteFS . . . . . . . . . . . . . . 95
File aggregation . . . . . . . . . . . . 35 dsmDeleteObj . . . . . . . . . . . . . 96
LAN-free data transfer . . . . . . . . . 35 dsmEndGetData . . . . . . . . . . . . . 97
Simultaneous-write operations . . . . . . . 35 dsmEndGetDataEx . . . . . . . . . . . . 98
Enhancing API performance . . . . . . . . 36 dsmEndGetObj . . . . . . . . . . . . . 98
Set up the API to send performance data to the dsmEndQuery . . . . . . . . . . . . . 99
client performance monitor . . . . . . . . . 36 dsmEndSendObj. . . . . . . . . . . . . 99
Configuring client performance monitor options 37 dsmEndSendObjEx . . . . . . . . . . . 100
Sending objects to the server . . . . . . . . 39 dsmEndTxn . . . . . . . . . . . . . . 100
Understanding backup and archive objects . . . 39 dsmEndTxnEx . . . . . . . . . . . . . 102
Compression . . . . . . . . . . . . . 40 dsmGetData . . . . . . . . . . . . . . 103
Publications
The IBM Spectrum Protect product family includes IBM Spectrum Protect
Snapshot, IBM Spectrum Protect for Space Management, IBM Spectrum Protect for
Databases, and several other storage management products from IBM®.
Example Description
autoexec.ncf A series of lowercase letters with an extension indicates program file
hsmgui.exe names.
DSMI_DIR A series of uppercase letters indicates return codes and other values.
dsmQuerySessInfo Boldface type indicates a command that you type on a command line,
the name of a function call, the name of a structure, a field within a
structure, or a parameter.
timeformat Boldface italic type indicates a backup-archive client option. The bold
type is used to introduce the option, or used in an example.
For a list of new features and updates in this release, see API updates.
The API includes function calls that you can use in an application to perform the
following operations:
v Start or end a session
v Assign management classes to objects before they are stored on a server
v Back up or archive objects to a server
v Restore or retrieve objects from a server
v Query the server for information about stored objects
v Manage file spaces
v Send retention events
When you, as an application developer, install the API, you receive the files that an
end user of an application needs:
v The API shared library.
v The messages file.
v The sample client options files.
v The source code for the API header files that your application needs.
v The source code for a sample application, and the makefile to build it.
For 64-bit applications, all compiles should be performed using compiler options
that enable 64-bit support. For example, '-q64' should be used when building API
applications on AIX®, and '-m64' should be used on Linux. See the sample make
files for more information.
Important: When you install the API, ensure that all files are at the same level.
For information about installing the API, see Installing the IBM Spectrum Protect
backup-archive clients.
References to UNIX and Linux include AIX, HP-UX, Linux, Mac OS X, and Oracle
Solaris operating systems.
You define options in one or two files when you install the API on your
workstation.
On UNIX and Linux operating systems, the options reside in two options files:
v dsm.opt - the client options file
v dsm.sys - the client system options file
Restriction: The API does not support the following backup-archive client options:
v autofsrename
v changingretries
v domain
v eventlogging
v groups
v subdir
v users
v virtualmountpoint
You also can specify options on the dsmInitEx function call. Use the option string
parameter or the API configuration file parameter.
The same option can derive from more than one configuration source. When this
happens, the source with the highest priority takes precedence. Table 1 lists the
priority sequence.
Table 1. Configuration sources in order of decreasing priority
Priority UNIX and Linux Windows Description
1 dsm.sys file not applicable This file contains options that a system administrator
sets only for UNIX and Linux.
(client system Tip: If your dsm.sys file contains server stanzas, ensure
options) that the passwordaccess option specifies the same value
(either prompt or generate) in each of the stanzas.
2 Option string Option string
One of these options takes effect when it is passed as a
(client options) (all options) parameter to a dsmInitEx call. The list can contain client
options such as compressalways, servername (UNIX and
Linux only), or tcpserveraddr (non-UNIX).
Related concepts:
Processing options
To help you get started, review the procedure to build the sample dapismp sample
application by your platform:
v For UNIX or Linux applications, see “UNIX or Linux sample application source
files.”
v For Windows applications, see “Windows 64-bit sample application” on page 7.
The dapismp sample application creates its own data streams when backing up or
archiving objects. It does not read or write objects to the local disk file system. The
object name does not correspond to any file on your workstation. The “seed
string” that you issue generates a pattern that can be verified when the object is
restored or retrieved. Once you compile the sample application and run dapismp to
start it, follow the instructions that display on your screen.
The files that are listed in Table 3 include the source files and other files that you
need to build the sample application that is included with the API package.
Table 3. Files that you need to build the UNIX or Linux API sample application
File names Description
README_api_enu README file
dsmrc.h Return codes header file
dsmapitd.h Common type definitions header file
dsmapips.h Operating system-specific type definitions header file
dsmapifp.h Function prototype header file
release.h Release values header file
You must install the following compilers to build the UNIX or Linux API sample
application:
v IBM AIX - IBM Visual Age compiler Version 6 or later
v HP-IA64 - aCC compiler A.05.50 or later
v Linux - GCC compiler Version 3.3.3 or later
v Mac OS X - GCC compiler Version 4.0 or later
v Oracle Solaris - Oracle Studio C++ compiler Version 11 or later
1. To build the API samples, run the following command:
gmake -f makesmp[64].xxx
Requirement: Always prefix the file space, high-level, and low-level names
with the correct path delimiter (/) when you enter the name, for example:
/myfilespace. You must use this prefix even when you specify the asterisk (*)
wildcard character.
Related concepts:
Environment variables (UNIX and Linux systems)
Restrictions:
v For best results, use dynamic loading. For an example, see the file dynaload.c
and the implementation in the sample code.
v Files for the sample application are in the following directories:
api64\obj
Contains the API sample program object files.
api64\samprun
Contains the sample program dapismp. The sample program contains the
execution directory.
v The DLL tsmapi64.dll is a 64-bit DLL.
v Use the Microsoft C/C++ Compiler Version 15 and the makefile makesmp64.mak
to compile the API sample application dapismp. You might have to adjust the
makefiles to fit your environment, specifically the library or the include
directories.
v After you compile the application, run the sample application by issuing the
command dapismp from the api64\samprun directory.
v Choose from the list of options displayed that are displayed. Ensure that you
run the sign-on action before you run any other actions.
v Always prefix the file space, high-level, and low-level names with the correct
path delimiter (\) when you enter the name, for example: \myfilespace. You
must use this prefix even when you specify the asterisk (*) wildcard character.
For Windows operating systems, the source files that you must have to build the
sample application are listed in Table 4 on page 8. The sample application is
included in the API package. For your convenience, a precompiled executable
(dapismp.exe) is also included.
When you design your application, review the considerations in Table 5. Start
structures with memset fields might change in subsequent releases. The stVersion
value increments with each product enhancement.
Table 5. API Considerations for designing an application
Design item Considerations
Setting locale The application must set the locale before the API is called. To set the locale to the default
value, add the following code to the application:
setlocale(LC_ALL,"");
To set the locale to another value, use the same call with the proper locale in the second
parameter. Check for specifics in the documentation for each operating system that you are
using.
By setting AIXTHREAD_SCOPE to S, user threads that are created with default attributes are
placed into system-wide contention scope. If a user thread is created with system-wide
contention scope, the user thread is bound to a kernel thread and is scheduled by the
kernel. The underlying kernel thread is not shared with any other user thread. For more
information about this environment variable, see the following topic:
“Using multithreading” on page 14
v Ensure that only one thread in a session calls any API function at any time. Applications
that use multiple threads with the same session handle must synchronize the API calls.
For example, use a mutex to synchronize API calls:
getTSMMutex()
issue TSM API call
releaseTSMMutex()
Use this approach only when the threads share a handle. You can use parallel calls to API
functions if the calls have different session handles.
v Implement a threaded consumer/producer model for data movement. API calls are
synchronous and the calls for dsmGetData function and dsmSendData function block until
they are finished. By using a consumer/producer model, the application can read the next
buffer during waiting periods for the network. Also, decoupling the data read/write and
the network increases performance when there is a network bottleneck or delays. In
general, the following holds:
Data thread <---> shared queue of buffers <---> communication
thread (issue calls to the IBM Spectrum Protect API)
v Use the same session for multiple operations to avoid incurring an overhead. For
applications that deal with many small objects, implement session-pooling so that the
same session can be used across multiple small operations. An overhead is associated with
opening and closing a session to the IBM Spectrum Protect server. The dsmInit/dsmInitEX
call is serialized so even in a multithreaded application only one thread can sign on at any
time. Also, during sign-on the API sends a number of one-time queries to the server so
that the server can do all operations. These queries include policy, option, file spaces, and
local configuration.
During a restore, pay special attention to the restore order. After the query, sort on this value
before the restore. If you are using multiple types of serial media, then access the different
types of media in separate sessions. For more information, see the following topic:
The following fields are examples of data structures that have size limits:
v Application type
v Archive description
v Copy group destination
v Copy group name
v File space information
v Management class name
v Object owner name
v Password
These limits are defined as constants within the header file dsmapitd.h. Any
storage allocation is based on these constants rather than on numbers that you
enter. For more information, see Appendix B, “API type definitions source files,”
on page 153.
The dsmQueryApiVersionEx should be the first API call that you enter when you
use the API. This call performs the following tasks:
v Confirms that the API library is installed and available on the end user's system
v Returns the version level of the API library that the application accesses
Determining the release of the API library is very important because some releases
might have different memory requirements and data structure definitions.
Downward compatibility is unlikely. See Table 6 for information about your
platform.
Table 6. Platform compatibility information
Platform Description
| Windows The message files must be at the same level as the library (DLL).
| UNIX or The API library and the message files must be at the same level.
| Linux
The dsmQueryApiVersionEx call returns the version of the API library that is
installed on the end user workstation. You can then compare the returned value
with the version of the API that the application client is using.
The API version number of the application client is entered in the compiled object
code as a set of four constants defined in dsmapitd.h:
The API version of the application client should be less than, or equal to, the API
library that is installed on the user's system. Be careful about any other condition.
You can enter the dsmQueryApiVersionEx call at any time, whether the API session
has been started or not.
Data structures that the API uses also have version control information in them.
Structures have version information as the first field. As enhancements are made to
structures, the version number is increased. When initializing the version field, use
the defined structure Version value in dsmapitd.h.
typedef struct
{
dsUint16_t stVersion; /* Structure version */
dsUint16_t version; /* API version */
dsUint16_t release; /* API release */
dsUint16_t level; /* API level */
dsUint16_t subLevel; /* API sub level */
} dsmApiVersionEx;
dsmApiVersionEx apiLibVer;
memset(&apiLibVer,0x00,sizeof(dsmApiVersionEx));
dsmQueryApiVersionEx(&apiLibVer);
Tip: When you run applications that assume a multithreaded API, use the
dsmQueryAPIVersionEx call.
Restriction: The default for the API is single-thread mode. If an application does
not call dsmSetUp with the mtflag value set to DSM_MULTITHREAD, the API
permits only one session for each process.
Once dsmSetUp successfully completes, the application can begin multiple threads
and enter multiple dsmInitEx calls. Each dsmInitEx call returns a handle for that
session. Any subsequent calls on that thread for that session must use that handle
value. Certain values are process-wide, environmental variables (values that are set
on dsmSetUp). Each dsmInitEx call parses options again. Each thread can run with
different options by specifying an overwrite file or an options string on the
dsmInitEx call. This enables different threads to go to different servers, or use
different node names.
Recommendation: On HP, set the thread stack to 64K or greater. The default value
of the thread stack (32K) might not be sufficient
The application requires signal handlers, such as SIGPIPE and SIGUSR1, for signals
that cause the application to end. The application then receives the return code
from the API. For example, to ignore SIGPIPE add the following instruction in
your application: signal(SIGPIPE, SIG_IGN). After this information is added,
instead of the application exiting on a broken pipe, the proper return code is
returned.
The dsmQueryCliOptions function can be called only before the dsmInitExcall. The
function returns the values of important options, such as option files, compression
settings, and communication parameters. The dsmInitEx call sets up a session with
the server as indicated in the parameters that are passed in the call or defined in
the options files.
The client node name, the owner name, and the password parameters are passed
to the dsmInitEx call. The owner name is case-sensitive, but the node name and
password are not. The application client nodes must be registered with the server
before a session starts.
Each time an API application client starts a session with the server, the client
application type is registered with the server. Always specify an operating system
abbreviation for the application type value because this value is entered in the
platform field on the server. The maximum string length is
DSM_MAX_PLATFORM_LENGTH.
The dsmInitEx function call establishes the IBM Spectrum Protect session with the
API configuration file and option list of the application client. The application
client can use the API configuration file and option list to set a number of IBM
Spectrum Protect options. These values override the values that are set in the user
configuration files during installation. Users cannot change the options that the
administrator defines. If the application client does not have a specific
configuration file and option list, you can set both of these parameters to NULL.
For more information about configuration files, see the following topic:
The dsmInitEx function call establishes the IBM Spectrum Protect session, by using
parameters that permit extended verification.
Check the dsmInitEx function call and the dsmInitExOut information return code.
The administrator canceled the last session if the return code is okay (RC=ok) and
the information return code (infoRC) is DSM_RC_REJECT_LASTSESS_CANCELED.
To end the current session immediately, call dsmTerminate.
End sessions with a dsmTerminate call. Any connection with the server is closed
and all resources that are associated with this session are freed.
For an example of starting and ending a session, see the following topic:
The example defines a number of global and local variables that are used in calls
to dsmInitEx and dsmTerminate. The dsmInitEx call takes a pointer to dsmHandle as
a parameter, while the dsmTerminate call takes the dsmHandle as a parameter. The
example in Figure 3 on page 18 displays the details of rcApiOut. The function
rcApiOut calls the API function dsmRCMsg, which translates a return code into a
message. The rcApiOut call then prints the message for the user. A version of
rcApiOut is included in the API sample application. The dsmApiVersion function is
a type definition that is found in the header file dsmapitd.h.
Session security
The IBM Spectrum Protect session-based system has security components that
permit applications to start sessions in a secure manner. These security measures
prohibit unauthorized access to the server and help to insure system integrity.
Every session that is started with the server must complete a sign-on process,
requires a password. When the password is coupled with the node name of the
client, it insures proper authorization when connecting to the server. The
application client provides this password to the API to start the session.
Passwords have expiration times associated with them. If a dsmInitEx call fails
with a password-expired return code (DSM_RC_REJECT_VERIFIER_EXPIRED), the
application client must enter the dsmChangePW call using the handle that is returned
by dsmInitEx. This updates the password before the session can be established
successfully. The example in Figure 4 on page 19 demonstrates the procedure to
change a password by using dsmChangePW. The login owner must use a root user ID
or an authorized user ID to change the password.
Tips:
1. If two different physical machines have the same IBM Spectrum Protect node
name or multiple paths are defined on one node using several server stanzas,
passwordaccess=generate might only work for the stanza which is used first
after password expiration. During the first client-server contact, the user is
prompted for the same password for each server stanza separately, and for each
stanza, a copy of the password is stored separately. When the password
expires, a new password is generated for the stanza which connects the first
client-server contact. All subsequent attempts to connect via other server
stanzas fail, because there is no logical link between their respective copies of
the old password, and the updated copy generated by the stanza used first
after password expiration. In this case, you must update the passwords prior to
expiration or after expiration as a recovery from the situation, as follows:
a. Run dsmadmc and update the password on the server.
An application can restrict user access by other means, such as setting access
filters.
These values override the IP connection information, but the session still uses the
same dsm.sys stanza node and password information.
printf("Doing signon for node %s, owner %s, with password %s\n", node,owner,pw);
initIn.stVersion = dsmInitExInVersion;
initIn.dsmApiVersionP = &apiApplVer
initIn.clientNodeNameP = node;
initIn.clientOwnerNameP = owner ;
initIn.clientPasswordP = pw;
initIn.applicationTypeP = "Sample-API AIX";
initIn.configfile = confFile;
initIn.options = options;
initIn.userNameP = userName;
initIn.userPasswordP = userNamePswd;
rc = dsmInitEx(&dsmHandle, &initIn, &initOut);
if (rc == DSM_RC_REJECT_VERIFIER_EXPIRED)
{
printf("*** Password expired. Select Change Password.\n");
return(rc);
}
else if (rc)
{
printf("*** Init failed: ");
rcApiOut(dsmHandle, rc); /* Call function to print error message */
dsmTerminate(dsmHandle); /* clean up memory blocks */
return(rc);
}
rc = dsmChangePW(dsmHandle,current_pw,new_pw1);
if (rc)
{
printf("*** Password change failed. Rc =
}
else
{
printf("*** Your new password has been accepted and updated.\n");
}
return 0;
Complete the following steps when you set the passwordaccess to generate:
1. Write the application with a call to dsmSetUp which passes argv[0]. The argv[0]
contains the name of the application that calls the API. The application is
permitted to run an authorized user; however, the administrator must decide
on the login name for the authorized user.
2. Set the effective user ID bit (S bit) for the application executable to On. The
owner of the application executable file can then become an authorized user
and can create a password file, update passwords, and run applications. The
owner of the application executable file must be the same as the user ID that
runs the program. In the following example, User is user1, the name of the
application executable file is applA, and user1 has read/write permissions on
the /home/user1 directory. The applA executable file has the following
permissions:
-rwsr-xr-x user1 group1 applA
3. Instruct the users of the application to use the authorized user name to log in.
IBM Spectrum Protect verifies that the login ID matches the application
executable owner before it permits access to the protected password file.
4. Set the passworddir option in the dsm.sys file to point to a directory where this
user has read/write access. For example, enter the following line in the server
stanza of the dsm.sys file:
passworddir /home/user1
5. Create the password file and ensure that the authorized user owns the file.
6. Log on as user1 and run app1A.
7. Call dsmSetUp and pass in argv.
To receive client owner authority, complete the following steps on the server:
1. Define the administrative user:
REGister Admin admin_name password
Where:
v admin_name is the administrative user name.
v password is the admin password.
2. Define the authority level. Users with system or policy authority also have
client owner authority.
Grant Authority admin_name classes authority node
Where:
v admin_name is the administrative user.
v classes is the node.
v authority has one of the following levels of authority:
– owner: full backup and restore authority for the node
– node: single node
– domain: group of nodes
3. Define access to a single node.
Register Node node_name password userid=user_id
Where:
v node_name is the client user node
v password is the client user node password
v user_id is the administrative user name
When the application uses the administrative user, the dsmInitEx function is called
with the userName and userNamePswd parameters.
dsmInitEx
clientNodeName = NULL
clientOwnerName = NULL
clientPassword = NULL
userName = ’administrative user’ name
userNamePswd = ’administrative user’ password
You can set the passwordaccess option to generate or prompt. With either
parameter, the userNamePswd value starts the session. When the session starts, any
backup or restore process can occur for that node.
To meet this requirement IBM Spectrum Protect has two main storage areas,
database and data storage.
v The database contains all metadata, such as the name or attributes associated
with objects.
v The data storage contains the object data. The data storage is actually a storage
hierarchy that the system administrator defines. Data are efficiently stored and
managed on either online or offline media, depending on cost and access needs.
Each object that is stored on the server has a name associated with it. The client
controls the following key components of that name:
v File space name
v High-level name
v Low-level name
v Object type
When making decisions about naming objects for an application, you might need
to use an external name for the full object names to the end user. Specifically, the
end user might need to specify the object in an Include or Exclude statement when
the application is run. The exact syntax of the object name in these statements is
platform-dependent. On the Windows operating system, the drive letter associated
with the file space rather than the file space name itself is used in the Include or
Exclude statement.
The object ID value that was assigned when you created the object might not be
the same as when you perform a restore process. Applications should save the
object name and then query to obtain the current object ID before doing a restore.
IBM Spectrum Protect uses the file space to identify the file system or disk drive
on which the data are located. In this way, actions can be performed on all entities
within a file space, such as querying all objects within a specified file space.
Because the file space is such an important component of the IBM Spectrum
Protect naming convention, you use special calls to register, update, query, and
delete file spaces.
The server also has administrative commands to query the file spaces on any node
in IBM Spectrum Protect storage, and delete them if necessary. All data stored by
the application client must have a file space name associated with it. Select the
name carefully to group similar data together in the system.
Note: On Windows platforms, a drive letter is associated with a file space. When
you register or update a file space, you must supply the drive letter. Because the
include-exclude list refers to the drive letter, you must keep track of each letter and
its associated file space. In the sample program dapismp, the drive letter is set to
"G" by default.
See Chapter 2, “Building and running the sample API application,” on page 5 for
more information on the sample programs.
When the file space name, high-level name, and low-level name are concatenated,
they must form a syntactically correct name on the operating system on which the
client runs. It is not necessary for the name to exist as an object on the system or
resemble the actual data on the local file system. However, the name must meet
the standard naming rules to be properly processed by the dsmBindMC calls. See
“Understanding backup and archive objects” on page 39 for naming considerations
that are related to policy management.
Object type
The object type identifies the object as either a file or a directory. A file is an object
that contains both attributes and binary data, and a directory is an object that
contains only attributes.
Table 7 shows what the application client would code is for object names by
platform.
Table 7. Application object name examples by platform
Platform Client code for object name
UNIX or Linux /myfs/highlev/lowlev
Windows "myvol\\highlev\\lowlev"
Note: On a Windows platform, a double backslash translates into a
single backslash, because a backslash is the escape character. File space
names start with a slash on the UNIX or Linux platform, but do not
start with a slash on the Windows platform.
The session owner is set during the call to dsmInitEx in the clientOwnerNameP
parameter. If you start a session with dsmInitEx owner name of NULL and you use
passwordaccess=prompt, that session owner is handled with session (root or
authorized user) authority. This is also true if you log in with a root user ID or an
authorized user ID and you use passwordaccess= generate. During a session
started in this manner, you can perform any action on any object that is owned by
this node regardless of the actual owner of that object.
If a session is started with a specific owner name, the session can only perform
actions on objects that have that object owner name associated with them. Backups
or archives into the system all must have this owner name associated with them.
Any queries performed return only the values that have this owner name
associated with them. The object owner value is set during the dsmSendObj call in
the Owner field of the ObjAttr structure. An owner name is case-sensitive. Table 8
summarizes the conditions under which a user has access to an object.
Table 8. Summary of user access to objects
Session owner Object owner User access
NULL (root, system owner) “ ” (empty string) Yes
NULL Specific name Yes
Specific name “ ” (empty string) No
Specific name Same name Yes
Specific name Different name No
For example, User A on node A uses the dsmSetAccess function call to give access
to its backups under the /db file space to User B from Node B. The access rule is
displayed as:
These options are set for this session. Any queries access the file spaces, and files
of Node A. Backups and archives are not permitted. Only query, restore, and
retrieve processes are permitted from the file spaces for which User B has access. If
the application tries to execute any operation using a dsmBeginTxn (for examples,
backup or update) while signed in with a -fromnode or -fromowner option set, then
Tip: On UNIX and Linux you can specify –fromowner=root in the option string
that is passed on the dsmInitEx function call. This permits non-root users access to
files that the root owns if a set access was performed.
Use the asnodename option on the dsmInitEx option string with the appropriate
function to back up, archive, restore, retrieve, query or delete data under the target
node name on the IBM Spectrum Protect server. See “Backing up multiple nodes
with client node proxy support” on page 78 for information on enabling this
option.
Use the dsmRegisterFS call to accomplish this task. For more information about
object names and IDs, see “Object names and IDs” on page 21.
The file space identifier is the top-level qualifier in a three-part name hierarchy.
Grouping related data together within a file space makes management of that data
much easier. For example, either the application client or the IBM Spectrum Protect
server administrator can delete a file space and all the objects within that file
space.
File spaces also permit the application client to provide information about the file
space to the server that the administrator can then query. This information is
returned on the query in the qryRespFSData structure and includes the following
file system information:
Type Definition
fstype The file space type. This field is a character string that the
application client sets.
fsAttr[platform].fsInfo A client information field that is used for client-specific data.
capacity The total amount of space in the file space.
occupancy The amount of space that is currently occupied in the file space.
backStartDate The time stamp when the latest backup started (set by sending a
dsmUpdateFS call).
backCompleteDate The time stamp when the latest backup completed (set by
sending a dsmUpdateFS call).
Using capacity and occupancy depends on the application client. Some applications
might not need information about the size of the file space, in which case these
fields can default to 0. For more information about querying file spaces, see
“Querying the IBM Spectrum Protect system” on page 31.
After a file space is registered with the system, you can back up or archive objects
at any time. To update the occupancy and the capacity fields of the file space after
If you want to monitor your last backup dates, enter a dsmUpdateFS call before you
start the backup. Set the update action to DSM_FSUPD_BACKSTARTDATE. This
forces the server to set the backStartDate field of the file space to the current time.
After the backup is complete for that file space, enter a dsmUpdateFS call with the
update action that is set to DSM_FSUPD_BACKCOMPLETEDATE. This call creates
a time stamp on the end of the backup.
If a file space is no longer needed, you can delete it with the dsmDeleteFS
command. On a UNIX or Linux operating system, only the root user or authorized
users can delete file spaces.
The examples in Figure 5 demonstrate how to use the three file space calls for
UNIX or Linux. For an example of how to use the three file space calls for
Windows, see the sample program code that is installed on your system.
dsInt16 rc;
regFSData fsData;
char fsName[DSM_MAX_FSNAME_LENGTH];
char smpAPI[] = "Sample-API";
strcpy(fsName,"/home/tallan/text");
memset(&fsData,0x00,sizeof(fsData));
fsData.stVersion = regFSDataVersion;
fsData.fsName = fsName;
fsData.fsType = smpAPI;
strcpy(fsData.fsAttr.unixFSAttr.fsInfo,"Sample API FS Info");
fsData.fsAttr.unixFSAttr.fsInfoLength =
strlen(fsData.fsAttr.unixFSAttr.fsInfo) + 1;
fsData.occupancy.hi=0;
fsData.occupancy.lo=100;
fsData.capacity.hi=0;
fsData.capacity.lo=300;
rc = dsmRegisterFS(dsmHandle,fsData);
if (rc == DSM_RC_FS_ALREADY_REGED) rc = DSM_RC_OK; /* already done */
if (rc)
{
printf("Filespace registration failed: ");
rcApiOut(dsmHandle, rc);
free(bkup_buff);
return (RC_SESSION_FAILED);
}
updFilespace.stVersion = dsmFSUpdVersion;
updFilespace.fsType = 0; /* no change */
updFilespace.occupancy.hi = 0;
updFilespace.occupancy.lo = 50;
updFilespace.capacity.hi = 0;
updFilespace.capacity.lo = 200;
strcpy(updFilespace.fsAttr.unixFSAttr.fsInfo,
"My update for filespace") ;
updFilespace.fsAttr.unixFSAttr.fsInfoLength =
strlen(updFilespace.fsAttr.unixFSAttr.fsInfo);
updAction = DSM_FSUPD_FSINFO |
DSM_FSUPD_OCCUPANCY |
DSM_FSUPD_CAPACITY;
rc = dsmUpdateFS (handle,fsName,&updFilespace,updAction);
printf("dsmUpdateFS rc=%d\n", rc);
Management classes consist of both backup copy groups and archive copy groups.
A copy group is a set of attributes that define the management policies for an
object that is being backed up or archived. If a backup operation is being
performed, the attributes in the backup copy group apply. If an archive operation
is being performed, the attributes in the archive copy group apply.
The backup or archive copy group in a particular management class can be empty
or NULL. If an object is bound to the NULL backup copy group, that object cannot be
backed up. If an object is bound to the NULL archive copy group, the object cannot
be archived.
The API requires that dsmBindMC is called before you back up or archive an object.
The dsmBindMC call returns a mcBindKey structure that contains information on
management class and copy groups that are associated with the object. Check the
copy group destination before proceeding with a send. When you send multiple
objects in a single transaction, they must have the same copy group destination.
The dsmBindMC function call returns the following information:
Table 9. Information returned on the dsmBindMC call
Information Description
Management Class The name of the management class that was bound to the object. The application client can
send the dsmBeginQuery call to determine all attributes of this management class.
Backup Copy Group Informs you if a backup copy group exists for this management class. If a backup
operation is being performed and a backup copy group does not exist, this object cannot
be sent to storage. You receive an error code if you attempted to send it using the
dsmSendObj call.
Backup Copy This field identifies the storage pool to which the data is sent. If you are performing a
Destination multiple object backup transaction, all copy destinations within that transaction must be
the same. If an object has a different copy destination than previous objects in the
transaction, end the current transaction and begin a new transaction before you can send
the object. You receive an error code if you attempt to send objects to different copy
destinations within the same transaction.
Archive Copy Group Informs you if an archive copy group exists for this management class. If an archive
operation is being performed and an archive copy group does not exist, this object cannot
be sent to storage. You receive an error code if you attempted to send it using the
dsmSendObj call.
Archive Copy This field identifies the storage pool to which the data are sent. If you are performing a
Destination multiple object archive transaction, all copy destinations within that transaction must be
the same. If an object has a different copy destination than previous objects in the
transaction, end the current transaction and begin a new transaction before you send the
object. You receive an error code if you attempt to send objects to different copy
destinations within the same transaction.
You can also rebind backup copies to a different management class using the
dsmUpdateObj or dsmUpdateObjEx call with the DSM_BACKUPD_MC action.
Related reference:
You can only bind objects to management classes by using the dsmBindMC call. You
might want your applications to query the management class attributes and
display them to end users. See “Querying the IBM Spectrum Protect system” on
page 31 for more information.
dsUint16_t send_type;
dsUint32_t dsmHandle;
dsmObjName objName; /* structure containing the object name */
mcBindKey MCBindKey; /* management class information */
char *dest; /* save destination value */
switch (send_type)
{
case (Backup_Send) :
rc = dsmBindMC(dsmHandle,&objName,stBackup,&MCBindKey);
dest = MCBindKey.backup_copy_dest;
break;
case (Archive_Send) :
rc = dsmBindMC(dsmHandle,&objName,stArchive,&MCBindKey);
dest = MCBindKey.archive_copy_dest;
break;
default : ;
}
if (rc)
{
printf("*** dsmBindMC failed: ");
rcApiOut(dsmHandle, rc);
rc = (RC_SESSION_FAILED);
return;
}
Restriction: You can issue only one dsmRetentionEvent call per transaction.
6. Query the objects to confirm that the retention is activated. If retention is
initiated, the retentionInitiated field in the qryRespArchiveData structure has
a value of I.
All queries that use the dsmBeginQuery call follow these steps:
1. Send the dsmBeginQuery call with the appropriate query type:
v Backup
v Archive
v Active backed-up objects
v File space
v Management class
The dsmBeginQuery call informs the API of the data format that is returned from
the server. The appropriate fields can be placed in the data structures that are
passed by the dsmGetNextQObj calls. The begin query call also permits the
application client to set the scope of the query by properly specifying the
parameters on the begin query call.
Restriction: On UNIX or Linux systems, only the root user can query active
backed-up objects. This query type is known as "fast path".
2. Enter the dsmGetNextQObj call to obtain each record from the query. This call
passes a buffer that is large enough to hold the data that is returned from the
query. Each query type has a corresponding data structure for the data
returned. For example, a backup query type has an associated
qryRespBackupData structure that is populated when the dsmGetNextQObj call is
sent.
3. The dsmGetNextQObj call usually returns one of the following codes:
v DSM_RC_MORE_DATA: Send the dsmGetNextQObj call again.
v DSM_RC_FINISHED: There is no more data. Send the dsmEndQuery call.
4. Send the dsmEndQuery call. When all query data are retrieved or more query
data are not needed, enter the dsmEndQuery call to end the query process. The
API flushes any remaining data from the query stream and releases any
resources that were used for the query.
In Query
dsmGetNextQObj
Start
dsmBeginQuery
More No dsmEndQuery
objects?
Yes
dsmGetNextQObj
qRespMCData.stVersion = qryRespMCDetailDataVersion;
Server efficiency
Use these guidelines when you retrieve from, or send objects to, the IBM Spectrum
Protect server.
v When you retrieve objects from the IBM Spectrum Protect server, follow these
guidelines:
Tip: You can either back up or archive data. Perform all send operations within a
transaction.
Transactions can consist of either single object sends or multiple object sends. To
improve system performance by decreasing system overhead, send smaller objects
in a multiple object transaction. The application client determines whether single or
multiple transactions are appropriate.
Send all objects within a multiple object transaction to the same copy destination.
If you need to send an object to a different destination than the previous object,
end the current transaction and start a new one. Within the new transaction, you
can send the object to the new copy destination.
Note: Objects that do not contain any bit data ( sizeEstimate=0 ) are not checked
for copy destination consistency.
The application client must keep track of the objects sent within a transaction to
perform retry processing or error processing if the transaction ends prematurely.
Either the server or the client can stop a transaction at any time. The application
client must be prepared to handle sudden transaction ends that it did not start.
File aggregation
IBM Spectrum Protect servers use a function that is called file aggregation. With
file aggregation, all objects sent in a single transaction are stored together, which
saves space and improves performance. You can still query and restore the objects
separately.
To use this function, all of the objects in a transaction should have the same file
space name. If the file space name changes within a transaction, the server closes
the existing aggregated object and begins a new one.
You can use LAN-free operations on platforms that are supported by the storage
agent. Macintosh platform is excluded.
Simultaneous-write operations
You can configure IBM Spectrum Protect server storage pools to write
simultaneously to a primary storage pool and copy storage pool or pools during a
backup or archive. Use this configuration to create multiple copies of the object.
For more information about setting up simultaneous-write operations, see the IBM
Spectrum Protect server documentation.
Table 10 describes the actions that you can take to enhance the API performance.
Table 10. Backup-archive options and the API parameter that enhance performance
Backup-archive
client options Description
tcpbuffsize Specifies the size of the TCP buffer. The default value is 31 KB. To
enhance performance, set the value to 32 KB.
tcpnodelay Specifies whether to send small buffers to the server rather than
holding them. To enhance performance, set this option to yes for all
platforms. This option is valid for Windows and AIX only.
API parameter Description
DataBlk This parameter is used with the dsmSendData function call to
determine the application buffer size. For best results, set the
parameter as a multiple of the tcpbuffsize value that is specified
with the tcpbuffsize minus 4 bytes. For example, set a value of 28
for this parameter when the value of tcpbuffsize is set to 32 KB.
Each dsmSendData call is synchronous and does not return until the data
transferred to the API in the dataBlkPtr is flushed to the network. The API adds a
4-byte overhead to each transaction buffer that is placed on the network.
For example, when the transaction buffer size is 32 KB and the application DataBlk
buffer size is 31 KB, then each application DataBlk buffer fits in a communications
buffer and can be flushed immediately. However, if the application DataBlk buffer
is exactly 32 KB, and because the API is adding 4 bytes per transaction buffer, two
flushes are required; one of 32 KB and one of 4 bytes. Also, if you set the
tcpnodelay option to no, flushing the 4 bytes might take up to 200 milliseconds.
With performance monitoring enabled, you can display performance data that is
collected by the API by using the performance monitor; the performance monitor is
available in the Tivoli Storage Manager Administration Center. Starting with
version 7.1, the Administration Center component is no longer included in Tivoli
Storage Manager or IBM Spectrum Protect distributions. If you have an
Administration Center that was installed with a previous server release, you can
continue to use it to display performance data. If you do not already have an
Administration Center installed, you can download the previously-released version
from ftp://public.dhe.ibm.com/storage/tivoli-storage-management/maintenance/
admincenter/v6r3/. For information about using the performance monitor, see the
Tivoli Storage Manager Version 6.3 server documentation.
When you monitor performance on UNIX and Linux computers, set the open file
descriptor limit to at least 1024, by using the following command:
ulimit -n 1024
To configure the client performance monitor options, complete the following steps:
1. Open the client options file for each client that you are monitoring. Depending
on your configuration, the client options are in one of the following files:
v dsm.opt
v dsm.sys
2. Add the following options to the client options file:
PERFMONTCPSERVERADDRESS
PERFMONTCPPORT
PERFMONCOMMTIMEOUT
PERFMONTCPSERVERADDRESS
The PERFMONTCPSERVERADDRESS option specifies the host name or IP address
of the system where the client performance monitor is installed.
Supported clients
Options file
Syntax
►► PERFMONTCPServeraddress server ►◄
Parameters
server
The server host name or IP address of the system that has the client
performance monitor installed (this is the same server that runs the
Administration Center).
Examples
Options file:
PERFMONTCPSERVERADDRESS 131.222.10.5
Command line:
This option cannot be set using the command line.
Supported clients
Options file
Syntax
5129
►► PERFMONTCPPort ►◄
port
Parameters
port
The port that is monitored for client performance data. Port 5129 is the default
port.
Examples
Options file:
PERFMONTCPPPORT 5000
Command line:
This option cannot be set using the command line.
PERFMONCOMMTIMEOUT
Specifies the maximum time, in seconds, that the dsmTerminate call waits for
performance data to arrive after a session is ended.
Supported clients
Options file
Syntax
30
►► PERFMONCOMMtimeout ►◄
seconds
Parameters
seconds
The time to wait for remaining performance data to arrive, before ending the
session.
The size estimate attribute is an estimate of the total size of the data object to send
to the server. If the application does not know the exact object size, set the
sizeEstimate to a higher estimate. If the estimate is smaller than the actual size,
the IBM Spectrum Protect server uses extra resources to manage extra space
allocations.
Tips:
v Be as accurate as is possible when you make this size estimate. The server uses
this attribute for efficient space allocation and object placement within its storage
resources.
v If the estimate is smaller than the actual size, a server with caching does not
allocate extra space and stops the send.
You might encounter problems if the sizeEstimate is much too large. The server
might not have enough space for the estimated size but does have space for the
actual size; or the server might use slower devices.
You can back up or archive objects that are larger than two gigabytes in size. The
objects can be either compressed or uncompressed.
To start a send operation, call dsmSendObj. If you have more data than you can
send at one time, you can make repeated calls to dsmSendData to transfer the
remainder of the information. Call dsmEndSendObj to complete the send operation.
Any object backed up to the server that has the same name as an object that is
already stored on the server from that client is subject to version control. Objects
are considered to be in active or inactive states on the server. The latest copy of an
object on the server that has not been deactivated is in the active state. Any other
object with the same name, whether it is an older version or a deactivated copy, is
considered inactive. Management class constructs define different management
criteria. They are assigned to active and inactive objects on the server.
Table 11 on page 40 lists the copy group fields that apply to active and inactive
states:
If backup versions each have a unique name, such as using a time stamp in the
name, then versioning does not happen automatically: every object is active. Active
objects never expire, so an application would be responsible for deactivating these
with the dsmDeleteObj call. In this situation, the application would need the
deactivated objects to expire as soon as possible. The user would define a backup
copy group with VERDELETED=0 and RETONLY=0.
The archive component of the IBM Spectrum Protect system permits objects to be
stored on the server with retention or expiration period controls instead of version
control. Each object stored is unique, even though its name might be the same as
an object already archived. Archive objects have a description field associated with
the metadata that can be used during query to identify a specific object.
Every object on the IBM Spectrum Protect server is assigned a unique object ID.
The persistence of the original value is not guaranteed during the life of an object
(specifically, after an export or import). Therefore, an application should not query
and save the original object ID for use on later restores. Rather, an application
should save the object name and insert date. You can use this information during a
restore to query objects and verify the insert date. Then, the current object ID can
be used to restore the object.
Compression
Configuration options on a given node and the dsmSendObj objCompressed option,
determine whether IBM Spectrum Protect compresses the object during a send.
Also, objects with a sizeEstimate less than DSM_MIN_COMPRESS_SIZE are never
compressed.
The administrator can change compression thresholds on the server by using the
register node command (compression=yes, no, or client-determined). If this is
client-determined, then the compression behavior is determined by the
compression option value in the configuration sources.
Some types of data, such as data that is already compressed, might actually get
bigger when processed with the compression algorithm. When this happens, the
return code DSM_RC_COMPRESS_GREW is generated. If you realize that this
might happen, but you want the send operation to continue anyway, tell the end
users to specify the following option in their options file:
COMPRESSAlways Yes
Attention: If your application plans to use partial object restore or retrieve, you
cannot compress the data while sending it. To enforce this, set the dsmSendObj
ObjAttr.objCompressed to bTrue.
Compression type
The type of compression that the client uses is determined by the combination of
compression and client-side data deduplication that is used during backup or
archive processing.
The compression algorithm that is used by the client is reported by the API in a
new field in the qryRespArchiveData and qryRespBackupData structures:
dsChar_t compressAlg[20]; /* compression algorithm name */
Example
The following example shows the Compresssion Type field in the output of the
backup and archive queries from the 64-bit sample application dapismp:
Enter selection ==>1
Filespace:\fs1
Highlevel:\hl
Item 1: \fs1\hl\ll
Object type: File
Object state: Active
Insert date: 2016/2/3 10:57:41
Expiration date: 0/0/0 0:0:0
Owner:
Restore order: 0-0-0-0-0
Object id: 0-40967
Copy group: 1
Media class: Fixed
Mgmt class: DEFAULT
Object info is :IBM Spectrum Protect API Verify Data
Object info length is :73
Estimated size : 0 4000
Compression : YES
Compression Type: LZ4
Encryption : NO
Encryption Strength : NONE
Client Deduplicated : YES
The buffers for data movement are allocated by IBM Spectrum Protect and a
pointer is passed back to the application. The application places the data in the
provided buffer, and that buffer is passed through the communication layers to the
storage agent by using shared memory. The data is then moved to the tape device,
which eliminates copies of data. This function can be used with either backup or
archive operations.
Attention: When you use this method, pay extra attention to proper buffer
handling and sizes of buffers. The buffers are shared between the components and
any memory overwrite that is a result of a programming error results in severe
errors.
The dsmRequestBuffer function can be called multiple times, up to the value that is
specified by the numTsmBuffers option. An application can have two threads: a
producer thread that fills buffers with data; and a consumer thread that sends
those buffers to IBM Spectrum Protect with the dsmSendBufferData call. When a
dsmRequestBuffer call is issued and the numTsmBuffers is reached, the
dsmRequestBuffer call blocks until a buffer is released. The buffer release can
happen by either calling dsmSendBufferData, which sends and releases a buffer or
by calling dsmReleaseBuffer. For more information, see callbuff.c in the API
sample directory.
If at any point there is a failure in the send, the application must release all the
buffers that are held and terminate the session. For example:
If failure
for each data buffer held by application
call dsmReleaseBuffer
dsmTerminate
If an application calls dsmTerminate and a buffer is still held, the API does not exit.
The following code is returned: DSM_RC_CANNOT_EXIT_MUST_RELEASE_BUFFER. If the
application cannot release the buffer, the application must exit the process to force
a cleanup.
The maximum amount of data in a single buffer that is returned by the IBM
Spectrum Protect server is (256K bytes – header overhead). As a consequence, only
applications that deal with small buffer writes benefit from this data retrieval
mechanism. The application must give special attention to the number of bytes in
the buffer, depending on the object size, the network, and other boundary
conditions. In some situations, the use of buffer copy elimination can actually
perform worse than the normal restore. The API normally caches the data and
returns a fixed length to the application. The application can then control the
number of data writes back to the disk.
If you use buffer copy elimination, create a data-caching mechanism for buffers
that are less than the preferred write buffer size. For example, if an application
writes 64K data blocks to disk, the application must take these actions:
1. Call dsmGetBufferData.
2. Write out blocks of 64K.
3. On the final block, copy the remainder to a tempBuff, issue another
dsmGetBufferData call, and fill the tempBuff with the rest of the data.
4. Continue writing blocks of 64K:
Restriction: Because the API provides the buffer and the goal is to minimize
processor utilization, more processing of the data in the buffer is not permitted.
The application cannot use encryption and compression with buffer copy
elimination because both of these operations require data processing and copies.
Implement both the regular data movement path and the buffer copy elimination
to enable the user to switch between both paths, based on their needs. If the user
must compress or encrypt data, then use the existing mechanism. If there is a
processor constraint, then use the new mechanism. Both of these mechanisms are
complementary and do not completely replace each other.
API encryption
Two methods are available to encrypt data: application-managed encryption and
IBM Spectrum Protect client encryption.
Select and use only one of these methods to encrypt data. The methods are
mutually exclusive and if you encrypt data by using both methods, you will be
unable to restore or retrieve some data. For example, assume that an application
uses application-managed encryption to encrypt object A, and then uses IBM
Spectrum Protect client encryption to encrypt object B. During a restore operation,
if the application sets the option to use IBM Spectrum Protect client encryption and
it tries to restore both objects, only object B can be restored; object A cannot be
restored because it was encrypted by the application, not by the client.
Regardless of the encryption method that is used, the IBM Spectrum Protect must
enable password authentication. By default, the server uses SET AUTHENTICATION
ON.
Application-managed encryption
With application-managed encryption, the application provides the key password
to the API (using key DSM_ENCRYPT_USER) and it is the application's
responsibility to manage the key password.
Attention: If the encryption key is not saved, and you forgot the key, your data is
unrecoverable.
The application provides the key password in the dsmInitEx call and must provide
the proper key password at restore time.
Attention: If the key password is lost, there is no way to restore the data.
The same key password must be used for backup and restore (or archive and
retrieve) operations for the same object. This method does not have a dependency
on the IBM Spectrum Protect server level. To set up this method, the application
needs to follow these steps:
1. Set the bEncryptKeyEnabled variable to bTrue in the call to dsmInitEx, and set
the encryptionPasswordP variable to point to a string with the encrypt key
password.
2. Set the include.encrypt for the objects to encrypt. For example, to encrypt all
data, set:
include.encrypt /.../* (UNIX)
and
include.encrypt *\...\* (Windows)
To encrypt the object /FS1/DB2/FULL, set:
include.encrypt /FS1/DB2/FULL
3. Set ENCRYPTKEY=PROMPT|SAVE in the option string that is passed to the API in the
dsmInitEx call on Windows. This option can also be set in dsm.opt (Windows)
or dsm.sys (UNIX or Linux).
By default, the encryptkey option is set to prompt. This setting ensures that the key
does not get stored automatically. If encryptkey save is specified, the key is stored
by IBM Spectrum Protect on the local machine but then only one key can be valid
for all IBM Spectrum Protect operations with the same node name.
The following table lists the API encryption types, prerequisites, and the functions
that are available.
Note: It is advised that the server has authentication turned ON. If authentication is
turned OFF, the key is not encrypted, but the data is still encrypted. However, this
is not recommended.
Table 13 shows how both Authorized Users and non-Authorized Users can encrypt
or decrypt data during a backup or restore operation, depending on the value that
is specified for the passwordaccess option. The TSM.PWD file must exist to
perform the following authorized-user and non-authorized-user operations. The
authorized user creates the TSM.PWD file and sets the encryptkey option to save
and the passwordaccess option to generate.
Table 13. Encrypting or decrypting data with application managed key on UNIX or Linux
passwordaccess
Operation encryptkey option Result
option
Authorized generate save Data encrypted.
user backup
generate prompt Data encrypted if encryptionPasswordP
contains an encryption password.
prompt save Data encrypted if encryptionPasswordP
contains an encryption password.
prompt prompt Data encrypted if encryptionPasswordP
contains an encryption password.
Authorized generate save Data encrypted.
user restore
generate prompt Data encrypted if encryptionPasswordP
contains an encryption password.
prompt save Data encrypted if encryptionPasswordP
contains an encryption password.
prompt prompt Data encrypted if encryptionPasswordP
contains an encryption password.
Non- generate save Data encrypted.
authorized
generate prompt Data encrypted if encryptionPasswordP
user backup
contains an encryption password.
prompt save Data encrypted if encryptionPasswordP
contains an encryption password.
prompt prompt Data encrypted if encryptionPasswordP
contains an encryption password.
Non- generate save Data encrypted.
authorized
generate prompt Data encrypted if encryptionPasswordP
user restore
contains an encryption password.
prompt save data encrypted if encryptionPasswordP
contains an encryption password.
prompt prompt Data encrypted if encryptionPasswordP
contains an encryption password.
This is the simpler method to implement, where one random encryption key is
generated per session and it is stored on the IBM Spectrum Protect server with the
object in the server database. During restore, the stored key is used for decryption.
Using this method, the management of the key is the responsibility of IBM
Spectrum Protect, and the application does not have to deal with the key at all.
Because the key is stored in the server database, you must have a valid IBM
Spectrum Protect database for a restore operation of an encrypted object. When the
key is transmitted between the API and the server, it is also encrypted. The
transmission of the key is secure, and when the key is stored in the IBM Spectrum
Protect server database it is encrypted. The only time that the key is placed in the
clear with the export data stream is when a node's data are exported between
servers.
To enable IBM Spectrum Protect client encryption, complete the following steps:
1. Specify -ENABLECLIENTENCRYPTKEY=YES in the option string that is passed to the
API on the dsmInitEx call or set the option in the system option file dsm.opt
(Windows) or dsm.sys (UNIX or Linux).
2. Set the include.encrypt for the objects to encrypt. For example, to encrypt all
data, set:
include.encrypt /.../* (UNIX)
and
include.encrypt *\...\* (Windows)
To encrypt the object /FS1/DB2/FULL, set:
include.encrypt /FS1/DB2/FULL
Overview
Two types of data deduplication are available on IBM Spectrum Protect: client-side
data deduplication and server-side data deduplication.
Enhancements
With client-side data deduplication, you can:
v Exclude specific files on a client from data deduplication.
v Enable a data deduplication cache that reduces network traffic between the
client and the server. The cache contains extents that were sent to the server in
previous incremental backup operations. Instead of querying the server for the
existence of an extent, the client queries its cache.
Specify a size and location for a client cache. If an inconsistency between the
server and the local cache is detected, the local cache is removed and
repopulated.
Note: For applications that use the IBM Spectrum Protect API, the data
deduplication cache must not be used because of the potential for backup
failures caused by the cache being out of sync with the IBM Spectrum Protect
server. If multiple, concurrent backup-archive client sessions are configured,
there must be a separate cache configured for each session.
v Enable both client-side data deduplication and compression to reduce the
amount of data that is stored by the server. Each extent is compressed before it
is sent to the server. The trade-off is between storage savings and the processing
power that is required to compress client data. In general, if you compress and
deduplicate data on the client system, you are using approximately twice as
much processing power as data deduplication alone.
The server can work with deduplicated, compressed data. In addition,
backup-archive clients earlier than V6.2 can restore deduplicated, compressed
data.
Benefits
Client-side data deduplication has a possible disadvantage. The server does not
have whole copies of client files until you back up the primary storage pools that
contain client extents to a non-deduplicated copy storage pool. (Extents are parts of
a file that are created during the data-deduplication process.) During storage pool
backup to a non-deduplicated storage pool, client extents are reassembled into
contiguous files.
By default, primary sequential-access storage pools that are set up for data
deduplication must be backed up to non-deduplicated copy storage pools before
they can be reclaimed and before duplicate data can be removed. The default
ensures that the server has copies of whole files at all times, in either a primary
storage pool or a copy storage pool.
Important: For further data reduction, you can enable client-side data
deduplication and compression together. Each extent is compressed before it is sent
to the server. Compression saves space, but it increases the processing time on the
client workstation.
When the client is enabled for client-side data deduplication, and you perform a
backup or archive operation, the data is sent to the server as extents. The next time
a backup or archive operation is performed, the client and server identify which
data extents have already been backed up or archived, and send only the unique
extents of data to the server.
For client-side data deduplication, the server and API must be at version 6.2 or
later.
Before you use client-side data deduplication to back up or archive your files, the
system must meet the following requirements:
v The client must have the deduplication option enabled.
v The server must enable the client for client-side data deduplication with the
DEDUP=CLIENTORSERVER parameter on either the REGISTER NODE or UPDATE NODE
command.
v The storage pool destination for the data must be a data deduplication-enabled
storage pool. The data deduplication-enabled storage pool is file device type
only.
v Ensure that the files are bound to the correct management class.
v A file can be excluded from client-side data deduplication processing. By default,
all files are included.
v Files must be larger than 2 KB.
v The server can limit the maximum transaction size for data deduplication by
setting the CLIENTDEDUPTXNLIMIT option on the server. See the server
documentation information about this option.
If any of these requirements are not met, data is processed normally, with no
client-side data deduplication.
Requirements:
Restriction: When client side data deduplication is enabled, the API cannot
recover from a state where the server has run out of storage on the destination
pool, even if there is a next pool defined. A stop reason code of
DSM_RS_ABORT_DESTINATION_POOL_CHANGED is returned and the
operation fails. There are two ways to recover from this situation:
1. Ask the administrator to add more scratch volumes to the original filepool.
2. Retry the operation with data deduplication disabled.
For even greater bandwidth savings, you can enable a local cache for data
deduplication. The local cache saves queries from going to the IBM Spectrum
Protect server. The default value for ENABLEDEDUPCACHE is NO, so that the
cache is not out of sync with the server. If the cache is out of sync with the server,
the application resends all data. If your application can retry on a failed
transaction, and you want to use the local cache, set the ENABLEDEDUPCACHE
option to YES in the dsm.opt (Windows) or dsm.sys (UNIX) file.
At the end of a restore, if all of the data was restored through the API, and the
object was deduplicated by the client, an end-to-end digest is calculated and
compared to the value calculated at backup time. If those values do not match,
error DSM_RC_DIGEST_VALIDATION_ERROR is returned. If an application
receives this error, the data is corrupt. This error can also be a result of a transient
error on the network, so try the restore or retrieve again.
To refine the list of files to be included, the include.dedup option can be used in
combination with the exclude.dedup option.
include.dedup /FS1/archive/*
include.dedup E:\myfiles\archive\*
The IBM Spectrum Protect administrator can specify the data deduplication
location (client or server) to use with the DEDUP parameter on the REGISTER NODE or
UPDATE NODE server command.
In a data deduplication-enabled storage pool (file pool), only one instance of a data
extent is retained. Other instances of the same data extent are replaced with a
pointer to the retained instance.
For more information about server-side data deduplication, see the IBM Spectrum
Protect server documentation.
Application failover
When the IBM Spectrum Protect server becomes unavailable because of an outage,
applications that use the API can automatically fail over to a secondary server for
data recovery.
The IBM Spectrum Protect server that the client and API connects to during
normal production processes is called the primary server. When the primary server
is set up for node replication, that server is also known as the source replication
server. The client node data on the source replication server can be replicated to the
target replication server. This server is also known as the secondary server, and is the
server that the client automatically fails over to when the primary server fails.
The client and API must be configured for automated client failover, and must
connect to a version 7.1 (or later) server that replicates client node data. The
configuration for the API is the same as the configuration for the backup-archive
client.
You must back up the application at least one time to the primary server. The API
can fail over to the secondary server to recover data only if the data from the client
node was replicated from the primary server to the secondary server.
Related concepts:
Automated client failover configuration and use
The replication status indicates whether the most recent backup was replicated to
the secondary server. If the time stamp of the most recent backup operation on the
API matches the time stamp of the backup on the secondary server, the replication
status is current. If the two time stamps do not match, the replication status is not
current and the replicated data might be out-of-date.
See Appendix B, “API type definitions source files,” on page 153 for the structure
and type definitions of the API.
The DSM_RC_SIGNON_FAILOVER_MODE return code indicates that the client and API
failed over to the secondary server, and is running in failover mode.
************************************************************
After dsmInitEx:
Server TARGET ver/rel/lev 7/1/0/0
userNameAuthorities : Owner
Replication Server name : TARGET
Home Server name : MINE
Connected to replication server
************************************************************
The following sample output is an example of the query filespace command that
shows the replication status of a file space on the secondary server:
Related reference:
“dsmGetNextQObj” on page 105
For example, you cannot make a dsmSendObj call unless a transaction was started
and a dsmBindMC call was previously made for the object that you are backing up.
Figure 12 on page 57 displays the state diagram for performing backup or archive
operations within a transaction. The arrow pointing from “In Send Object” to
dsmEndTxn indicates that a dsmEndTxn call can be started after a call to dsmSendObj
or dsmSendData. You might want to do this if an error condition occurred during
the send of an object and you want to stop the entire operation. In this case, you
must use a vote of DSM_VOTE_ABORT. In normal circumstances, however, call
dsmEndSendObj before you end the transaction.
dsmBindMC * dsmDeleteObj
In Transaction
dsmSendObj dsmEndSendObj
dsmEndSendObjEx
In Send Object
dsmSendData
* May be inside or outside of a transaction
dsmBeginTxn
Yes BindMC
Done? Yes
No More No Idle
objects? State
dsmBindMC
Yes
No More No
Send objects
Object? dsmEndTxn
in txn?
Yes
dsmSendObj
More No
dsmEndSendObj
data?
Yes
dsmSendData
The primary feature in these two diagrams is the loop between the following API
calls from within a transaction:
v dsmBindMC
v dsmSendObj
v dsmSendData
v dsmEndSendObj
The dsmBindMC call is unique in that you can start it from inside or outside of a
transaction boundary. You can also start it from a different transaction, if required.
The only requirement for the dsmBindMC call is that it is made prior to backing up
or archiving an object. If the object that you are backing up or archiving is not
associated with a management class, an error code is returned from dsmSendObj. In
this situation, the transaction is ended by calling dsmEndTxn (this error condition is
not shown in the flowchart).
The dsmSendData call is called from inside a loop that repeatedly sends data until a
flag is set that permits the program execution to exit the loop. The entire send
operation is performed from within the transaction.
The third parameter on the dsmSendObj call is a buffer that contains the archive
description. Because backup objects do not have a description, this parameter is
NULL when backing up an object.
Figure 8 on page 28 displays an example that shows the use of the dsmBindMC
function call.
File grouping
The IBM Spectrum Protect API has a logical file grouping protocol that relates
several individual objects together. You can reference and manage these groups as
a logical group on the server. A logical group requires that all group members and
the group leader belong to the same node and file space on the server.
File groups contain backup data only, and cannot contain archive data. Archive
objects can use the Archive Description field to facilitate a type of grouping if
required by an application.
The out structure in dsmEndTxnEx includes a new field, groupLeaderObjId. This field
contains the object ID of the group leader if a group was opened in that
transaction. You can create a group across more than one transaction. A group is
not committed, or saved, on the server until a close is performed. The
dsmGroupHandler is an interface that can accept five different operations. They
include:
v DSM_GROUP_ACTION_OPEN
v DSM_GROUP_ACTION_CLOSE
v DSM_GROUP_ACTION_ADD
v DSM_GROUP_ACTION_ASSIGNTO
v DSM_GROUP_ACTION_REMOVE
The qtBackupGroups queries groups that are closed while qtOpenGroups queries
groups that are open. The query buffer for the new types has fields for
groupLeaderObjId and objType. The query performs differently depending on the
values for these two fields. The following table includes some query possibilities:
Table 16. Examples of queries
groupLeaderObjId.hi groupLeaderObjId.lo objType Result
0 0 NULL Returns a list of all group leaders
grpLdrObjId.hi grpLdrObjId.lo 0 Returns a list for all group members that are assigned
to the specified group leader (grpLdrObjId).
grpLdrObjId.hi grpLdrObjId.lo objType Returns a list by using BackQryRespEnhanced3, for each
group member that is assigned to the specified group
leader (grpLdrObjId), and matching the object type
(objType).
These fields are Boolean flags. The following example displays the creation of the
group, adding members to the group, and closing the group to commit the group
on the IBM Spectrum Protect server.
For a code example, see the sample group program dsmgrp.c that is included in
the API sampsrc directory.
Restriction: The API can only restore or retrieve objects that were backed up or
archived using API calls.
Both restore and retrieve functions start with a query operation. The query returns
different information depending on whether the data was originally backed up or
archived. For instance, a query on backup objects returns information on whether
an object is active or inactive, while a query on archive objects returns information
such as object descriptions. Both queries return object IDs that are used to uniquely
identify the object on the server.
Note: If you code your application to use a partial object restore or retrieve, you
cannot compress the data while sending it. To enforce this, set
ObjAttr.objCompressed to bTrue.
To perform a partial object restore or retrieve, associate the following two data
fields with each object GetList entry:
offset The byte offset into the object from which to begin returning data.
The following data fields, used on the dsmBeginGetData call, determine what
portion of the object is restored or retrieved:
v If both the offset and length are zero, the entire object is restored or retrieved
from IBM Spectrum Protect storage.
v If the offset is greater than zero, but the length is zero, the object is restored or
retrieved from the offset to the end.
v If the length is greater than zero, only the portion of the object from the offset
for the specified length is restored or retrieved.
To send the query, the application must enter the parameter lists and structures for
the dsmBeginQuery call. The structure must include the file space that the query
examines and pattern-match entries for the high-level and low-level name fields. If
the session was initialized with a NULL owner name, you do not need to specify
the owner field. However, if the session was initialized with an explicit owner
name, only objects that are associated with that owner name are returned.
A query returns all information that is stored with the object, in addition to the
information in the following table.
You must keep some or all of the query information for later processing. Keep the
copyId and restoreOrderExt fields because they are needed for the actual restore
operation. You must also keep any other information needed to open a data file or
identify a destination.
Then you sort the objects in ascending order (low to high). This sorting is very
important to the performance of the restore operation. Sorting the objects on the
restoreOrderExt fields ensures that the data is read from the server in the most
efficient order.
All data on disk is restored first, followed by data on media classes that require
volume mounts (such as tape). The restoreOrderExt field also ensures that data on
tape is read in order with processing starting at the front of a tape and progressing
towards the end.
Properly sorting on the restoreOrderExt field means that duplicate tape mounts
and unnecessary tape rewinds do not occur.
The following example shows how to sort objects by using Restore Order fields.
typedef struct {
dsStruct64_t objId;
dsUint160_t restoreOrderExt;
===================================================================
/*----------------------------------------+
| Make sure to check rc from dsmBeginQuery
+-----------------------------------------*/
while (!done)
{
rc = dsmGetNextQObj(dsmHandle, &qDataBlkArea);
if ((rc == DSM_RC_MORE_DATA) ||
(rc == DSM_RC_FINISHED))
&&( qDataBlkArea.numBytes))
{
/******************************************/
/* transferring restoreOrderExt and objId */
/******************************************/
sortorder[i].restoreOrderExt = qbDataArea.restoreOrderExt;
sortorder[i].objId = qbDataArea.objId;
i++;
qry_item++;
} /* while (!done) */
rc = dsmEndQuery(dsmHandle);
/*check rc */
/*****************************************************/
/* sorting the array using qsort. After the call, */
/* sortorder will be sorted by restoreOrderExt field */
/*****************************************************/
/*-----------------------------------------------------------------+
| NOTE: Make sure to extract sorted object ids and store them in
| any data structure you want.
------------------------------------------------------------------*/
/*----------------------------------------------------------------+
The DSM_RC_MORE_DATA return code means that a buffer was returned and
that you should call dsmGetData again. Check the DataBlk.numBytes for the actual
number of returned bytes.
When you obtain all data for an object, you must send a dsmEndGetObj call. If more
objects will be received, send dsmGetObj again.
If you want to stop the process, for example, to discard any remaining data in the
restore stream for all objects that are not yet received, send the dsmEndGetData call.
This call flushes the data from the server to the client. However, using this method
might take time to complete. If you want to end a restore operation, use
dsmTerminate to close the session.
1. Send the dsmGetObj call to identify the object that you requested from the data
stream and to obtain the first block of data that is associated with the object.
2. Send more dsmGetData calls, as necessary to obtain the remaining object data.
The arrow pointing from “In Get Object” to dsmEndGetData indicates that you can
send a dsmEndGetData call after a call to dsmGetObj or dsmGetData. You might need
to do this if an error condition occurred while getting an object from IBM
Spectrum Protect storage and you want to stop the operation. In normal
circumstances, however, call dsmEndGetObj first.
dsmBeginGetData dsmEndGetData
In Get Data
dsmGetObj dsmEndGetObj
In Get Object
dsmGetData
Figure 17. State diagram for restore and retrieve operations
Idle
Query server to determine State
objects to get
No
Sort desired objects
by restore order
Yes
Another
list?
dsmBeginGetData
dsmGetObj
Yes
No No
More dsmEndGetObj More
data? objects? dsmEndGetData
Yes
dsmGetData
For an archived object, the application can update the following fields:
v Description
v Object information
v Owner
For a backed-up object, the application can update the following fields:
v Management class
v Object information
v Owner
Use the dsmDeleteObj function call to delete archived objects and turn off backup
objects. Using this delType removes the backup object from the server. This is
based on objID, deletes an object from the server database. Only an owner of an
object can delete it. You can delete any version (active or inactive) of an object. The
server reconciles the versions. If you delete an active version of an object, the first
inactive version becomes active. If you delete an inactive version of an object, all
older versions advance. The node must be registered with backDel permission.
An archived object is marked for deletion in storage when the system performs its
next object expiration cycle. Once you delete an archived object from the server,
you cannot retrieve it.
When you inactivate a backup object at the server, the object moves from an active
state to an inactive state. These states have different retention policies associated
with them that are based on the management class that is assigned.
Similar to the dsmSendObj call, a call to dsmDeleteObj is sent within the boundary
of a transaction. The state diagram in Figure 12 on page 57 displays how a call to
dsmDeleteObj is preceded by a call to dsmBeginTxn and followed by a call to
dsmEndTxn.
Logging events
An API application can log event messages to central locations. The application can
direct logging to the IBM Spectrum Protect server, the local machine, or both. The
dsmLogEventEx function call is performed in a session. To view messages logged on
the server, use the query actlog command through the administrative client.
Use the IBM Spectrum Protect client option, errorlogretention, to prune the client
error log file if the application writes numerous client messages to the client log
dsmLogType, either logLocal or logBoth.
For more information about IBM Spectrum Protect logs, see the IBM Spectrum
Protect server documentation.
Figure 20 on page 73 contains the state diagram for the API. It contains all
previously displayed state diagrams in addition to several other calls previously
not displayed.
Note: If the dsmInitEx call returns with a password-expired return code, the
dsmChangePW call must be made before you start a valid session. See Figure 4 on
page 19 for an example that uses dsmChangePW.
v If a call returns with an error, the state remains as it was. For example, if
dsmGetObj returns with an error, the state remains In Get Data, and a call to
dsmEndGetObj is a call sequence error.
dsmQueryCliOptions (optional)
dsmQueryApiVersion
dsmInit
or dsmInitEx dsmTerminate
dsmReleaseBuffer
dsmRegisterFS dsmQuerySessOptions
dsmUpdateFS dsmBindMC
dsmDeleteFS dsmChangePW
In
Session
dsmSetAccess dsmQuerySessInfo
dsmLogEvent
dsmQueryAccess
dsmLogEventEx
dsmUpdateObj
dsmDeleteAccess
dsmUpdateObjEx
In
Send Object In Get Object
dsmSendData
dsmGetData
dsmRequestBuffer dsmReleaseBuffer
dsmSendBufferData dsmGetBufferData
Notes:
1. There is no interoperability between the backup-archive client and API objects
stored on a retention protection server.
2. You cannot use the backup-archive client GUIs to access files that were stored
using the API client. You can only use the command line to access these files.
For convenience, use the name of the object that is not prefixed with directory
information as the low-level qualifier. For more information, see “Object names
and IDs” on page 21.
File space names must be fully qualified when they are referred to from either the
API or the backup-archive command line. For example, on a UNIX or Linux
operating system, you register the following file spaces:
v /a
v /a/b
After you register both file spaces, if you back up object b into file space /a, then a
query for /a/b continues to display objects that are related only to file space /a/b.
The exception to this restriction occurs in file space references when you attempt to
query or delete file spaces with the API. In both cases, the file space names do not
have to be fully qualified if you use a wildcard character. For example, /a* refers
to both /a and /a/b.
Tip: If interoperability is important for you, then avoid file space names that
overlap.
On Windows systems, enclose file space names in braces { } for API objects when
you access the objects from the backup-archive command line interface. Windows
operating systems automatically place file space names in uppercase letters when
you register or refer the names. However, this automatic function does not occur
for the remainder of the object name specification. If you want full interoperability,
place the high-level qualifier and the low-level qualifier in uppercase letters in the
application when you back up API objects. If your application does not uppercase
high-level qualifiers (directory names) and low-level qualifiers (file names) before it
sends objects to the server, you will be unable to access the objects directly by
name through the backup-archive client.
If any other of the other qualifiers are also saved in lowercase text, those qualifiers
must also be queried by using wildcards. For example, to query an object that is
stored as {"FileSpaceName"}\TEST\mydirname\file.txt, use the following
command:
dsmc query backup {"FileSpaceName"}\TEST\*\*
The examples that follow demonstrate these concepts. In both Windows and UNIX
or Linux environments, you do not have to specify either the complete high-level
or low-level qualifier. However, if you do not specify the complete qualifier, then
you must use the wildcard character.
Platform Example
Windows To query all backed-up files in file space MYFS, enter the following string:
dsmc q ba "{MYFS}\*\*"
You must use at least one asterisk (*) for each of the high-level and
low-level qualifiers.
You must use at least one asterisk (*) for each of the high-level and
low-level qualifiers.
To view and manage objects that other users own either on the same node or on a
different node, perform these steps:
1. Give access with the set access command.
2. Specify the owner and the node. Use the fromowner and fromnode options from
the backup-archive command line to specify the owner and the node. For
example:
dsmc q ba "/A/*/*" -fromowner=other_owner -fromnode=other_node
Table 18 describes the commands that you can use with API objects.
Table 18. Backup-archive client commands you can use with API objects
Command Description
Delete Archived files that the current user owns can be deleted. The set access
Archive command settings have no effect on this command.
Delete The delete filespace command affects API objects.
Filespace
Query From the backup-archive command line, you can query backed up and
archived API objects and objects that other users own, or that exist on other
nodes. See “Naming your API objects” on page 75 for information about
querying API objects.
Use the existing –fromowner option to query objects that a different user
owns for which the set access permission has been given. Use the existing
–fromnode option to query objects that exist on another node for which the
set access permission has been given. For more information, see
“dsmInitEx” on page 113.
Restore Note: Use these commands only for exception situations. API objects that
are encrypted using the application managed key can be restored or
Retrieve retrieved if the encryption key is known or saved in the password file or
registry. API objects encrypted by using transparent encryption cannot be
restored or retrieved by using the backup-archive client.
These commands return data as bit files that are created by using default
file attributes. You can restore or retrieve API objects that other users own,
or that are from a different node. The set access command determines
which objects qualify.
Set Access The set access command permits users to manage API objects that another
user owns, or that are from another node.
By default, the names of objects from one UNIX system are compatible with the
names of objects from other UNIX systems. By default, names of objects from
Windows systems are not compatible with names of objects from UNIX systems.
Several parameters control the naming of objects in IBM Spectrum Protect file
spaces. If you set up an application appropriately, the names of objects can be used
by applications that run on both Windows systems and UNIX systems. Use the
same parameters to back up and restore objects.
Restriction: A Windows application that uses Unicode creates a file space that is
not compatible with applications that run on UNIX systems.
Use the asnodename option on the dsmInitEx option string to back up, archive,
restore, and retrieve, query, or delete data under the target node name on the IBM
Spectrum Protect server. You can also specify the asnodename option in the dsm.opt
or dsm.sys file.
Restriction: Do not use target nodes as traditional nodes, especially if you encrypt
your files before you back up to the server.
With Unicode, your application can back up and restore file names in any
character set from the same machine. For example, on an English machine, you can
back up and restore file names in any other language code page.
Use the IBM Spectrum Protect Unicode interface if any of the following conditions
are true:
v If your application is already compiled for Unicode and it was converting to a
multibyte character set (mbcs) before calling the IBM Spectrum Protect API.
v If you are writing a new application and want to enable your application to
support Unicode.
v If your application uses a string passed to it from an operating system or other
application that uses Unicode.
If you do not need Unicode, it is not necessary to compile your application again.
The API continues to support the dsm interface. The API SDK contains callmtu1.c
and callmtu2.c sample programs that demonstrate how to use the Unicode API.
Use makemtu to compile these programs.
Setting up Unicode
To set up and use Unicode you must perform a particular procedure so the API
registers a Unicode file space on the server and all file names in that file space
become Unicode strings.
Restriction: You cannot store Unicode and non-Unicode file names in the same file
space.
1. Compile the code with the -DUNICODE flag.
2. All strings in your application must be wchar strings.
3. Follow the structures in the tsmapitd.h file, and the function definitions in the
tsmapifp.h file for calls to the API.
4. Set the useUnicode flag to bTrue on the tsmInitEx function call. Any new file
space is registered as a Unicode file space.
When you send data to previously registered, non-Unicode file spaces, the API
continues to send file names as non-Unicode. Rename the old file spaces on the
server to fsname_old and start a new Unicode file space for new data. The API
Each dsmXXX function call has a matching tsmXXX function call. The difference
between the two are the structures that are used. All tsmXXX function call structures
have dsChar_t types for string values when they are compiled with the UNICODE
flag. The dsChar_r maps to wchar. There is no other difference between these
interfaces.
Restriction: Use either one interface or the other. Do not mix the dsmXXX function
call and tsmXXX function call interfaces. Ensure that you use the IBM Spectrum
Protect structures and IBM Spectrum Protect version definitions.
Some constants continue to be defined in the dsmapitd.h file, so you need both the
dsmapitd.h and the tsmapitd.h files when you compile.
You can use the IBM Spectrum Protect interface on other operating systems, such
as UNIX or Linux, but on these operating systems, the dsChar_t type maps to char
because Unicode is supported on only Windows operating systems. You can write
only one variation of the application and compile on more than one operating
system using the IBM Spectrum Protect interface. If you are writing a new
application, use the IBM Spectrum Protect interface.
Note: After you use a Unicode-enabled client to access a node, you cannot connect
to the same node name with an older version of the API or with an API from
another operating system. If your application uses cross-platform capability, do not
use the Unicode flag. There is no cross-platform support between Unicode and
non-Unicode operating systems.
When you enable the useUnicode flag, all string structures are treated as Unicode
strings. On the server, only the following fields are true Unicode:
v File space name
v High level
v Low level
v Archive description
All remaining fields convert to mbcs in the local code page before they are sent to
the server. Fields, such as nodename, are wchar strings. They must be valid in the
current locale. For example, on a Japanese machine, you can back up files with
Chinese names, but the node name must be a valid string in Japanese. The option
file remains in the current code page. If you need to create a Unicode
include-exclude list, use the inclexcl option with a file name and create a Unicode
file with Unicode patterns in it.
Related reference:
inclexcl option
Element Description
Purpose Describes the function call.
Syntax Contains the actual C code for the function call. This code is copied from the
UNIX or Linux version of the dsmapifp.h header file. See Appendix C, “API
function definitions source file,” on page 195.
Related reference:
API return codes
dsmBeginGetData
The dsmBeginGetData function call starts a restore or retrieve operation on a list of
objects in storage. This list of objects is contained in the dsmGetList structure. The
application creates this list with values from the query that preceded a call to
dsmBeginGetData.
The caller first must use the restore order fields that are obtained from the object
query to sort the list that is contained in this call. This ensures that the objects are
restored from storage in the most efficient way possible without rewinding or
remounting data tapes.
Follow the call to dsmBeginGetData with one or more calls to dsmGetObj to obtain
each object within the list. After each object is obtained, or additional data for the
object is not needed, the dsmEndGetObj call is sent.
When all objects are obtained, or the dsmEndGetObj is canceled, the dsmEndGetData
call is sent. You then can start the cycle again.
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsBool_t mountWait (I)
A Boolean true or false value indicates whether or not the application client
waits for offline media to be mounted if the data that is needed is currently
offline. If mountWait is true, the application waits for the server to mount the
required media. The application waits until the media is mounted or the
request is canceled.
dsmGetType getType (I)
An enumerated type consisting of gtBackup and gtArchive that indicates what
type of object to get.
dsmGetList *dsmGetObjListP (I)
The structure that contains information about the objects or partial objects to
restore or retrieve. The structure points to a list of object IDs and, in the case of
a partial object restore or retrieve, a list of associated offsets and lengths. If
your application uses the partial object restore or retrieve function, set the
dsmGetList.stVersion field to dsmGetListPORVersion. In a partial object restore
or retrieve, you cannot compress data while sending it. To enforce this, set
ObjAttr.objCompressed to bTrue.
See Figure 19 on page 69 and Appendix B, “API type definitions source files,”
on page 153 for more information on this structure.
See “Partial object restore or retrieve” on page 63 for more information on
partial object restore or retrieve.
Return codes
The query data that is returned from the call is obtained by one or more calls to
dsmGetNextQObj. When the query is complete, the dsmEndQuery call is sent.
Syntax
dsInt16_t dsmBeginQuery (dsUint32_t dsmHandle,
dsmQueryType queryType,
dsmQueryBuff *queryBuffer);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmQueryType queryType (I)
Identifies the type of query to run. Assign one of the following options:
qtArchive
Queries archived objects.
qtBackup
Queries backed-up objects.
qtBackupActive
Queries active, backed-up objects only for the entire file space name
that you pass. This query is called a “fast path” and is an efficient way
to query active objects from storage.
The call does not return DEF because that object as deleted
prior to the point-in-time value.
qryABackupData
objName
The complete object name. You can use a wildcard character,
such as an asterisk (*) or a question mark (?), in the high-level
or low-level portion of the name. An asterisk matches zero or
more characters, and a question mark matches one character.
The objType field of objName can have one of the following
values:
v DSM_OBJ_FILE
v DSM_OBJ_DIRECTORY
v DSM_OBJ_ANY_TYPE
Return codes
The following table describes the return codes for the dsmBeginQuery function call.
Table 21. Return codes for dsmBeginQuery
Return code Return code number Explanation
DSM_RC_NO_MEMORY 102 There is not enough memory to complete the
request.
DSM_RC_FILE_SPACE_NOT_FOUND 124 The specified file space was not found.
DSM_RC_NO_POLICY_BLK 2007 Server policy information was not available.
DSM_RC_INVALID_OBJTYPE 2010 Invalid object type.
DSM_RC_INVALID_OBJOWNER 2019 Invalid object owner name.
DSM_RC_INVALID_OBJSTATE 2024 Invalid object condition.
DSM_RC_WRONG_VERSION_PARM 2065 The API version of the application client is
different from the IBM Spectrum Protect library
version.
dsmBeginTxn
The dsmBeginTxn function call begins one or more IBM Spectrum Protect
transactions that begin a complete action; either all the actions succeed or none
succeed. An action can be either a single call or a series of calls. For example, a
dsmSendObj call that is followed by a number of dsmSendData calls can be
considered a single action. Similarly, a dsmSendObj call with a dataBlkPtr that
indicates a data area containing the object to back up is also considered a single
action.
Try to group more than one object together in a single transaction for data transfer
operations. Grouping objects results in significant performance improvements in
the IBM Spectrum Protect system. From both a client and a server perspective, a
certain amount of overhead is incurred by starting and ending each transaction.
There are limits to what you can perform within a single transaction. These
restrictions include:
v A maximum number of objects that you can send or delete in a single
transaction. This limit is located in the data that dsmQuerySessInfo returns in the
ApiSessInfo.maxObjPerTxn field. This corresponds to the TxnGroupMax server
option.
v All objects that are sent to the server (either backup or archive) within a single
transaction must have the same copy destination that is defined in the
With the API, either the application client can monitor and control these
restrictions, or the API can monitor these restrictions. If the API is monitoring
restrictions, appropriate return codes from the API calls inform the application
client when one or more restrictions are reached.
Always match a dsmBeginTxn call with a dsmEndTxn call to optimize the set of
actions within a pair of dsmBeginTxn and dsmEndTxn calls.
Syntax
dsInt16_t dsmBeginTxn (dsUint32_t dsmHandle);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
Return codes
The return code numbers are provided in parentheses ( ).
Table 22. Return codes for dsmBeginTxn
Return code Explanation
DSM_RC_ABORT_NODE_NOT_AUTHORIZED FROMNODE or FROMOWNER is not allowed for TXN
(36) operations.
dsmBindMC
The dsmBindMC function call associates, or binds, a management class to the passed
object. The object is passed through the include-exclude list that is pointed to in
the options file. If a match is not found in the Include list for a specific
management class, the default management class is assigned. The Exclude list can
prevent objects from a backup but not from an archive.
The application client can use the parameters that are returned in the mcBindKey
structure to determine if this object should be backed up or archived, or whether a
new transaction must be started because of different copy destinations. See
dsmBeginTxn for more information.
Call dsmBindMC before you call dsmSendObj because every object must have a
management class associated with it. This call can be performed within a
transaction or outside of a transaction. For example, within a multiple object
transaction, if dsmBindMC indicates that the object has a different copy destination
than the previous object, the transaction must be ended and a new transaction
started. In this case, another dsmBindMC is not required because one has already
been performed for this object.
Syntax
dsInt16_t dsmBindMC (dsUint32_t dsmHandle,
dsmObjName *objNameP,
dsmSendType sendType,
mcBindKey *mcBindKeyP);
Name Description
stBackup A backup object
stArchive An archive object
stBackupMountWait A backup object
stArchiveMountWait An archive object
For the dsmBindMC call, stBackup and stBackupMountWait are equivalent, and
stArchive and stArchiveMountWait are equivalent.
mcBindKey *mcBindKeyP (O)
This is the address of an mcBindKey structure where the management class
information is returned. The application client can use the information that is
returned here to determine if this object fits within a multiple object
transaction, or to perform a management class query on the management class
that is bound to the object.
Return codes
dsmChangePW
The dsmChangePW function call changes an IBM Spectrum Protect password. On a
multiple-user operating system such as UNIX or Linux, only the root user or the
authorized user can use this call.
On Windows operating systems, you can specify the password in the dsm.opt file.
In this situation, dsmChangePW does not update the dsm.opt file. After the call to
dsmChangePW is made, you must update the dsm.opt file separately.
If dsmChangePW is called for some other reason, the session remains open regardless
of the return code.
Syntax
dsInt16_t dsmChangePW (dsUint32_t dsmHandle,
char *oldPW,
char *newPW);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
char *oldPW (I)
The old password of the caller. The maximum length is
DSM_MAX_VERIFIER_LENGTH.
char *newPW (I)
The new password of the caller. The maximum length is
DSM_MAX_VERIFIER_LENGTH.
Return codes
dsmCleanUp
The dsmCleanUp function call is used if dsmSetUp was called. The dsmCleanUp
function call should be called after dsmTerminate. You cannot make any other calls
after you call dsmCleanUp.
Syntax
dsInt16_t DSMLINKAGE dsmCleanUp
(dsBool_t mtFlag);
Parameters
dsBool_t mtFlag (I)
This parameter specifies that the API was used either in a single thread or a
multithread mode. Possible values include:
dsmDeleteAccess
The dsmDeleteAccess function call deletes current authorization rules for backup
versions or archived copies of your objects. When you delete an authorization rule,
you revoke the access a user has to any files that are specified by the rule.
When you use dsmDeleteAccess, you can only delete one rule at a time. Obtain the
rule ID through the dsmQueryAccess command.
Syntax
dsInt16_t DSMLINKAGE dsmDeleteAccess
(dsUint32_t dsmHandle,
dsUint32_t ruleNum) ;
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsUint32_t ruleNum (I)
The rule ID for the access rule that is deleted. This value is obtained from a
dsmQueryAccess function call.
dsmDeleteFS
The dsmDeleteFS function call deletes a file space from storage. To delete a file
space, you must have the appropriate permissions that your IBM Spectrum Protect
administrator gave you. To determine whether you have the necessary
permissions, call dsmQuerySessInfo. This function call returns a data structure of
type ApiSessInfo, that includes two fields, archDel and backDel.
Note:
v On a UNIX or Linux operating system, only a root user or an authorized user
can delete a file space.
v If the file space that you need to delete contains backup versions, you must have
backup delete authority (backDel = BACKDEL_YES). If the file space contains
archive copies, you must have archive delete authority (archDel =
ARCHDEL_YES). If the file space contains both backup versions and archive
copies, you must have both types of delete authority.
v When using an archive manager server, a file space cannot actually be removed.
This function call returns rc=0 even though the file space was not actually
deleted. The only way to verify that the file space has been deleted is to issue a
filespace query to the server.
v The IBM Spectrum Protect server delete file-space function is a background
process. If errors other than those detected before passing a return code happen,
they are recorded in the IBM Spectrum Protect server log.
Syntax
dsInt16_t dsmDeleteFS (dsUint32_t dsmHandle,
char *fsName,
unsigned char repository);
Return codes
dsmDeleteObj
The dsmDeleteObj function call inactivates backup objects, deletes backup objects,
or it deletes archive objects in storage. The dtBackup type inactivates the currently
active backup copy only. The dtBackupID type removes from the server whichever
object ID is specified. Call this function from within a transaction.
Before you send dsmDeleteObj, send the query sequence that is described in
“Querying the IBM Spectrum Protect system” on page 31 to obtain the information
for delInfo. The call to dsmGetNextQObj returns a data structure named
qryRespBackupData for backup queries or qryRespArchiveData for archive queries.
These data structures contain the information that you need for delInfo.
The value of maxObjPerTxn determines the maximum number of objects that you
can delete in a single transaction. To obtain this value, call dsmQuerySessInfo.
Tip: Your node must have the appropriate permission that your administrator set.
To delete archive objects, you must have archive delete authority. You do not need
backup delete authority to inactivate a backup object.
Syntax
dsInt16_t dsmDeleteObj (dsUint32_t dsmHandle,
dsmDelType delType,
dsmDelInfo delInfo)
Name Description
dtArchive The object to delete was previously archived.
dtBackup The object to inactivate was previously backed up.
dtBackupID The object to delete was previously backed up.
Restriction: Using this delType with objID removes the backup
object from the server. Only an owner of an object can delete it.
Return codes
dsmEndGetData
The dsmEndGetData function call ends a dsmBeginGetData session that obtains
objects from storage.
The dsmEndGetData function call starts after all objects that you want to restore are
processed, or ends the get process prematurely. Call dsmEndGetData to end a
dsmBeginGetData session before you can continue other processing.
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmEndGetDataEx
The dsmEndGetDataEx function call provides the total of LAN-free bytes that were
sent. It is an extension of the dsmEndGetData function call.
Syntax
Parameters
dsmEndGetDataExIn_t *dsmEndGetDataExInP (I)
Passes the end get object dsmHandle that identifies the session and associates
it with subsequent calls.
dsmEndGetDataExOut_t *dsmEndGetDataExOutP (O)
This structure contains this input parameter:
totalLFBytesRecv
The total LAN-free bytes that are received.
dsmEndGetObj
The dsmEndGetObj function call ends a dsmGetObj session that obtains data for a
specified object.
Start the dsmEndGetObj call after an end of data is received for the object. This
indicates that all data was received, or that no more data will be received for this
object. Before you can start another dsmGetObj call, you must call dsmEndGetObj.
Syntax
dsInt16_t dsmEndGetObj (dsUint32_t dsmHandle);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmEndQuery
The dsmEndQuery function call signifies the end of a dsmBeginQuery action. The
application client sends dsmEndQuery to complete a query. This call either is sent
after all query responses are obtained through dsmGetNextQObj, or it is sent to end
a query before all data are returned.
Tip: IBM Spectrum Protect continues to send the query data from the server to the
client in this case, but the API discards any remaining data.
Once a dsmBeginQuery is sent, a dsmEndQuery must be sent before any other activity
can start.
Syntax
dsInt16_t dsmEndQuery (dsUint32_t dsmHandle);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmEndSendObj
The dsmEndSendObj function call indicates the end of data that is sent to storage.
Enter the dsmEndSendObj function call to indicate the end of data from the
dsmSendObj and dsmSendData calls. A protocol violation occurs if this is not
performed. The exception to this rule is if you call dsmEndTxn to end the
transaction. Doing this discards all data that was sent for the transaction.
Syntax
dsInt16_t dsmEndSendObj (dsUint32_t dsmHandle);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
Return codes
Syntax
dsInt16_t dsmEndSendObjEx (dsmEndSendObjExIn_t *dsmEndSendObjExInP,
dsmEndSendObjExOut_t *dsmEndSendObjExOutP);
Parameters
dsmEndSendObjExIn_t *dsmEndSendObjExInP (I)
This parameter passes the end send object dsmHandle that identifies the
session and associates it with subsequent calls.
dsmEndSendObjExOut_t *dsmEndSendObjExOutP (O)
This parameter passes the end send object information:
Name Description
totalBytesSent The total number of bytes that are read from the application.
objCompressed A flag that displays if the object was compressed.
totalCompressedSize The total byte size after compression.
totalLFBytesSent The total LAN-free bytes that were sent.
objDeduplicated A flag that displays if the object was deduplicated by the API.
totalDedupSize Total bytes sent after deduplication.
Return codes
dsmEndTxn
The dsmEndTxn function call ends an IBM Spectrum Protect transaction. Pair the
dsmEndTxn function call with dsmBeginTxn to identify the call or set of calls that are
considered a transaction. The application client can specify on the dsmEndTxn call
whether the transaction must be committed or ended.
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsUint8_t vote (I)
Indicates whether the application client commits all the actions that are done
between the previous dsmBeginTxn call and this call. The following values are
possible:
DSM_VOTE_COMMIT /* commit current transaction */
DSM_VOTE_ABORT /* roll back current transaction */
Return codes
Syntax
dsInt16_t dsmEndTxnEx (dsmEndTxnExIn_t *dsmEndTxnExInP
dsmEndTxnExOut_t *dsmEndTxnExOutP);
Parameters
dsmEndTxnExIn_t *dsmEndTxnExInP (I)
This structure contains the following parameters:
dsmHandle
The handle that identifies the session and associates it with subsequent
IBM Spectrum Protect calls.
dsUint8_t vote (I)
Indicates whether or not the application client commits all the actions that
are done between the previous dsmBeginTxn call and this call. The possible
values are:
DSM_VOTE_COMMIT /* commit current transaction */
DSM_VOTE_ABORT /* roll back current transaction */
Use DSM_VOTE_ABORT only if your application has found a reason to stop the
transaction.
dsmEndTxnExOut_t *dsmEndTxnExOutP (O)
This structure contains the following parameters:
dsUint16_t *reason (O)
If the call to dsmEndTxnEx ends with an error or the value of vote is not
agreed to, this parameter has a reason code indicating why the vote failed.
Tip: The return code for the call might be zero, and the reason code might
be non-zero. Therefore, the application client must always check for errors
on both the return code and the reason (if (rc || reason)) before you can
assume a successful completion.
If the application specifies a vote of DSM_VOTE_ABORT, the reason code
is DSM_RS_ABORT_BY_CLIENT (3). See Appendix A, “API return codes
source file: dsmrc.h,” on page 143 for a list of the possible reason codes.
Numbers 1 through 50 in the return codes list are reserved for the reason
codes. If the server ends the transaction, the return code is
DSM_RC_CHECK_REASON_CODE. In this case, the reason value contains
more information on the cause of the abort.
groupLeaderObjId
The group leader object ID that is returned when the
DSM_ACTION_OPEN flag is used with the dsmGroupHandler call.
dsmGetData
The dsmGetData function call obtains a byte stream of data from IBM Spectrum
Protect and places it in the caller's buffer. The application client calls dsmGetData
when there is more data to receive from a previous dsmGetObj or dsmGetData call.
Syntax
dsInt16_t dsmGetData (dsUint32_t dsmHandle,
DataBlk *dataBlkPtr);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
DataBlk *dataBlkPtr (I/O)
Points to a structure that includes both a pointer to the buffer for the data that
is received and the size of the buffer. On return, this structure contains the
number of bytes that is actually transferred. See Appendix B, “API type
definitions source files,” on page 153 for the type definition.
Return codes
dsmGetBufferData
The dsmGetBufferData function call receives a byte stream of data from IBM
Spectrum Protect through a buffer. After each call the application needs to copy the
data and release the buffer through a call to dsmReleaseBuffer. If the number of
buffers held by the application equals the numTsmBuffers specified in the
dsmInitEx call, the dsmGetBufferData function blocks until a dsmReleaseBuffer is
called.
Syntax
dsInt16_t dsmGetBufferData (getDatatExIn_t *dsmGetBufferDataExInP,
getDataExOut_t *dsmGetBufferDataExOutP) ;
Parameters
getDataExIn_t * dsmGetBufferDataExInP (I)
This structure contains the following input parameter.
dsUint32_t dsmHandle
The handle that identifies the session and associates it with a previous
dsmInitEx call.
getDataExOut_t * dsmGetBufferDataExOutP (0)
This structure contains the following output parameters.
dsUint8_t tsmBufferHandle(0)
The handle that identifies the buffer received.
char *dataPtr(0)
The address to which the data was written.
dsUint32_t numBytes(0)
Actual number of bytes written by IBM Spectrum Protect.
Return codes
The return code numbers are provided in parentheses ( ).
Table 33. Return codes for dsmGetBufferData
Return code Explanation
DSM_RC_BAD_CALL_SEQUENCE (2041) The call was not issued in the proper state.
DSM_RC_OBJ_ENCRYPTED (2049) This function cannot be used for encrypted objects.
DSM_RC_OBJ_COMPRESSED (2048) This function cannot be used for compressed objects.
DSM_RC_BUFF_ARRAY_ERROR (2045) A buffer array error occurred.
The dsmGetNextQObj call is called one or more times. Each time the function is
called, either a single query record is retrieved, or an error or a DSM_RC_FINISHED
reason code is returned. If DSM_RC_FINISHED is returned, there is no more data to
process. When all query data is retrieved, or if no more query data is needed, send
the dsmEndQuery call to end the query process.
The dataBlkPtr parameter must point to a buffer that is defined with the
qryResp*Data structure type. The context in which dsmGetNextQObj is called
determines the type of structure that is entered on the query response.
Syntax
dsInt16_t dsmGetNextQObj (dsUint32_t dsmHandle,
DataBlk *dataBlkPtr);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
DataBlk *dataBlkPtr (I/O)
Points to a structure that includes both a pointer to the buffer for the data to
be received and the size of the buffer. This buffer is the qryResp*Data response
structure. On return, this structure contains the number of bytes that is
transferred. The structure that is associated with each type of query is
described in the following table. For more information about the type
definition of DataBlk, see the following topic: Appendix B, “API type
definitions source files,” on page 153.
Table 34. DataBlk pointer structure
Query Response structure Fields of special interest
qtArchive qryRespArchiveData
sizeEstimate
Contains the value that is passed
on a previous dsmSendObj call.
mediaClass
Can have a value of MEDIA_FIXED if
the object is on disk, or
MEDIA_LIBRARY if the object is on
tape.
clientDeduplicated
Indicates whether this object is
deduplicated by the client.
Return codes
The following table describes the return codes for the dsmGetNextQObj function call.
Table 35. Return codes for the dsmGetNextQObj function call
Return code Return code number Description
DSM_RC_ABORT_NO_MATCH 2 No match for the query was
requested.
DSM_RC_FINISHED 121 Finished processing (start
dsmEndQuery). There is no more data
to process.
DSM_RC_UNKNOWN_FORMAT 122 The file that IBM Spectrum Protect
attempted to restore or retrieve has an
unknown format.
dsmGetObj
The dsmGetObj function call obtains the requested object data from the IBM
Spectrum Protect data stream and places it in the caller's buffer. The dsmGetObj call
uses the object ID to obtain the next object or partial object from the data stream.
The data for the indicated object is placed in the buffer to which DataBlk points. If
more data is available, you must make one or more calls to dsmGetData to receive
the remaining object data until a return code of DSM_RC_FINISHED is returned.
Check the numBytes field in DataBlk to see whether any data remains in the buffer.
Objects should be asked for in the order that they were listed on the
dsmBeginGetData call in the dsmGetList parameter. The exception is when the
application client needs to pass over an object in the data stream to get to an object
later in the list. If the object that is indicated by the object ID is not the next object
in the stream, the data stream is processed until the object is located, or the stream
is completed. Use this feature with care, because it might be necessary to process
and discard large amounts of data to locate the requested object.
Syntax
dsInt16_t dsmGetObj (dsUint32_t dsmHandle,
ObjID *objIdP,
DataBlk *dataBlkPtr);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
ObjID *objIdP (I)
A pointer to the ID of the object to restore.
DataBlk *dataBlkPtr (I/O)
A pointer to the buffer where the restored data are placed.
dsmGroupHandler
The dsmGroupHandler function call performs an action on a logical file group
depending on the input that is given. The client relates a number of individual
objects together to reference and manage on the IBM Spectrum Protect server as a
logical group.
Syntax
dsInt16_t dsmGroupHandler (dsmGroupHandlerIn_t *dsmGroupHandlerInP,
dsmGroupHandlerOut_t *dsmGroupHandlerOutP);
Parameters
dsmGroupHandlerIn_t *dsmGroupHandlerInP (I)
Passes group attributes to the API.
groupType
The type of the group. Values include:
v DSM_GROUPTYPE_PEER - peer group
actionType
The action to be executed. Values include:
v DSM_GROUP_ACTION_OPEN - creates a new group
v DSM_GROUP_ACTION_CLOSE - commits and saves an open group
v DSM_GROUP_ACTION_ADD - appends to a group
v DSM_GROUP_ACTION_ASSIGNTO - assigns to another group
v DSM_GROUP_ACTION_REMOVE- removes a member from a group
memberType.
The group type of the object. Values include:
v DSM_MEMBERTYPE_LEADER - group leader
v DSM_MEMBERTYPE_MEMBER - group member
*uniqueGroupTagP
A unique string ID that is associated with a group.
Return codes
dsmInit
The dsmInit function call starts an API session and connects the client to IBM
Spectrum Protect storage. The application client can have only one active session
open at a time. To open another session with different parameters, use the
dsmTerminate call first to end the current session.
To permit cross-node query and restore or retrieve, use the -fromnode and
-fromowner string options. See “Accessing objects across nodes and owners” on
page 23 for more information.
Syntax
dsInt16_t dsmInit (dsUint32_t *dsmHandle,
dsmApiVersion *dsmApiVersionP,
char *clientNodeNameP,
char *clientOwnerNameP,
char *clientPasswordP,
char *applicationType,
char *configfile,
char *options);
Parameters
dsUint32_t *dsmHandle (O)
The handle that identifies this initialization session and associates it with
subsequent IBM Spectrum Protect calls.
dsmApiVersion *dsmApiVersionP (I)
A pointer to the data structure identifying the version of the API that the
application client is using for this session. The structure contains the values of
the three constants, DSM_API_VERSION, DSM_API_RELEASE, and
DSM_API_LEVEL, that are set in the dsmapitd.h file. A previous call to
dsmQueryApiVersion must be performed to ensure that compatibility exists
between the application client API version and the version of the API library
that is installed on the user's workstation.
Return codes
Related concepts:
Client options file overview
Processing options
dsmInitEx
The dsmInitEx function call starts an API session by using the additional
parameters for extended verification.
Syntax
dsInt16_t dsmInitEx (dsUint32_t *dsmHandleP,
dsmInitExIn_t *dsmInitExInP,
dsmInitExOut_t *dsmInitExOutP) ;
Parameters
dsUint32_t *dsmHandleP (O)
The handle that identifies this initialization session and associates it with
subsequent IBM Spectrum Protect calls.
dsmInitExIn_t *dsmInitExInP
This structure contains the following input parameters:
dsmApiVersion *dsmApiVersionP (I)
This parameter is a pointer to the data structure that identifies the version
of the API that the application client is using for this session. The structure
contains the values of the four constants, DSM_API_VERSION,
DSM_API_RELEASE, DSM_API_LEVEL, and DSM_API_SUBLEVEL that
are set in the dsmapitd.h file. Call dsmQueryApiVersionEx and verify that
the API version of the application client and the version of the API library
that is installed on the user's workstation is compatible.
char *clientNodeNameP (I)
This parameter is a pointer to the node for the IBM Spectrum Protect
session. All sessions must be associated with a node name. The
DSM_MAX_NODE_LENGTH constant in the dsmapitd.h file sets the
maximum size for a node name.
The node name is not case-sensitive.
Return codes
Related concepts:
Client options file overview
Processing options
dsmLogEvent
The dsmLogEvent function call logs a user message (ANE4991 I) to the server log
file, to the local error log, or to both. A structure of type logInfo is passed in the
call. This call must be performed while at InSession state inside a session. Do not
perform it within a send, get, or query. To retrieve messages logged on the server,
use the query actlog command through the administrative client.
Syntax
dsInt16_t dsmLogEvent
(dsUint32_t dsmHandle,
logInfo *logInfoP);
Parameters
dsUint32_t dsmHandle(I)
The handle that associates this call with a previous dsmInitEx call.
logInfo *logInfoP (I)
Passes the message and destination. The application client is responsible for
allocating storage for the structure.
The fields in the logInfo structure are:
message
The text of the message to be logged. This must be a null-ended string.
The maximum length is DSM_MAX_RC_MSG_LENGTH.
dsmLogtype
Specifies where to log the message. Possible values include: logServer,
logLocal, logBoth.
dsmLogEventEx
The dsmLogEventEx function call logs a user message to the server log file, to the
local error log, or to both. This call must be made while at an InSession state
within a session. The call cannot be made within a send, get, or query call.
Summary state diagram: For an overview of the session interactions, see the
summary state diagram in the following topic:
Figure 20 on page 73
The severity determines the IBM Spectrum Protect message number. To view
messages that are logged on the server, use the query actlog command through
the administrative client. Use the IBM Spectrum Protect client option,
errorlogretention, to prune the client error log file if the application generates
numerous client messages written to the client log, dsmLogType either logLocal or
logBoth. For more information, see the IBM Spectrum Protect server
documentation.
Syntax
extern dsInt16_t DSMLINKAGE dsmLogEventEx(
dsUint32_t dsmHandle,
dsmLogExIn_t *dsmLogExInP,
dsmLogExOut_t *dsmLogExOutP
);
Parameters
dsUint32_t dsmHandle(I)
The handle that associates this call with a previous dsmInitEx call.
dsmLogExIn_t *dsmLogExInP
This structure contains the input parameters.
dsmLogSeverity severity;
This parameter is the event severity. The possible values are:
logSevInfo, /* information ANE4990 */
logSevWarning, /* warning ANE4991 */
logSevError, /* Error ANE4992 */
logSevSevere /* severe ANE4993 */
char appMsgID[8];
This parameter is a string to identify the specific application message. A
suitable format is three characters that are followed by four numbers, for
example: DSM0250.
dsmLogType logType;
This parameter specifies where to direct the event. The parameter has the
following possible values:
v logServer
Return codes
dsmQueryAccess
The dsmQueryAccess function call queries the server for all access authorization
rules for either backup versions or archived copies of your objects. A pointer to an
array of access rules is passed in to the call, and the completed array is returned. A
pointer to the number of rules is passed in to indicate how many rules are in the
array.
Syntax
dsInt16_t DSMLINKAGE dsmQueryAccess
(dsUint32_t dsmHandle),
qryRespAccessData **accessListP,
dsUint16_t *numberOfRules) ;
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
qryRespAccessData **accessListP (O)
A pointer to an array of qryRespAccessData elements that the API library
allocates. Each element corresponds to an access rule. The number of elements
in the array is returned in the numberOfRules parameter. The information that
is returned in each qryRespAccessData element includes the following:
Name Description
ruleNumber The ID for the access rule. This identifies the rule for deletion.
AccessType The backup or archive type.
Node The node on which you gave access.
Owner The user to whom you gave access.
objName The high-level, or low-level file space descriptors.
dsmQueryApiVersion
The dsmQueryApiVersion function call performs a query request for the API library
version that the application client accesses.
All updates to the API are made in an upward-compatible format. Any application
client with an API version or release less than, or equal to, the API library on the
end user's workstation operates without change. Be aware before you proceed that
should the dsmQueryApiVersion call return a version or version release older than
that of the application clients, some API calls might be enhanced in a manner that
is not supported by the end user's older version of the API.
The application API version number is stored in the dsmapitd.h header file as
constants DSM_API_VERSION, DSM_API_RELEASE, and DSM_API_LEVEL.
Syntax
void dsmQueryApiVersion (dsmApiVersion *apiVersionP);
Parameters
dsmApiVersion *apiVersionP (O)
This parameter is a pointer to the structure that contains the API library
version, release, and level components. For example, if the library is version
1.1.0, then, after returning from the call, the fields of the structure contain the
following values:
dsmApiVersionP->version = 1
dsmApiVersionP->release = 1
dsmApiVersionP->level = 0
dsmQueryApiVersionEx
The dsmQueryApiVersionEx function call performs a query request for the API
library version that the application client accesses.
All updates to the API are made in an upward-compatible format. Any application
client that has an API version or release less than or equal to the API library on the
end user's workstation operates without change. See Summary of Code Changes in
the README_api_enu file for exceptions to upward compatibility. If the
dsmQueryApiVersionEx call returns a version or version release that is different from
that of the application client, be aware before you proceed that some API calls
might be enhanced in a manner that is not supported by the end user's older
version of the API.
The application API version number is stored in the dsmapitd.h header file as
constants DSM_API_VERSION, DSM_API_RELEASE, DSM_API_LEVEL, and
DSM_API_SUBLEVEL.
Syntax
void dsmQueryApiVersionEx (dsmApiVersionEx *apiVersionP);
dsmQueryCliOptions
The dsmQueryCliOptions function call queries important option values in the user's
option files. A structure of type optStruct is passed in the call and contains the
information. This call is performed before dsmInitEx is called, and it determines
the setup before the session.
Syntax
dsInt16_t dsmQueryCliOptions
(optStruct *optstructP);
Parameters
optStruct *optstructP (I/O)
This parameter passes the address of the structure that the API completes. The
application client is responsible for allocating storage for the structure. On
successful return, the appropriate information is entered in the fields in the
structure.
The following information is returned in the optStruct structure:
Name Description
dsmiDir The value of the environment DSMI_DIR variable.
dsmiConfig The client option file as specified by the DSMI_CONFIG
environment variable.
serverName The name of the IBM Spectrum Protect server.
commMethod The communication method selected. See the #defines for
DSM_COMM_* in the dsmapitd.h file.
serverAddress The address of the server that is based on the communication
method.
nodeName The client node (machine) name.
compression This field provides information regarding the compression option.
passwordAccess The values are: bTrue for generate, and bFalse for prompt.
Related concepts:
Processing options
See Appendix B, “API type definitions source files,” on page 153 for information
about the content of the structure that is passed and each field within it.
Syntax
dsInt16_t dsmQuerySessInfo (dsUint32_t dsmHandle,
ApiSessInfo *SessInfoP);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
ApiSessInfo *SessInfoP (I/O)
This parameter passes the address of the structure that the API enters. The
application client is responsible for allocating storage for the structure and for
completing the field entries that indicate the version of the structure that is
used. On successful return, the fields in the structure are completed with the
appropriate information. The adsmServerName is the name that is given in the
define server command on the IBM Spectrum Protect server. If the
archiveRetentionProtection field is true, the server is enabled for retention
protection.
Return codes
This call is started after a successful dsmInitEx call. The values that are returned
might be different from the values returned on a dsmQueryCliOptions call,
depending on values that are passed to the dsmInitEx call, primarily optString,
and optFile. For information about option precedence, see “Understanding
configuration and options files” on page 1.
Syntax
dsInt16_t dsmQuerySessOptions
(dsUint32_t dsmHandle,
optStruct *optstructP);
Parameters
dsUint32_t dsmhandle(I)
The handle that associates this call with a previous dsmInitEx call.
optStruct *optstructP (I/O)
This parameter passes the address of the structure that the API completes. The
application client is responsible for allocating storage for the structure. On
successful return, the fields in the structure are completed with the appropriate
information.
The information returned in the optStruct structure is:
Name Description
dsmiDir The value of the DSMI_DIR environment variable.
dsmiConfig The dsm.opt file that the DSMI_CONFIG environment variable
specifies.
serverName The name of the IBM Spectrum Protect server stanza in the
options file.
commMethod The communication method that was selected. See the #defines for
DSM_COMM_* in the dsmapitd.h file.
serverAddress The address of the server that is based on the communication
method.
nodeName The name of the client's node (machine).
compression The value of the compression option (bTrue=on and bFalse=off).
compressAlways The value of the compressalways option (bTrue=on and
bFalse=off).
passwordAccess Value bTrue for generate, and bFalse for prompt.
Related concepts:
Processing options
The msg parameter displays the message prefix return code in parentheses ( ),
followed by the message text. For example, a call to dsmRCMsg might return the
following:
ANS0264E (RC2300) Only root user can execute dsmChangePW or dsmDeleteFS.
For some languages where characters are different in ANSII and OEM code pages,
it might be necessary to convert strings from ANSII to OEM before printing them
out (for example, Eastern European single-byte character sets). The following is an
example:
dsmRCMsg(dsmHangle, rc, msgBuf);
#ifdef WIN32
#ifndef WIN64
CharToOemBuff(msgBuf, msgBuf, strlen(msgBuf));
#endif
#endif
printf("
Syntax
dsInt16_t dsmRCMsg (dsUint32_t dsmHandle,
dsInt16_t dsmRC,
char *msg);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsInt16_t dsmRC (I)
The API return code of the associated message text. The API return codes are
listed in the dsmrc.h file. See Appendix A, “API return codes source file:
dsmrc.h,” on page 143 for more information.
char *msg (O)
This parameter is the message text that is associated with the return code,
dsmRC. The caller is responsible for allocating enough space for the message
text.
The maximum length for msg is defined as DSM_MAX_RC_MSG_LENGTH.
On platforms that have National Language Support and a choice of language
message files, the API returns a message string in the national language.
Return codes
Application clients should not use the same file space names that a backup-archive
client would use.
v On UNIX or Linux, run the df command for these names.
v On Windows, these names are generally the volume labels that are associated
with the different drives on your system.
Syntax
dsInt16_t dsmRegisterFS (dsUint32_t dsmHandle,
regFSData *regFilespaceP);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
regFSData *regFilespaceP (I)
This parameter passes the name of the file space and associated information
that you need to register with the IBM Spectrum Protect server.
Tip: The fstype field includes the prefix, “API:”. All file space queries display
this string. For example, if the user passes myfstype for fstype in
dsmRegisterFS, the actual value string on the server is returned as
API:myfstype when queried. This prefix distinguishes API objects from
backup-archive objects.
The usable area for fsInfo is now DSM_MAX_USER_FSINFO_LENGTH.
Return codes
dsmReleaseBufferSyntax
dsInt16_t dsmReleaseBuffer (releaseBufferIn_t *dsmReleaseBufferInP,
releaseBufferOut_t *dsmReleaseBufferOutP) ;
Parameters
releaseBufferIn_t * dsmReleaseBufferInP (I)
This structure contains the following input parameters.
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsUint8_t tsmBufferHandle(I)
The handle that identifies this buffer.
char *dataPtr(I)
The address to which the application is written.
Return codes
The return code numbers are provided in parentheses ( ).
Table 45. Return codes for dsmReleaseBuffer
Return code Explanation
DSM_RC_BAD_CALL_SEQUENCE The call was not issued in the proper state.
DSM_RC_INVALID_TSMBUFFER The handle or the value of dataPtr are invalid.
DSM_RC_BUFF_ARRAY_ERROR A buffer array error occurred.
dsmRenameObj
The dsmRenameObj function call renames the high-level or low-level object name.
For backup objects, pass in the current object name and changes either for
high-level or low-level object names. For archive objects, pass in the current object
file space name and object ID, and changes either for high-level or low-level object
names. Use this function call within dsmBeginTxn and dsmEndTxn calls.
The merge flag determines whether or not a duplicate backup object name is
merged with the existing backups. If the new name corresponds to an existing
object and merge is true, the current object is converted to the new name and it
becomes the active version of the new name while the existing active object that
had that name becomes the top most inactive copy of the object. If the new name
corresponds to an existing object and merge is false, the function then returns the
return code, DSM_RC_ABORT_DUPLICATE_OBJECT.
Restrictions:
v Only the owner of the object can rename it.
Syntax
dsInt16_t dsmRenameObj (dsmRenameIn_t *dsmRenameInP,
dsmRenameOut_t *dsmRenameOutP);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmRenameIn_t *dsmRenameInP
This structure contains the input parameters.
dsUint8_t repository (I);
This parameter indicates whether the file space to delete is in the backup
repository or the archive repository.
dsmObjName *objNameP (I);
This parameter is a pointer to the structure that contains the current file
space name, high-level object name, low-level object name, and object type.
char newHl [DSM_MAX_HL_LENGTH + 1];
This parameter specifies the new high-level name.
char newLl [DSM_MAX_LL_LENGTH + 1];
This parameter specifies the new low-level name.
dsBool_t merge;
This parameter determines whether or not a backup object is merged with
duplicate named objects. The values are either true or false.
ObjID;
The object ID for archive objects.
dsmRenameOut_t *dsmRnameOutP
This structure contains the output parameters.
Return codes
dsmRequestBuffer
The dsmRequestBuffer function returns a buffer to IBM Spectrum Protect. The
application calls dsmRequestBuffer after a dsmGetDataEx was called and the
application has moved all the data out of the buffer and is ready to release it.
dsmReleaseBuffer requires that dsmInitEx was called with the UseTsmBuffers set to
btrue and a non-zero value was provided for numTsmBuffers. dsmReleaseBuffer
should also be called if the application is about to call dsmTerminate and it still
holds IBM Spectrum Protect buffers.
Syntax
dsInt16_t dsmRequestBuffer (getBufferIn_t *dsmRequestBufferInP,
getBufferOut_t *dsmRequestBufferOutP) ;
Parameters
getBufferIn_t * dsmRequestBufferInP (I)
This structure contains the following input parameter:
dsUint32_t dsmHandle
The handle that identifies the session and associates it with a previous
dsmInitEx call.
getBufferOut_t *dsmRequestBufferOut P (0)
This structure contains the output parameters.
dsUint8_t tsmBufferHandle(0)
The handle that identifies this buffer.
char *dataPtr(0)
The address to which application is written.
dsUint32_t *bufferLen(0)
Maximum number of bytes that can be written to this buffer.
Return codes
Note: The server must be at version 5.2.2.0 or later for this function to work.
Before you send dsmRetentionEvent, send the query sequence that is described in
“Querying the IBM Spectrum Protect system” on page 31 to obtain the information
for the object. The call to dsmGetNextQObj returns a data structure named
qryRespArchiveData for archive queries. This data structure contains the
information that is needed for dsmRetentionEvent.
Syntax
extern dsInt16_t DSMLINKAGE dsmRetentionEvent(
dsmRetentionEventIn_t *ddsmRetentionEventInP,
dsmRetentionEventOut_t *dsmRetentionEventOutP
);
Parameters
dsmRetentionEventIn_t *dsmRetentionEventP
This structure contains the following input parameters:
dsUint16_t stVersion;
This parameter indicates the structure version.
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmEventType_t evenType (I);
This parameter indicates the event type. See the beginning of this section
for the meaning of these possible values: eventRetentionActivate,
eventHoldObj, eventReleaseObj
dsmObjList_t objList;
This parameter indicates a list of object IDs to signal.
dsmSendBufferData
The dsmSendBufferData function call sends a byte stream of data to IBM Spectrum
Protect through a buffer that was provided in a previous dsmReleaseBuffer call.
The application client can pass any type of data for storage on the server. Usually
this data are file data, but it is not limited to file data. You can call
dsmSendBufferData several times, if the byte stream of data that you are sending is
large. Regardless of whether the call succeeds or fails, the buffer is released.
Restriction: When you use the useTsmBuffers option, even if an object is included
for compression, the object is not compressed.
Syntax
dsInt16_t dsmSendBufferData (sendBufferDataIn_t *dsmSendBufferDataExInP,
sendBufferDataOut_t *dsmSendBufferDataOutP) ;
Parameters
sendBufferDataIn_t * dsmSendBufferDataInP (I)
This structure contains the following input parameters.
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsUint8_t tsmBufferHandle(I)
The handle that identifies the buffer to send.
char *dataPtr(I)
The address to which application data was written.
dsUint32_t numBytes(I)
The actual number of bytes written by the application (should always be
less than the value provided in dsmReleaseBuffer).
Return codes
dsmSendData
The dsmSendData function call sends a byte stream of data to IBM Spectrum Protect
through a buffer. The application client can pass any type of data for storage on
the server. Usually, these data are file data, but are not limited to such. You can call
dsmSendData several times, if the byte stream of data that you want to send is
large.
Restriction: The application client cannot reuse the buffer that is specified in
dsmSendData until the dsmSendData call returns.
Syntax
dsInt16_t dsmSendData (dsUint32_t dsmHandle,
DataBlk *dataBlkPtr);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
DataBlk *dataBlkPtr (I/O)
This parameter points to a structure that includes both a pointer to the buffer
from which the data are to be sent, as well as the size of the buffer. On return,
this structure contains the number of bytes that is actually transferred. See
Appendix B, “API type definitions source files,” on page 153 for the type
definition.
Return codes
dsmSendObj
The dsmSendObj function call starts a request to send a single object to storage.
Multiple dsmSendObj calls and associated dsmSendData calls can be made within the
bounds of a transaction for performance reasons.
The dsmSendObj call processes the data for the object as a byte stream passed in
memory buffers. The dataBlkPtr parameter in the dsmSendObj call permits the
application client to either:
v Pass the data and the attributes (the attributes are passed through the
objAttrPtr ) of the object in a single call.
v Specify part of the object data through the dsmSendObj call and the remainder of
the data through one or more dsmSendData calls.
Alternatively, the application client can specify only the attributes through the
dsmSendObj call and specify the object data through one or more calls to
dsmSendData. For this method, set dataBlkPtr to NULL on the dsmSendObj call.
Tip: For certain object types, byte stream data might not be associated with the
data; for example, a directory entry with no extended attributes.
Follow all object data that is sent to storage with a dsmEndSendObj call. If you do
not have object data to send to the server, or all data was contained within the
dsmSendObj call, start a dsmEndSendObj call before you can start another dsmSendObj
call. If multiple data sends were required through the dsmSendData call, the
dsmEndSendObj follows the last send to indicate the state change.
Syntax
dsInt16_t dsmSendObj (dsUint32_t dsmHandle,
dsmSendType sendType,
void *sendBuff,
dsmObjName *objNameP,
ObjAttr *objAttrPtr,
DataBlk *dataBlkPtr);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmSendType sendType (I)
This parameter specifies the type of send that is being performed. Possible
values include:
Name Description
stBackup A backup object that is sent to the server.
stArchive An archive object that is sent to the server.
stBackupMountWait A backup object for which you want the server to wait until the
necessary device, such as a tape, is mounted.
stArchiveMountWait An archive object for which you want the server to wait until
the necessary device, such as a tape, is mounted.
Note: Use the MountWait types if there is any possibility that your application
user might send data to a tape.
void *sendBuff (I)
This parameter is a pointer to a structure that contains other information
specific to the sendType on the call. Currently, only a sendType of stArchive has
an associated structure. This structure is called sndArchiveData and it contains
the archive description.
dsmObjName *objNameP (I)
This parameter is a pointer to the structure that contains the file space name,
high-level object name, low-level object name, and object type. See “Object
names and IDs” on page 21 for more information.
ObjAttr *objAttrPtr (I)
This parameter passes object attributes of interest to the application. See
Appendix B, “API type definitions source files,” on page 153 for the type
definition.
The attributes are:
v owner refers to the owner of the object. Determining whether the owner is
declared to be a specific name or an empty string is important when getting
the object back from IBM Spectrum Protect storage. See “Accessing objects as
session owner” on page 23 for more information.
v sizeEstimate is a best estimate of the total size of the data object to send to
the server. Be as accurate as possible on this size, because the server uses
this attribute for efficient space allocation and object placement within its
storage resources.
Note: The size estimate is for the total size of the data object in bytes.
Objects with a size smaller than DSM_MIN_COMPRESS_SIZE do not
compress.
If your object has no bit data (only the attribute information from this call),
the sizeEstimate should be zero.
Note: Starting with Version 5.1.0, the copy destination within a transaction
is not checked for consistency on zero-length objects.
v objCompressed is a Boolean value that states whether or not the object data
have already been compressed.
If the object is compressed (object compressed=bTrue), IBM Spectrum Protect
does not try to compress it again. If it is not compressed, IBM Spectrum
Protect decides whether to compress the object, based on the values of the
compression option set by the administrator and set in the API configuration
sources.
If your application plans to use partial object restore or retrieve, you cannot
compress the data while sending it. To enforce this, set
ObjAttr.objCompressed to bTrue.
v objInfo saves information about the particular object.
Return codes
dsmSetAccess
The dsmSetAccess function call gives other users or nodes access to backup
versions or archived copies of your objects, access to all your objects, or access to a
selective set. When you give access to another user, that user can query, restore, or
retrieve your files. This command supports wildcards for the following fields: fs,
hl, ll, node, owner.
Note: You cannot give access to both backup versions and archive copies by using
a single command. You must specify either backup or archive.
Syntax
dsInt16_t DSMLINKAGE dsmSetAccess
(dsUint32_t dsmHandle,
dsmSetAccessType accessType,
dsmObjName *objNameP,
char *node,
char *owner);
Name Description
atBackup Specifies that access is being set to backup objects.
atArchive Specifies that the access is being set for archive objects.
Note: To specify all file spaces, use an asterisk (*) for the file space name.
char *node (I)
This parameter is a pointer to the node name for which access is given. For
any node, specify an asterisk (*).
char *owner (I)
This parameter is a pointer to the user name on the node to which you gave
access. For all users, specify an asterisk (*).
Return codes
dsmSetUp
The dsmSetUp function call overwrites environment variable values. Call dsmSetUp
before dsmInitEx. The values that were passed in the envSetUp structure overwrite
any existing environment variables or defaults. If you specify NULL for a field,
values are taken from the environment. If you do not set a value, the values are
taken from the defaults.
Requirements:
1. If you use dsmSetUp, always call dsmTerminate before dsmCleanUp.
2. API instrumentation can only be activated if the testflag INSTRUMENT: API is
set in the configuration file and the dsmSetUp or dsmCleanUp calls are used in
the application.
Parameters
dsBool_t mtFlag (I)
This parameter specifies if the API will be used in a single thread, or a
multithread mode. Values include:
DSM_SINGLETHREAD
DSM_MULTITHREAD
Name Description
dsmiDir A fully-qualified directory path that contains a message file on
UNIX or Linux. It also specifies the dsm.sys directories.
dsmiConfig The fully-qualified name of the client options file.
dsmiLog The fully-qualified path of the error log directory.
argv Pass the argv[0] name of the calling program if the application
must run with authorized user authority. See “Controlling
access to password files” on page 19 for more information.
logName The file name for an error log if the application does not use
dsierror.log.
inclExclCaseSensitive Indicates whether include/exclude rules are case-sensitive or
case-insensitive. This parameter can be used on Windows only,
it is ignored elsewhere.
Return codes
dsmTerminate
The dsmTerminate function call ends a session with the IBM Spectrum Protect
server and cleans up the IBM Spectrum Protect environment.
Syntax
There are no return codes that are specific for this call.
dsInt16_t dsmTerminate (dsUint32_t dsmHandle);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmUpdateFS
The dsmUpdateFS function call updates a file space in IBM Spectrum Protect
storage. This update ensures that the administrator has a current record of your
file space.
Syntax
dsInt16_t dsmUpdateFS (dsUint32_t dsmHandle,
char *fs,
dsmFSUpd *fsUpdP,
dsUint32_t fsUpdAct);
Parameters
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
char *fs (I)
This parameter is a pointer to the file space name.
dsmFSUpd *fsUpdP (I)
This parameter is a pointer to the structure that has the correct fields for the
update that you want. Complete only those fields that need updating.
dsUint32_t fsUpdAct (I)
A 2-byte bit map that indicates which of the fields to update. The bit masks
have the following values:
v DSM_FSUPD_FSTYPE
v DSM_FSUPD_FSINFO
Return codes
The following table lists return codes for the dsmUpdateFS function call.
Table 54. Return codes for dsmUpdateFS
Return code Return code number Description
DSM_RC_FS_NOT_REGISTERED 2061 File space name is not registered.
DSM_RC_WRONG_VERSION_PARM 2065 The API version of the application
client is different from the IBM
Spectrum Protect library version.
DSM_RC_FSINFO_TOOLONG 2106 File space information is too long.
dsmUpdateObj
The dsmUpdateObj function call updates the meta information associated with an
active backup or archive object already on the server. The application bit data is
not affected. To update an object, you must give a specific non-wildcard name. To
update an archived object, set the dsmSendType to stArchive. Only the latest named
archive object is updated.
You can only start the dsmUpdateObj call in the session state; it cannot be called
inside a transaction because it performs its own transaction. And, you can update
only one object at a time.
Restriction: On a UNIX or Linux operating system, if you change the owner field,
you cannot query or restore the object unless you are the root user.
Syntax
dsInt16_t dsmUpdateObj
(dsUint32_t dsmHandle,
dsmSendType sendType,
void *sendBuff,
dsmObjName *objNameP,
ObjAttr *objAttrPtr, /* objInfo */
dsUint16_t objUpdAct); /* action bit vector */
Parameters
The field descriptions are the same as those in dsmSendObj, with the following
exceptions:
dsmObjName *objNameP (I)
You cannot use a wildcard.
ObjAttr *objAttrPtr (I)
The objCompressed field is ignored for this call.
Return codes
dsmUpdateObjEx
The dsmUpdateObjEx function call updates the meta information that is associated
with an active backup or archive object that is on the server. The application bit
data is not affected. To update an object, you must specify a non-wildcard name,
or you can specify the object ID to update a specific archived object. You cannot
use wildcard characters when specifying the name. To update a backup object, set
the dsmSendType parameter to stBackup. To update an archived object, set the
dsmSendType parameter to stArchive.
Restriction: On a UNIX or Linux operating system, if you change the owner field,
you cannot query or restore the object unless you are the root user. Only the
current active version of a backup object can be updated.
Syntax
dsInt16_t dsmUpdateObjEx
(dsmUpdateObjExIn_t *dsmUpdateObjExInP,
dsmUpdateObjExOut_t *dsmUpdateObjExOutP);
Parameters
dsmUpdateObjExIn_t *dsmUpdateObjExInP
This structure contains the following input parameters:
dsUint16_t stVersion (I)
The current version of the structure that is used.
dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.
dsmSendType sendType (I)
The type of send that is being performed. The value can be:
stBackup
A backup object that is sent to the server.
stArchive
An archive object that is sent to the server.
dsmObjName *objNameP (I)
A pointer to the structure that contains the filespace name, high-level
object name, low-level object name, and object type. You cannot use a
wildcard.
ObjAttr *objAttrPtr (I)
Passes object attributes to the application. The values that are updated
depend on the flags in the objUpdAct field. The objCompressed attribute is
ignored for this call.
The attributes are:
v owner changes the owner if a new name is entered.
v sizeEstimate is the actual amount of data that is sent in bytes. The
value is stored in the IBM Spectrum Protect meta data for future use.
v objCompressed is a Boolean value that states whether or not the object
data have already been compressed.
v objInfo is an attribute that contains the new information to be placed in
the objInfo field. Set the objInfoLength to the length of the new
objInfo.
v mcNameP contains the name of a management class that overrides the
management class that is obtained from dsmBindMC.
dsUint32_t objUpdAct
Specifies the bit masks and actions for objUpdAct are:
DSM_BACKUPD_MC
Updates the management class for the object.
Return codes
The return code numbers are provided in parentheses ( ) in the following table.
Table 56. Return codes for dsmUpdateObjEx
Return code Explanation
DSM_RC_INVALID_ACTION (2012) Invalid action.
DSM_RC_FS_NOT_REGISTERED (2061) File space not registered.
DSM_RC_BAD_CALL_SEQUENCE (2041) Sequence of calls is invalid.
DSM_RC_WILDCHAR_NOTALLOWED Wildcard characters are not allowed.
(2050)
DSM_RC_ABORT_NO_MATCH (2) Previous query does not match.
The information that is provided here contains a point-in-time copy of the dsmrc.h
file that is distributed with the API. View the file in the API distribution package
for the latest version.
/***********************************************************************
* Tivoli Storage Manager *
* API Client Component *
* *
* (C) Copyright IBM Corporation 1993,2010 *
***********************************************************************/
/**********************************************************************/
/* Header File Name: dsmrc.h */
/* */
/* Descriptive-name: Return codes from Tivoli Storage Manager APIs */
/**********************************************************************/
#ifndef _H_DSMRC
#define _H_DSMRC
#ifndef DSMAPILIB
#ifndef _H_ANSMACH
typedef int RetCode ;
#endif
#endif
#define DSM_RS_ABORT_FS_NOT_DEFINED 20
#define DSM_RS_ABORT_NODE_ALREADY_DEFED 21
#define DSM_RS_ABORT_NO_DEFAULT_DOMAIN 22
#define DSM_RS_ABORT_INVALID_NODENAME 23
#define DSM_RS_ABORT_INVALID_POL_BIND 24
#define DSM_RS_ABORT_DEST_NOT_DEFINED 25
#define DSM_RS_ABORT_WAIT_FOR_SPACE 26
#define DSM_RS_ABORT_NOT_AUTHORIZED 27
#define DSM_RS_ABORT_RULE_ALREADY_DEFED 28
#define DSM_RS_ABORT_NO_STOR_SPACE_STOP 29
#define DSM_RS_ABORT_LICENSE_VIOLATION 30
#define DSM_RS_ABORT_DATA_SKIPPED 40
#define DSM_RS_ABORT_EXCEED_MAX_MP 41
#define DSM_RS_ABORT_NO_OBJSET_MATCH 42
#define DSM_RS_ABORT_PVR_ERROR 43
#define DSM_RS_ABORT_BAD_RECOGTOKEN 44
#define DSM_RS_ABORT_MERGE_ERROR 45
#define DSM_RS_ABORT_FSRENAME_ERROR 46
#define DSM_RS_ABORT_INVALID_OPERATION 47
#define DSM_RS_ABORT_STGPOOL_UNDEFINED 48
#define DSM_RS_ABORT_INVALID_DATA_FORMAT 49
#define DSM_RS_ABORT_DATAMOVER_UNDEFINED 50
/* RETURN CODE */
/*---------------------------------------------------------------------------*/
/* Return codes 180-199 are reserved for Policy Set handling */
/*---------------------------------------------------------------------------*/
#define DSM_RC_PS_MULTBCG 181 /* Multiple backup copy groups in 1 MC*/
#define DSM_RC_PS_MULTACG 182 /* Multiple arch. copy groups in 1 MC*/
#define DSM_RC_PS_NODFLTMC 183 /* Default MC name not in policy set */
#define DSM_RC_TL_NOBCG 184 /* Backup req, no backup copy group */
#define DSM_RC_TL_EXCLUDED 185 /* Backup req, excl. by in/ex filter */
#define DSM_RC_TL_NOACG 186 /* Archive req, no archive copy group */
#define DSM_RC_PS_INVALID_ARCHMC 187 /* Invalid MC name in archive override*/
#define DSM_RC_NO_PS_DATA 188 /* No policy set data on the server */
#define DSM_RC_PS_INVALID_DIRMC 189 /* Invalid directory MC specified in
the options file. */
#define DSM_RC_PS_NO_CG_IN_DIR_MC 190 /* No backup copy group in directory MC.
Must specify an MC using DirMC
option. */
/*---------------------------------------------------------------------------*/
/* Return codes for the Trusted Communication Agent */
/*---------------------------------------------------------------------------*/
#define DSM_RC_TCA_NOT_ROOT 161 /* Access to TA is denied */
#define DSM_RC_TCA_ATTACH_SHR_MEM_ERR 200 /* Error attaching shared memory */
#define DSM_RC_TCA_SHR_MEM_BLOCK_ERR 200 /* Shared memory block error */
#define DSM_RC_TCA_SHR_MEM_IN_USE 200 /* Shared memory block error */
#define DSM_RC_TCA_SHARED_MEMORY_ERROR 200 /* Shared memory block error */
#define DSM_RC_TCA_SEGMENT_MISMATCH 200 /* Shared memory block error */
#define DSM_RC_TCA_FORK_FAILED 292 /* Error forking off TCA process */
#define DSM_RC_TCA_DIED 294 /* TCA died unexpectedly */
#define DSM_RC_TCA_INVALID_REQUEST 295 /* Invalid request sent to TCA */
#define DSM_RC_TCA_SEMGET_ERROR 297 /* Error getting semaphores */
#define DSM_RC_TCA_SEM_OP_ERROR 298 /* Error in semaphore set or wait */
#define DSM_RC_TCA_NOT_ALLOWED 299 /* TCA not allowed (multi thread) */
/*---------------------------------------------------------------------------*/
/* 400-430 for options */
/*---------------------------------------------------------------------------*/
#define DSM_RC_INVALID_OPT 400 /* invalid option */
#define DSM_RC_NO_HOST_ADDR 405 /* Not enuf info to connect server */
#define DSM_RC_NO_OPT_FILE 406 /* No default user configuration file*/
#define DSM_RC_MACHINE_SAME 408 /* -MACHINENAME same as real name */
#define DSM_RC_INVALID_SERVER 409 /* Invalid server name from client */
#define DSM_RC_INVALID_KEYWORD 410 /* Invalid option keyword */
#define DSM_RC_PATTERN_TOO_COMPLEX 411 /* Can’t match Include/Exclude entry*/
#define DSM_RC_NO_CLOSING_BRACKET 412 /* Missing closing bracket inc/excl */
#define DSM_RC_OPT_CLIENT_NOT_ACCEPTING 417/* Client doesn’t accept this option
from the server */
#define DSM_RC_OPT_CLIENT_DOES_NOT_WANT 418/* Client doesn’t want this value
from the server */
#define DSM_RC_OPT_NO_INCLEXCL_FILE 419 /* inclexcl file not found */
/*---------------------------------------------------------------------------*/
/* 600 to 610 for volume label codes */
/*---------------------------------------------------------------------------*/
#define DSM_RC_DUP_LABEL 600 /* duplicate volume label found */
#define DSM_RC_NO_LABEL 601 /* drive has no label */
/*---------------------------------------------------------------------------*/
/* Return codes for message file processing */
/*---------------------------------------------------------------------------*/
#define DSM_RC_NLS_CANT_OPEN_TXT 610 /* error trying to open msg txt file */
#define DSM_RC_NLS_CANT_READ_HDR 611 /* error trying to read header */
#define DSM_RC_NLS_INVALID_CNTL_REC 612 /* invalid control record */
#define DSM_RC_NLS_INVALID_DATE_FMT 613 /* invalid default date format */
#define DSM_RC_NLS_INVALID_TIME_FMT 614 /* invalid default time format */
#define DSM_RC_NLS_INVALID_NUM_FMT 615 /* invalid default number format */
/*---------------------------------------------------------------------------*/
/* Return codes 620-630 are reserved for log message return codes */
/*---------------------------------------------------------------------------*/
#define DSM_RC_LOG_CANT_BE_OPENED 620 /* error trying to open error log */
#define DSM_RC_LOG_ERROR_WRITING_TO_LOG 621 /* error occurred writing to
log file */
#define DSM_RC_LOG_NOT_SPECIFIED 622 /* no error log file was specified */
/*---------------------------------------------------------------------------*/
/* Return codes 900-999 TSM CLIENT ONLY */
/*---------------------------------------------------------------------------*/
#define DSM_RC_NOT_ADSM_AUTHORIZED 927 /* Must be ADSM authorized to perform*/
/* action : root user or pwd auth */
#define DSM_RC_REJECT_USERID_UNKNOWN 940 /* userid unknown on server */
#define DSM_RC_FILE_IS_SYMLINK 959 /* errorlog or trace is a symbolic
link
*/
/*---------------------------------------------------------------------------*/
/* Return codes (-71)-(-90) are reserved for CommTSM error codes */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Return codes -300 to -307 are reserved for IPX/SPX communications */
/*---------------------------------------------------------------------------*/
#define DSM_RC_TLI_ERROR 2021 /* no longer used */
#define DSM_RC_IPXSPX_FAILURE 2021 /* no longer used */
#define DSM_RC_TLI_DLL_MISSING 2021 /* no longer used */
#define DSM_RC_DLL_LOADFAILURE 2021 /* no longer used */
#define DSM_RC_DLL_FUNCTION_LOADFAILURE 2021 /* no longer used */
#define DSM_RC_IPXCONN_REFUSED 2021 /* no longer used */
#define DSM_RC_IPXCONN_TIMEDOUT 2021 /* no longer used */
#define DSM_RC_IPXADDR_UNREACHABLE 2021 /* no longer used */
/*=== return codes 2400 - 2410 used by lic file see agentrc.h ===*/
/*=== return codes 2410 - 2430 used by Oracle agent see agentrc.h ===*/
/*=============================================================================
Return codes (4600)-(4624) are reserved for clustering
=============================================================================*/
#define DSM_RC_CLUSTER_INFO_LIBRARY_NOT_LOADED 4600
#define DSM_RC_CLUSTER_LIBRARY_INVALID 4601
#define DSM_RC_CLUSTER_LIBRARY_NOT_LOADED 4602
#define DSM_RC_CLUSTER_NOT_MEMBER_OF_CLUSTER 4603
#define DSM_RC_CLUSTER_NOT_ENABLED 4604
#define DSM_RC_CLUSTER_NOT_SUPPORTED 4605
#define DSM_RC_CLUSTER_UNKNOWN_ERROR 4606
/*=============================================================================
Return codes (5200)-(5600) are reserved for new Server ABORT codes (dsmcomm.h)
=============================================================================*/
#define DSM_RS_ABORT_CERTIFICATE_NOT_FOUND 5200
/*=============================================================================
Return codes (5701)-(5749) are reserved for proxy
=============================================================================*/
#define DSM_RC_PROXY_REJECT_NO_RESOURCES 5702
#define DSM_RC_PROXY_REJECT_DUPLICATE_ID 5705
#define DSM_RC_PROXY_REJECT_ID_IN_USE 5710
#define DSM_RC_PROXY_REJECT_INTERNAL_ERROR 5717
#define DSM_RC_PROXY_REJECT_NOT_AUTHORIZED 5722
#define DSM_RC_PROXY_INVALID_FROMNODE 5746
#define DSM_RC_PROXY_INVALID_SERVERFREE 5747
#define DSM_RC_PROXY_INVALID_CLUSTER 5748
#define DSM_RC_PROXY_INVALID_FUNCTION 5749
/*=============================================================================
Return codes 5801 - 5849 are reserved for cryptography/security
=============================================================================*/
/*=============================================================================
Return codes 6300 - 6399 are reserved for client-side deduplication
=============================================================================*/
#define DSM_RC_DIGEST_VALIDATION_ERROR 6300 /* End-to-end digest validation err */
#define DSM_RC_DATA_FINGERPRINT_ERROR 6301 /* Failure in Rabin fingeprinting */
#define DSM_RC_DATA_DEDUP_ERROR 6302 /* Error converting data into chunks */
#endif /* _H_DSMRC */
Related reference:
API return codes
The second header file, dsmapips.h, provides an example of definitions that are
specific to a particular operating system; in this example, the Windows platform.
The third header file, release.h, includes the version and release information.
The information that is provided here contains a point-in-time copy of the files that
are distributed with the API. View the files in the API distribution package for the
latest version.
/***********************************************************************
* Tivoli Storage Manager *
* API Client Component *
* *
* (C) Copyright IBM Corporation 1993,2010 *
***********************************************************************/
/**************************************************************************
* Header File Name: dsmapitd.h
*
* Environment: ************************************************
* ** This is a platform-independent source file **
*
* ************************************************
*
* Design Notes: This file contains basic data types and constants
* includable by all client source files. The constants
* within this file should be set properly for the
* particular machine and operating system on which the
* client software is to be run.
*
* Platform specific definitions are included in dsmapips.h
*
* Descriptive-name: Definitions for Tivoli Storage manager API constants
*-------------------------------------------------------------------------*/
#ifndef _H_DSMAPITD
#define _H_DSMAPITD
#ifdef _MAC
/*=============================================================================
choices are:
http://developer.apple.com/documentation/DeveloperTools/Conceptual/PowerPCRuntime/Data/chapter_2_section_3.html
/*<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>*/
/* D E F I N E S */
/*<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>*/
/*-------------------------------------------------------------------------+
| API Version, Release, and Level to use in dsmApiVersion on dsmInit() |
+-------------------------------------------------------------------------*/
#define DSM_API_VERSION COMMON_VERSION
#define DSM_API_RELEASE COMMON_RELEASE
#define DSM_API_LEVEL COMMON_LEVEL
#define DSM_API_SUBLEVEL COMMON_SUBLEVEL
/*-------------------------------------------------------------------------+
| Maximum field lengths |
+-------------------------------------------------------------------------*/
#define DSM_MAX_CG_DEST_LENGTH 30 /* copy group destination */
#define DSM_MAX_CG_NAME_LENGTH 30 /* copy group name */
#define DSM_MAX_DESCR_LENGTH 255 /* archive description */
#define DSM_MAX_DOMAIN_LENGTH 30 /* policy domain name */
#define DSM_MAX_FSINFO_LENGTH 500 /* filespace info */
#define DSM_MAX_USER_FSINFO_LENGTH 480 /* max user filespace info*/
#define DSM_MAX_FSNAME_LENGTH 1024 /* filespace name */
#define DSM_MAX_FSTYPE_LENGTH 32 /* filespace type */
#define DSM_MAX_HL_LENGTH 1024 /* object high level name */
#define DSM_MAX_ID_LENGTH 64 /* session node name */
#define DSM_MAX_LL_LENGTH 256 /* object low level name */
#define DSM_MAX_MC_NAME_LENGTH 30 /* management class name */
#define DSM_MAX_OBJINFO_LENGTH 255 /* object info */
#define DSM_MAX_EXT_OBJINFO_LENGTH 1500 /* Extended object info */
#define DSM_MAX_OWNER_LENGTH 64 /* object owner name */
#define DSM_MAX_PLATFORM_LENGTH 16 /* application type */
#define DSM_MAX_PS_NAME_LENGTH 30 /* policy set name */
#define DSM_MAX_SERVERTYPE_LENGTH 32 /* server platform type */
#define DSM_MAX_VERIFIER_LENGTH 64 /* password */
#define DSM_PATH_MAX 1024 /* API config file path */
#define DSM_NAME_MAX 255 /* API config file name */
#define DSM_MAX_NODE_LENGTH 64 /* node/machine name */
#define DSM_MAX_RC_MSG_LENGTH 1024 /* msg parm for dsmRCMsg */
#define DSM_MAX_SERVER_ADDRESS 1024 /* server address */
/*-------------------------------------------------------------------------+
| Minimum field lengths |
+-------------------------------------------------------------------------*/
#define DSM_MIN_COMPRESS_SIZE 2048 /* minimum number of bytes an object */
/* needs before compression is allowed*/
/*-------------------------------------------------------------------------+
| Values for mtFlag in dsmSetup call |
+-------------------------------------------------------------------------*/
#define DSM_MULTITHREAD bTrue
#define DSM_SINGLETHREAD bFalse
/*-------------------------------------------------------------------------+
| Values for object type in dsmObjName structure |
| Note: These values must be kept in sync with dsmcomm.h |
+-------------------------------------------------------------------------*/
#define DSM_OBJ_FILE 0x01 /*object has attrib info & data*/
#define DSM_OBJ_DIRECTORY 0x02 /*obj has only attribute info */
#define DSM_OBJ_RESERVED1 0x04 /* for future use */
#define DSM_OBJ_RESERVED2 0x05 /* for future use */
#define DSM_OBJ_RESERVED3 0x06 /* for future use */
#define DSM_OBJ_WILDCARD 0xFE /* Any object type */
#define DSM_OBJ_ANY_TYPE 0xFF /* for future use */
/*---------------------------------------------------------------------+
| Definitions for "group type" field in tsmGrouphandlerIn_t |
+---------------------------------------------------------------------*/
/*---------------------------------------------------------------------+
| Definitions for "member type" field in tsmGrouphandlerIn_t |
+---------------------------------------------------------------------*/
/*---------------------------------------------------------------------+
| Definitions for "operation type" field in tsmGrouphandlerIn_t |
+---------------------------------------------------------------------*/
#define DSM_GROUP_ACTION_BEGIN 0x01
#define DSM_GROUP_ACTION_OPEN 0x02 /* create new group */
#define DSM_GROUP_ACTION_CLOSE 0x03 /* commit and save an open group */
#define DSM_GROUP_ACTION_ADD 0x04 /* Append to a group */
#define DSM_GROUP_ACTION_ASSIGNTO 0x05 /* Assign to a another group */
#define DSM_GROUP_ACTION_REMOVE 0x06 /* remove a member from a group */
/*-------------------------------------------------------------------------+
| Values for copySer in DetailCG structures for Query Mgmt Class response |
+-------------------------------------------------------------------------*/
#define Copy_Serial_Static 1 /*Copy Serialization Static */
#define Copy_Serial_Shared_Static 2 /*Copy Serialization Shared Static*/
#define Copy_Serial_Shared_Dynamic 3 /*Copy Serialization Shared Dynamic*/
#define Copy_Serial_Dynamic 4 /*Copy Serialization Dynamic */
/*-------------------------------------------------------------------------+
| Values for copyMode in DetailCG structures for Query Mgmt Class response |
+-------------------------------------------------------------------------*/
#define Copy_Mode_Modified 1 /*Copy Mode Modified */
#define Copy_Mode_Absolute 2 /*Copy Mode Absolute */
/*-------------------------------------------------------------------------+
| Values for objState in qryBackupData structure |
+-------------------------------------------------------------------------*/
#define DSM_ACTIVE 0x01 /* query only active objects */
#define DSM_INACTIVE 0x02 /* query only inactive objects */
#define DSM_ANY_MATCH 0xFF /* query all backup objects */
/*-------------------------------------------------------------------------+
| Boundary values for dsmDate.year field in qryArchiveData structure |
+-------------------------------------------------------------------------*/
#define DATE_MINUS_INFINITE 0x0000 /* lowest boundary */
#define DATE_PLUS_INFINITE 0xFFFF /* highest upper boundary */
/*-------------------------------------------------------------------------+
| Bits masks for update action parameter on dsmUpdateFS() |
+-------------------------------------------------------------------------*/
#define DSM_FSUPD_FSTYPE ((unsigned) 0x00000002)
#define DSM_FSUPD_FSINFO ((unsigned) 0x00000004)
#define DSM_FSUPD_BACKSTARTDATE ((unsigned) 0x00000008)
#define DSM_FSUPD_BACKCOMPLETEDATE ((unsigned) 0x00000010)
#define DSM_FSUPD_OCCUPANCY ((unsigned) 0x00000020)
#define DSM_FSUPD_CAPACITY ((unsigned) 0x00000040)
/*-------------------------------------------------------------------------+
| Bits mask for backup update action parameter on dsmUpdateObj() |
+-------------------------------------------------------------------------*/
#define DSM_BACKUPD_OWNER ((unsigned) 0x00000001)
#define DSM_BACKUPD_OBJINFO ((unsigned) 0x00000002)
#define DSM_BACKUPD_MC ((unsigned) 0x00000004)
/*-------------------------------------------------------------------------+
| Values for repository parameter on dsmDeleteFS() |
+-------------------------------------------------------------------------*/
#define DSM_ARCHIVE_REP 0x0A /* archive repository */
#define DSM_BACKUP_REP 0x0B /* backup repository */
#define DSM_REPOS_ALL 0x01 /* all respository types */
/*-------------------------------------------------------------------------+
| Values for vote parameter on dsmEndTxn() |
+-------------------------------------------------------------------------*/
#define DSM_VOTE_COMMIT 1 /* commit current transaction */
#define DSM_VOTE_ABORT 2 /* roll back current transaction */
/*-------------------------------------------------------------------------+
| Values for various flags returned in ApiSessInfo structure. |
+-------------------------------------------------------------------------*/
/* Client compression field codes */
#define COMPRESS_YES 1 /* client must compress data */
#define COMPRESS_NO 2 /* client must NOT compress data */
#define COMPRESS_CD 3 /* client determined */
/*-------------------------------------------------------------------------+
Values for various flags returned in optStruct structure. |
-------------------------------------------------------------------------*/
#define DSM_PASSWD_GENERATE 1
#define DSM_PASSWD_PROMPT 0
/* obsolete commmethods */
#define DSM_COMM_PVM_IUCV 12
#define DSM_COMM_3270 12
#define DSM_COMM_IUCV 12
#define DSM_COMM_PWSCS 12
#define DSM_COMM_SNA_LU6_2 12
#define DSM_COMM_IPXSPX 12 /* For IPX/SPX support */
#define DSM_COMM_NETBIOS 12 /* NETBIOS */
#define DSM_COMM_400COMM 12
#define DSM_COMM_CLIO 12 /* CLIO/S */
/*-------------------------------------------------------------------------+
| Values for userNameAuthorities in dsmInitEx for future use |
+-------------------------------------------------------------------------*/
#define DSM_USERAUTH_NONE ((dsInt16_t)0x0000)
#define DSM_USERAUTH_ACCESS ((dsInt16_t)0x0001)
#define DSM_USERAUTH_OWNER ((dsInt16_t)0x0002)
#define DSM_USERAUTH_POLICY ((dsInt16_t)0x0004)
/*-------------------------------------------------------------------------+
| Values for encryptionType on dsmEndSendObjEx, queryResp |
+-------------------------------------------------------------------------*/
#define DSM_ENCRYPT_NO ((dsUint8_t)0x00)
#define DSM_ENCRYPT_USER ((dsUint8_t)0x01)
#define DSM_ENCRYPT_CLIENTENCRKEY ((dsUint8_t)0x02)
#define DSM_ENCRYPT_DES_56BIT ((dsUint8_t)0x04)
#define DSM_ENCRYPT_AES_128BIT ((dsUint8_t)0x08)
#define DSM_ENCRYPT_AES_256BIT ((dsUint8_t)0x10)
/*---------------------------------------------------------------------+
| Definitions for mediaClass field. |
+---------------------------------------------------------------------*/
/*
* The following constants define a hierarchy of media access classes.
* Lower numbers indicate media which can supply faster access to data.
*/
/* future use */
#define MEDIA_NETWORK 0x30
/* future use */
#define MEDIA_SHELF 0x40
/* future use */
#define MEDIA_OFFSITE 0x50
/* future use */
#define MEDIA_UNAVAILABLE 0xF0
/*-------------------------------------------------------------------------+
| Type definition for partial object data for dsmBeginGetData() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion; /* Structure version */
dsStruct64_t partialObjOffset; /* offset into object to begin reading */
dsStruct64_t partialObjLength; /* amount of object to read */
} PartialObjData ; /* partial object data */
#define PartialObjDataVersion 1 /* */
/*-------------------------------------------------------------------------+
| Type definition for date structure |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t year; /* year, 16-bit integer (e.g., 1990) */
dsUint8_t month; /* month, 8-bit integer (1 - 12) */
dsUint8_t day; /* day. 8-bit integer (1 - 31) */
dsUint8_t hour; /* hour, 8-bit integer (0 - 23) */
dsUint8_t minute; /* minute, 8-bit integer (0 - 59) */
dsUint8_t second; /* second, b-bit integer (0 - 59) */
}dsmDate ;
/*-------------------------------------------------------------------------+
| Type definition for Object ID on dsmGetObj() and in dsmGetList structure|
+-------------------------------------------------------------------------*/
typedef dsStruct64_t ObjID ;
/*-------------------------------------------------------------------------+
| Type definition for dsmGetType parameter on dsmBeginGetData() |
+-------------------------------------------------------------------------*/
typedef enum
{
gtBackup = 0x00, /* Backup processing type */
gtArchive /* Archive processing type */
} dsmGetType ;
/*-------------------------------------------------------------------------+
| Type definition for dsmQueryType parameter on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef enum
{
qtArchive = 0x00, /* Archive query type */
qtBackup, /* Backup query type */
qtBackupActive, /* Fast query for active backup files */
qtFilespace, /* Filespace query type */
qtMC, /* Mgmt. class query type */
qtReserved1, /* future use */
qtReserved2, /* future use */
qtReserved3, /* future use */
qtReserved4, /* future use */
qtBackupGroups, /* group leaders in a specific fs */
qtOpenGroups, /* Open groups in a specific fs */
qtReserved5, /* future use */
qtProxyNodeAuth, /* nodes that his node can proxy to */
qtProxyNodePeer, /* Peer nodes with the same target */
qtReserved6, /* future use */
qtReserved7, /* future use */
qtReserved8 /* future use */
}dsmQueryType ;
/*-------------------------------------------------------------------------+
| Type definition sendType parameter on dsmBindMC() and dsmSendObj() |
+-------------------------------------------------------------------------*/
typedef enum
{
stBackup = 0x00, /* Backup processing type */
stArchive, /* Archive processing type */
stBackupMountWait, /* Backup processing with mountwait on */
stArchiveMountWait /* Archive processing with mountwait on */
}dsmSendType ;
/*-------------------------------------------------------------------------+
| Type definition for delType parameter on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef enum
{
dtArchive = 0x00, /* Archive delete type */
dtBackup, /* Backup delete (deactivate) type */
dtBackupID /* Backup delete (remove) type */
}dsmDelType ;
/*-------------------------------------------------------------------------+
| Type definition sendType parameter on dsmSetAccess() |
+-------------------------------------------------------------------------*/
typedef enum
{
atBackup = 0x00, /* Backup processing type */
atArchive /* Archive processing type */
}dsmAccessType;
/*-------------------------------------------------------------------------+
/*-------------------------------------------------------------------------+
| Type definition for API Version on dsmInit() and dsmQueryApiVersion() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion; /* Structure version */
dsUint16_t version; /* API version */
dsUint16_t release; /* API release */
dsUint16_t level; /* API level */
dsUint16_t subLevel; /* API sub level */
dsmBool_t unicode; /* API unicode? */
}dsmApiVersionEx;
#define apiVersionExVer 2
/*-------------------------------------------------------------------------+
| Type definition for Application Version on dsmInit() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion; /* Structure version */
dsUint16_t applicationVersion; /* application version number */
dsUint16_t applicationRelease; /* application release number */
dsUint16_t applicationLevel; /* application level number */
dsUint16_t applicationSubLevel; /* application sub level number */
} dsmAppVersion;
#define appVersionVer 1
/*-------------------------------------------------------------------------+
| Type definition for object name used on BindMC, Send, Delete, Query |
+-------------------------------------------------------------------------*/
typedef struct S_dsmObjName
{
char fs[DSM_MAX_FSNAME_LENGTH + 1] ; /* Filespace name */
char hl[DSM_MAX_HL_LENGTH + 1] ; /* High level name */
char ll[DSM_MAX_LL_LENGTH + 1] ; /* Low level name */
dsUint8_t objType; /* for object type values, see defines above */
}dsmObjName;
/*-------------------------------------------------------------------------+
| Type definition for Backup delete info on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
dsmObjName *objNameP ; /* object name */
dsUint32_t copyGroup ; /* copy group */
}delBack ;
#define delBackVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Archive delete info on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
dsStruct64_t objId ; /* object ID */
#define delArchVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Backup ID delete info on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
dsStruct64_t objId ; /* object ID */
}delBackID;
#define delBackIDVersion 1
/*-------------------------------------------------------------------------+
| Type definition for delete info on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef union
{
delBack backInfo ;
delArch archInfo ;
delBackID backIDInfo ;
}dsmDelInfo ;
/*-------------------------------------------------------------------------+
| Type definition for Object Attribute parameter on dsmSendObj() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion; /* Structure version */
char owner[DSM_MAX_OWNER_LENGTH + 1]; /* object owner */
dsStruct64_t sizeEstimate; /* Size estimate in bytes of the object */
dsmBool_t objCompressed; /* Is object already compressed? */
dsUint16_t objInfoLength; /* length of object-dependent info */
char *objInfo; /* object-dependent info */
char *mcNameP; /* mgmnt class name for override */
dsmBool_t disableDeduplication; /* force no dedup for this object */
dsmBool_t useExtObjInfo; /* use ext obj info up to 1536 */
}ObjAttr;
#define ObjAttrVersion 4
/*-------------------------------------------------------------------------+
| Type definition for mcBindKey returned on dsmBindMC() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion; /* structure version */
char mcName[DSM_MAX_MC_NAME_LENGTH + 1];
/* Name of mc bound to object. */
dsmBool_t backup_cg_exists; /* True/false */
dsmBool_t archive_cg_exists; /* True/false */
char backup_copy_dest[DSM_MAX_CG_DEST_LENGTH + 1];
/* Backup copy dest. name */
char archive_copy_dest[DSM_MAX_CG_DEST_LENGTH + 1];
/* Arch copy dest.name */
}mcBindKey;
#define mcBindKeyVersion 1
/*-------------------------------------------------------------------------+
| Type definition for object list on dsmBeginGetData() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
/*-------------------------------------------------------------------------+
| Type definition for DataBlk used to Get or Send data |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
dsUint32_t bufferLen; /* Length of buffer passed below */
dsUint32_t numBytes; /* Actual number of bytes read from */
/* or written to the buffer */
char *bufferPtr; /* Data buffer */
dsUint32_t numBytesCompressed; /* on send actual bytes compressed */
dsUint16_t reserved; /* for future use */
}DataBlk;
#define DataBlkVersion 3
/*-------------------------------------------------------------------------+
| Type definition for Mgmt Class queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct S_qryMCData
{
dsUint16_t stVersion; /* structure version */
char *mcName; /* Mgmt class name */
/* single name to get one or empty string to get all*/
dsmBool_t mcDetail; /* Want details or not? */
}qryMCData;
#define qryMCDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Archive Copy Group details on Query MC response |
+-------------------------------------------------------------------------*/
typedef struct S_archDetailCG
{
char cgName[DSM_MAX_CG_NAME_LENGTH + 1]; /* Copy group name */
dsUint16_t frequency; /* Copy (archive) frequency */
dsUint16_t retainVers; /* Retain version */
dsUint8_t copySer; /* for copy serialization values, see defines */
dsUint8_t copyMode; /* for copy mode values, see defines above */
char destName[DSM_MAX_CG_DEST_LENGTH + 1]; /* Copy dest name */
dsmBool_t bLanFreeDest; /* Destination has lan free path? */
dsmBool_t reserved; /* Not currently used */
dsUint8_t retainInit; /* possible values see above */
dsUint16_t retainMin; /* if retInit is EVENT num of days */
dsmBool_t bDeduplicate; /* destination has dedup enabled */
}archDetailCG;
/*-------------------------------------------------------------------------+
| Type definition for Backup Copy Group details on Query MC response |
+-------------------------------------------------------------------------*/
typedef struct S_backupDetailCG
{
char cgName[DSM_MAX_CG_NAME_LENGTH + 1]; /* Copy group name */
dsUint16_t frequency; /* Backup frequency */
dsUint16_t verDataExst; /* Versions data exists */
dsUint16_t verDataDltd; /* Versions data deleted */
dsUint16_t retXtraVers; /* Retain extra versions */
/*-------------------------------------------------------------------------+
| Type definition for Query Mgmt Class detail response on dsmGetNextQObj()|
+-------------------------------------------------------------------------*/
typedef struct S_qryRespMCDetailData
{
dsUint16_t stVersion; /* structure version */
char mcName[DSM_MAX_MC_NAME_LENGTH + 1]; /* mc name */
char mcDesc[DSM_MAX_MC_DESCR_LENGTH + 1]; /*mc description */
archDetailCG archDet; /* Archive copy group detail */
backupDetailCG backupDet; /* Backup copy group detail */
}qryRespMCDetailData;
#define qryRespMCDetailDataVersion 4
/*-------------------------------------------------------------------------+
| Type definition for Query Mgmt Class summary response on dsmGetNextQObj()|
+-------------------------------------------------------------------------*/
typedef struct S_qryRespMCData
{
dsUint16_t stVersion; /* structure version */
char mcName[DSM_MAX_MC_NAME_LENGTH + 1]; /* mc name */
char mcDesc[DSM_MAX_MC_DESCR_LENGTH + 1]; /* mc description */
}qryRespMCData;
#define qryRespMCDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Archive queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct S_qryArchiveData
{
dsUint16_t stVersion; /* structure version */
dsmObjName *objName; /* Full dsm name of object */
char *owner; /* owner name */
/* for maximum date boundaries, see defines above */
dsmDate insDateLowerBound; /* low bound archive insert date */
dsmDate insDateUpperBound; /* hi bound archive insert date */
dsmDate expDateLowerBound; /* low bound expiration date */
dsmDate expDateUpperBound; /* hi bound expiration date */
char *descr; /* archive description */
} qryArchiveData;
#define qryArchiveDataVersion 1
/*-------------------------------------------------------------------------+
#define qryRespArchiveDataVersion 7
/*-------------------------------------------------------------------------+
| Type definition for Archive sendBuff parameter on dsmSendObj() |
+-------------------------------------------------------------------------*/
typedef struct S_sndArchiveData
{
dsUint16_t stVersion; /* structure version */
char *descr; /* archive description */
}sndArchiveData;
#define sndArchiveDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Backup queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct S_qryBackupData
{
dsUint16_t stVersion; /* structure version */
dsmObjName *objName; /* full dsm name of object */
char *owner; /* owner name */
dsUint8_t objState; /* object state selector */
dsmDate pitDate; /* Date value for point in time restore */
/* for possible values, see defines above */
}qryBackupData;
#define qryBackupDataVersion 2
typedef struct
{
dsUint8_t reserved1;
dsStruct64_t reserved2;
} reservedInfo_t; /* for future use */
/*-------------------------------------------------------------------------+
| Type definition for Query Backup response on dsmGetNextQObj() |
+-------------------------------------------------------------------------*/
typedef struct S_qryRespBackupData
{
dsUint16_t stVersion; /* structure version */
dsmObjName objName; /* full dsm name of object */
dsUint32_t copyGroup; /* copy group number */
#define qryRespBackupDataVersion 8
/*-------------------------------------------------------------------------+
| Type definition for Active Backup queryBuffer on dsmBeginQuery()
|
| Notes: For the active backup query, only the fs (filespace) and objType
| fields of objName need be set. objType can only be set to
| DSM_OBJ_FILE or DSM_OBJ_DIRECTORY. DSM_OBJ_ANY_TYPE will not
| find a match on the query.
+-------------------------------------------------------------------------*/
typedef struct S_qryABackupData
{
dsUint16_t stVersion; /* structure version */
dsmObjName *objName; /* Only fs and objtype used */
}qryABackupData;
#define qryABackupDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Query Active Backup response on dsmGetNextQObj() |
+-------------------------------------------------------------------------*/
typedef struct S_qryARespBackupData
{
dsUint16_t stVersion; /* structure version */
dsmObjName objName; /* full dsm name of object */
dsUint32_t copyGroup; /* copy group number */
char mcName[DSM_MAX_MC_NAME_LENGTH + 1];/*management class name*/
char owner[DSM_MAX_OWNER_LENGTH + 1]; /* owner name */
dsmDate insDate; /* backup insertion date */
dsUint16_t objInfolen; /* length of object-dependent info*/
char reservedObjInfo[DSM_MAX_OBJINFO_LENGTH]; /*object-dependent info */
char objInfo[DSM_MAX_EXT_OBJINFO_LENGTH]; /*object-dependent info */
}qryARespBackupData;
#define qryARespBackupDataVersion 2
/*-------------------------------------------------------------------------+
| Type definition for Backup queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct qryBackupGroups
#define qryBackupGroupsVersion 3
/*-------------------------------------------------------------------------+
| Type definition for proxynode queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct qryProxyNodeData
{
dsUint16_t stVersion; /* structure version */
char *targetNodeName; /* target node name */
}qryProxyNodeData;
#define qryProxyNodeDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for qryRespProxyNodeData parameter used on dsmGetNextQObj()|
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
char targetNodeName[DSM_MAX_ID_LENGTH+1]; /* target node name */
char peerNodeName[DSM_MAX_ID_LENGTH+1]; /* Peer node name */
char hlAddress[DSM_MAX_ID_LENGTH+1]; /* peer hlAddress */
char llAddress[DSM_MAX_ID_LENGTH+1]; /* peer hlAddress */
}qryRespProxyNodeData;
#define qryRespProxyNodeDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for WINNT and OS/2 Filespace attributes |
+-------------------------------------------------------------------------*/
typedef struct
{
char driveLetter ; /* drive letter for filespace */
dsUint16_t fsInfoLength; /* fsInfo length used */
char fsInfo[DSM_MAX_FSINFO_LENGTH];/*caller-determined data */
}dsmDosFSAttrib ;
/*-------------------------------------------------------------------------+
| Type definition for UNIX Filespace attributes |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t fsInfoLength; /* fsInfo length used */
char fsInfo[DSM_MAX_FSINFO_LENGTH];/*caller-determined data */
}dsmUnixFSAttrib ;
/*-------------------------------------------------------------------------+
| Type definition for NetWare Filespace attributes |
+-------------------------------------------------------------------------*/
typedef dsmUnixFSAttrib dsmNetwareFSAttrib;
/*-------------------------------------------------------------------------+
| Type definition for Filespace attributes on all Filespace calls |
+-------------------------------------------------------------------------*/
typedef union
/*-------------------------------------------------------------------------+
| Type definition for fsUpd parameter on dsmUpdateFS()
+-------------------------------------------------------------------------*/
typedef struct S_dsmFSUpd
{
dsUint16_t stVersion ; /* structure version */
char *fsType ; /* filespace type */
dsStruct64_t occupancy ; /* occupancy estimate */
dsStruct64_t capacity ; /* capacity estimate */
dsmFSAttr fsAttr ; /* platform specific attributes */
}dsmFSUpd ;
#define dsmFSUpdVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Filespace queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct S_qryFSData
{
dsUint16_t stVersion; /* structure version */
char *fsName; /* File space name */
}qryFSData;
#define qryFSDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Query Filespace response on dsmGetNextQObj() |
+-------------------------------------------------------------------------*/
typedef struct S_qryRespFSData
{
dsUint16_t stVersion; /* structure version */
char fsName[DSM_MAX_FSNAME_LENGTH + 1]; /* Filespace name */
char fsType[DSM_MAX_FSTYPE_LENGTH + 1] ; /* Filespace type */
dsStruct64_t occupancy; /* Occupancy est. in bytes.*/
dsStruct64_t capacity; /* Capacity est. in bytes. */
dsmFSAttr fsAttr ; /* platform specific attributes */
dsmDate backStartDate; /* start backup date */
dsmDate backCompleteDate; /* end backup Date */
dsmDate reserved1; /* For future use */
dsmDate lastReplStartDate; /* The last time replication was started */
dsmDate lastReplCmpltDate; /* The last time replication completed */
/* (could have had a failure, */
/* but it still completes) */
dsmDate lastBackOpDateFromServer; /* The last store time stamp the client */
/* saved on the server */
dsmDate lastArchOpDateFromServer; /* The last store time stamp the client */
/* saved on the server */
dsmDate lastSpMgOpDateFromServer; /* The last store time stamp the client */
/* saved on the server */
dsmDate lastBackOpDateFromLocal; /* The last store time stamp the client */
/* saved on the Local */
dsmDate lastArchOpDateFromLocal; /* The last store time stamp the client */
/* saved on the Local */
dsmDate lastSpMgOpDateFromLocal; /* The last store time stamp the client */
/* saved on the Local */
dsInt32_t failOverWriteDelay; /* Minutes for client to wait before allowed */
/* to store to this Repl srvr, Specail codes: */
/* NO_ACCESS(-1), ACCESS_RDONLY (-2) */
}qryRespFSData;
#define qryRespFSDataVersion 4
/*-------------------------------------------------------------------------+
| Type definition for regFilespace parameter on dsmRegisterFS()
#define regFSDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dedupType used in apisessInfo |
+-------------------------------------------------------------------------*/
typedef enum
{
dedupServerOnly= 0x00, /* dedup only done on server */
dedupClientOrServer /* dedup can be done on client or server */
}dsmDedupType ;
/*-------------------------------------------------------------------------+
| Type definition for fail over configuration and status
-------------------------------------------------------------------------*/
typedef enum
{
failOvrNotConfigured = 0x00,
failOvrConfigured,
failOvrConnectedToReplServer
}dsmFailOvrCfgType ;
/*-------------------------------------------------------------------------+
| Type definition for session info response on dsmQuerySessionInfo() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion; /* Structure version */
/*------------------------------------------------------------------*/
/* Server information */
/*------------------------------------------------------------------*/
char serverHost[DSM_MAX_SERVERNAME_LENGTH+1];
/* Network host name of DSM server */
dsUint16_t serverPort; /* Server comm port on host */
dsmDate serverDate; /* Server’s date/time */
char serverType[DSM_MAX_SERVERTYPE_LENGTH+1];
/* Server’s execution platform */
dsUint16_t serverVer; /* Server’s version number */
dsUint16_t serverRel; /* Server’s release number */
dsUint16_t serverLev; /* Server’s level number */
dsUint16_t serverSubLev; /* Server’s sublevel number */
/*------------------------------------------------------------------*/
/* Client Defaults */
/*------------------------------------------------------------------*/
char nodeType[DSM_MAX_PLATFORM_LENGTH+1]; /*node/application type*/
char fsdelim; /* File space delimiter */
char hldelim; /* Delimiter betw highlev & lowlev */
dsUint8_t compression; /* Compression flag */
dsUint8_t archDel; /* Archive delete permission */
dsUint8_t backDel; /* Backup delete permission */
dsUint32_t maxBytesPerTxn; /* for future use */
dsUint16_t maxObjPerTxn; /* The max objects allowed in a txn */
/*------------------------------------------------------------------*/
/* Session Information */
/*------------------------------------------------------------------*/
char id[DSM_MAX_ID_LENGTH+1]; /* Sign-in id node name */
char owner[DSM_MAX_OWNER_LENGTH+1]; /* Sign-in owner */
/* (for multi-user platforms) */
char confFile[DSM_PATH_MAX + DSM_NAME_MAX +1];
/* len is platform dep */
/*------------------------------------------------------------------*/
/* Replication and fail over information */
/*------------------------------------------------------------------*/
dsmFailOvrCfgType failOverCfgType; /* status of fail over */
char replServerName[DSM_MAX_SERVERNAME_LENGTH+1]; /* repl server name */
char homeServerName[DSM_MAX_SERVERNAME_LENGTH+1]; /* home server name */
char replServerHost[DSM_MAX_SERVERNAME_LENGTH+1]; /* Network host name of DSM server */
dsInt32_t replServerPort; /* Server comm port on host */
}ApiSessInfo;
#define ApiSessInfoVersion 6
/*-------------------------------------------------------------------------+
| Type definition for Query options response on dsmQueryCliOptions() |
| and dsmQuerySessOptions() |
+-------------------------------------------------------------------------*/
typedef struct
{
char dsmiDir[DSM_PATH_MAX + DSM_NAME_MAX +1];
char dsmiConfig[DSM_PATH_MAX + DSM_NAME_MAX +1];
char serverName[DSM_MAX_SERVERNAME_LENGTH+1];
dsInt16_t commMethod;
char serverAddress[DSM_MAX_SERVER_ADDRESS];
char nodeName[DSM_MAX_NODE_LENGTH+1];
dsmBool_t compression;
dsmBool_t compressalways;
dsmBool_t passwordAccess;
}optStruct ;
/*-------------------------------------------------------------------------+
| Type definition for LogType used in logInfo |
+-------------------------------------------------------------------------*/
typedef enum
{
logServer = 0x00, /* log msg only to server */
logLocal, /* log msg only to local error log */
logBoth, /* log msg to server and to local error log */
logNone
}dsmLogType ;
/*-------------------------------------------------------------------------+
| Type definition for logInfo parameter used on dsmLogEvent() |
+-------------------------------------------------------------------------*/
typedef struct
{
char *message; /* text of message to be logged */
/*-------------------------------------------------------------------------+
| Type definition for qryRespAccessData parameter used on dsmQueryAccess()|
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
char node[DSM_MAX_ID_LENGTH+1]; /* node name */
char owner[DSM_MAX_OWNER_LENGTH+1]; /* owner */
dsmObjName objName ; /* object name */
dsmAccessType accessType; /* archive or backup */
dsUint32_t ruleNumber ; /* Access rule id */
}qryRespAccessData;
#define qryRespAccessDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for envSetUp parameter on dsmSetUp()
+-------------------------------------------------------------------------*/
typedef struct S_envSetUp
{
dsUint16_t stVersion; /* structure version */
char dsmiDir[DSM_PATH_MAX + DSM_NAME_MAX +1];
char dsmiConfig[DSM_PATH_MAX + DSM_NAME_MAX +1];
char dsmiLog[DSM_PATH_MAX + DSM_NAME_MAX +1];
char **argv; /* for executables name argv[0] */
char logName[DSM_NAME_MAX +1];
dsmBool_t reserved1; /* for future use */
dsmBool_t reserved2; /* for future use */
}envSetUp;
#define envSetUpVersion 4
/*-------------------------------------------------------------------------+
| Type definition for dsmInitExIn_t
+-------------------------------------------------------------------------*/
typedef struct dsmInitExIn_t
{
dsUint16_t stVersion; /* structure version */
dsmApiVersionEx *apiVersionExP;
char *clientNodeNameP;
char *clientOwnerNameP;
char *clientPasswordP;
char *userNameP;
char *userPasswordP;
char *applicationTypeP;
char *configfile;
char *options;
char dirDelimiter;
dsmBool_t useUnicode;
dsmBool_t bCrossPlatform;
dsmBool_t bService;
dsmBool_t bEncryptKeyEnabled;
char *encryptionPasswordP;
dsmBool_t useTsmBuffers;
dsUint8_t numTsmBuffers;
dsmAppVersion *appVersionP;
}dsmInitExIn_t;
#define dsmInitExInVersion 5
/*-------------------------------------------------------------------------+
| Type definition for dsmInitExOut_t
+-------------------------------------------------------------------------*/
typedef struct dsmInitExOut_t
{
dsUint16_t stVersion; /* structure version */
}dsmInitExOut_t;
#define dsmInitExOutVersion 3
/*-------------------------------------------------------------------------+
| Type definition for LogType used in logInfo |
+-------------------------------------------------------------------------*/
typedef enum
{
logSevInfo = 0x00, /* information ANE4991 */
logSevWarning, /* warning ANE4992 */
logSevError, /* Error ANE4993 */
logSevSevere, /* severe ANE4994 */
logSevLicense, /* License ANE4995 */
logSevTryBuy /* try Buy ANE4996 */
}dsmLogSeverity ;
/*-------------------------------------------------------------------------+
| Type definition for dsmLogExIn_t
+-------------------------------------------------------------------------*/
typedef struct dsmLogExIn_t
{
dsUint16_t stVersion; /* structure version */
dsmLogSeverity severity;
char appMsgID[8];
dsmLogType logType; /* log type : local, server, both */
char *message; /* text of message to be logged */
char appName[DSM_MAX_PLATFORM_LENGTH];
char osPlatform[DSM_MAX_PLATFORM_LENGTH];
char appVersion[DSM_MAX_PLATFORM_LENGTH];
}dsmLogExIn_t;
#define dsmLogExInVersion 2
/*-------------------------------------------------------------------------+
| Type definition for dsmlogExOut_t
+-------------------------------------------------------------------------*/
typedef struct dsmLogExOut_t
{
dsUint16_t stVersion; /* structure version */
}dsmLogExOut_t;
#define dsmLogExOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmRenameIn_t
+-------------------------------------------------------------------------*/
typedef struct dsmRenameIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* handle for session */
dsUint8_t repository; /* Backup or Archive */
dsmObjName *objNameP ; /* object name */
char newHl[DSM_MAX_HL_LENGTH + 1]; /* new High level name */
char newLl[DSM_MAX_LL_LENGTH + 1]; /* new Low level name */
dsmBool_t merge; /* merge into existing name*/
ObjID objId; /* objId for Archive */
#define dsmRenameInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmRenameOut_t
+-------------------------------------------------------------------------*/
typedef struct dsmRenameOut_t
{
dsUint16_t stVersion; /* structure version */
}dsmRenameOut_t;
#define dsmRenameOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmEndSendObjExIn_t
+-------------------------------------------------------------------------*/
typedef struct dsmEndSendObjExIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* handle for session */
}dsmEndSendObjExIn_t;
#define dsmEndSendObjExInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmEndSendObjExOut_t
+-------------------------------------------------------------------------*/
typedef struct dsmEndSendObjExOut_t
{
dsUint16_t stVersion; /* structure version */
dsStruct64_t totalBytesSent; /* total bytes read from app */
dsmBool_t objCompressed; /* was object compressed */
dsStruct64_t totalCompressSize; /* total size after compress */
dsStruct64_t totalLFBytesSent; /* total bytes sent Lan Free */
dsUint8_t encryptionType; /* type of encryption used */
dsmBool_t objDeduplicated; /* was object processed for dist. data dedup */
dsStruct64_t totalDedupSize; /* total size after de-dup */
}dsmEndSendObjExOut_t;
#define dsmEndSendObjExOutVersion 3
/*-------------------------------------------------------------------------+
| Type definition for dsmGroupHandlerIn_t
+-------------------------------------------------------------------------*/
typedef struct dsmGroupHandlerIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* handle for session */
dsUint8_t groupType; /* Type of group */
dsUint8_t actionType; /* Type of group operation */
dsUint8_t memberType; /* Type of member: Leader or member */
dsStruct64_t leaderObjId; /* OBJID of the groupleader when manipulating a member */
char *uniqueGroupTagP; /* Unique group identifier */
dsmObjName *objNameP ; /* group leader object name */
dsmGetList memberObjList; /* list of objects to remove, assign */
}dsmGroupHandlerIn_t;
#define dsmGroupHandlerInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmGroupHandlerExOut_t
+-------------------------------------------------------------------------*/
typedef struct dsmGroupHandlerOut_t
{
dsUint16_t stVersion; /* structure version */
}dsmGroupHandlerOut_t;
#define dsmGroupHandlerOutVersion 1
/*-------------------------------------------------------------------------+
#define dsmEndTxnExInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmEndTxnExOut_t
+-------------------------------------------------------------------------*/
typedef struct dsmEndTxnExOut_t
{
dsUint16_t stVersion; /* structure version */
dsUint16_t reason; /* reason code */
dsStruct64_t groupLeaderObjId; /* groupLeader obj id returned on */
/* DSM_ACTION_OPEN */
dsUint8_t reserved1; /* future use */
dsUint16_t reserved2; /* future use */
}dsmEndTxnExOut_t;
#define dsmEndTxnExOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmEndGetDataExIn_t
+-------------------------------------------------------------------------*/
typedef struct dsmEndGetDataExIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* handle for session */
}dsmEndGetDataExIn_t;
#define dsmEndGetDataExInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmEndGetDataExOut_t
+-------------------------------------------------------------------------*/
typedef struct dsmEndGetDataExOut_t
{
dsUint16_t stVersion; /* structure version */
dsUint16_t reason; /* reason code */
dsStruct64_t totalLFBytesRecv; /* total lan free bytes recieved */
}dsmEndGetDataExOut_t;
#define dsmEndGetDataExOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for object list on dsmRetentionEvent() |
+-------------------------------------------------------------------------*/
typedef struct dsmObjList
{
dsUint16_t stVersion; /* structure version */
dsUint32_t numObjId; /* number of object IDs in the list */
ObjID *objId; /* list of object IDs to signal */
}dsmObjList_t ;
#define dsmObjlistVersion 1
/*-------------------------------------------------------------------------+
| Type definition eventType used on dsmRetentionEvent |
+--------------------------------------------------------------------------*/
typedef enum
{
eventRetentionActivate = 0x00, /* signal the server that the event has occured */
eventHoldObj, /* suspend delete/expire of the object */
eventReleaseObj /* Resume normal delete/expire processing */
}dsmEventType_t;
#define dsmRetentionEventInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on dsmRetentionEvent() |
+-------------------------------------------------------------------------*/
typedef struct dsmRetentionEventOut_t
{
dsUint16_t stVersion ; /* structure version */
}dsmRetentionEventOut_t;
#define dsmRetentionEventOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on dsmRequestBuffer() |
+-------------------------------------------------------------------------*/
typedef struct requestBufferIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* session Handle */
}requestBufferIn_t;
#define requestBufferInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on dsmRequestBuffer() |
+-------------------------------------------------------------------------*/
typedef struct requestBufferOut_t
{
dsUint16_t stVersion ; /* structure version */
dsUint8_t tsmBufferHandle; /* handle to tsm Data buffer */
char *dataPtr; /* Address to write data to */
dsUint32_t bufferLen; /* Max length of data to be written */
}requestBufferOut_t;
#define requestBufferOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on dsmReleaseBuffer() |
+-------------------------------------------------------------------------*/
typedef struct releaseBufferIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* session Handle */
dsUint8_t tsmBufferHandle; /* handle to tsm Data buffer */
char *dataPtr; /* Address to write data to */
}releaseBufferIn_t;
#define releaseBufferInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on dsmReleaseBuffer() |
+-------------------------------------------------------------------------*/
typedef struct releaseBufferOut_t
{
dsUint16_t stVersion ; /* structure version */
}releaseBufferOut_t;
/*-------------------------------------------------------------------------+
| Type definition for on dsmGetBufferData() |
+-------------------------------------------------------------------------*/
typedef struct getBufferDataIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* session Handle */
}getBufferDataIn_t;
#define getBufferDataInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on dsmGetBufferData() |
+-------------------------------------------------------------------------*/
typedef struct getBufferDataOut_t
{
dsUint16_t stVersion ; /* structure version */
dsUint8_t tsmBufferHandle; /* handle to tsm Data buffer */
char *dataPtr; /* Address of actual data to read */
dsUint32_t numBytes; /* Actual number of bytes to read from dataPtr*/
}getBufferDataOut_t;
#define getBufferDataOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on dsmSendBufferData() |
+-------------------------------------------------------------------------*/
typedef struct sendBufferDataIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* session Handle */
dsUint8_t tsmBufferHandle; /* handle to tsm Data buffer */
char *dataPtr; /* Address of actual data to send */
dsUint32_t numBytes; /* Actual number of bytes to send from dataPtr*/
}sendBufferDataIn_t;
#define sendBufferDataInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on dsmSendBufferData() |
+-------------------------------------------------------------------------*/
typedef struct sendBufferDataOut_t
{
dsUint16_t stVersion ; /* structure version */
}sendBufferDataOut_t;
#define sendBufferDataOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmUpdateObjExIn_t
+-------------------------------------------------------------------------*/
typedef struct dsmUpdateObjExIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t dsmHandle; /* session Handle */
dsmSendType sendType; /* send type back/arch */
char *descrP; /* archive description */
dsmObjName *objNameP; /* objName */
ObjAttr *objAttrPtr; /* attribute */
dsUint32_t objUpdAct; /* update action */
ObjID archObjId; /* objId for archive */
}dsmUpdateObjExIn_t;
#define dsmUpdateObjExInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmUpdateObjExOut_t
+-------------------------------------------------------------------------*/
#define dsmUpdateObjExOutVersion 1
#ifdef _MAC
#pragma options align=reset
#endif
#endif /* _H_DSMAPITD */
/***********************************************************************
* Tivoli Storage Manager *
* API Client Component *
* *
* (C) Copyright IBM Corporation 1993,2010 *
***********************************************************************/
/**************************************************************************
* Header File Name: tsmapitd.h
*
* Environment: ************************************************
* ** This is a platform-independent source file **
*
* ************************************************
*
* Design Notes: This file contains basic data types and constants
* includable by all client source files. The constants
* within this file should be set properly for the
* particular machine and operating system on which the
* client software is to be run.
*
* Platform specific definitions are included in dsmapips.h
*
* Descriptive-name: Definitions for Tivoli Storage manager API constants
*-------------------------------------------------------------------------*/
#ifndef _H_TSMAPITD
#define _H_TSMAPITD
#ifdef _MAC
#pragma options align = packed
#endif
/*==============================================================
Win32 applications using the tsm interface must use the
-DUNICODE flag during compilation.
==============================================================*/
#if _OPSYS_TYPE == DS_WINNT && !defined(DSMAPILIB)
#ifndef UNICODE
#error "Win32 applications using the TSM interface MUST be compiled with the -DUNICODE flag"
/*==============================================================
Mac OS X applications using the tsm interface must use the
-DUNICODE flag during compilation.
==============================================================*/
#if _OPSYS_TYPE == DS_MACOS && !defined(DSMAPILIB)
#ifndef UNICODE
#error "Mac OS X applications using the TSM interface MUST be compiled with the -DUNICODE flag"
#endif
#endif
/*-------------------------------------------------------------------------+
| Type definition for dsmGetType parameter on tsmBeginGetData() |
+-------------------------------------------------------------------------*/
typedef enum
{
gtTsmBackup = 0x00, /* Backup processing type */
gtTsmArchive /* Archive processing type */
} tsmGetType ;
/*-------------------------------------------------------------------------+
| Type definition for dsmQueryType parameter on tsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef enum
{
qtTsmArchive = 0x00, /* Archive query type */
qtTsmBackup, /* Backup query type */
qtTsmBackupActive, /* Fast query for active backup files */
qtTsmFilespace, /* Filespace query type */
qtTsmMC, /* Mgmt. class query type */
qtTsmReserved1, /* future use */
qtTsmReserved2, /* future use */
qtTsmReserved3, /* future use */
qtTsmReserved4, /* future use */
qtTsmBackupGroups, /* All group leaders in a specific filespace */
qtTsmOpenGroups, /* All group members associated with a leader */
qtTsmReserved5, /* future use */
qtTsmProxyNodeAuth, /* nodes that this node can proxy to */
qtTsmProxyNodePeer, /* peer nodes under this target node */
qtTsmReserved6, /* future use */
qtTsmReserved7, /* future use */
qtTsmReserved8 /* future use */
} tsmQueryType ;
/*-------------------------------------------------------------------------+
| Type definition sendType parameter on tsmBindMC() and tsmSendObj() |
+-------------------------------------------------------------------------*/
typedef enum
{
stTsmBackup = 0x00, /* Backup processing type */
stTsmArchive, /* Archive processing type */
stTsmBackupMountWait, /* Backup processing with mountwait on */
stTsmArchiveMountWait /* Archive processing with mountwait on */
} tsmSendType ;
/*-------------------------------------------------------------------------+
| Type definition for delType parameter on tsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef enum
{
dtTsmArchive = 0x00, /* Archive delete type */
dtTsmBackup, /* Backup delete (deactivate) type */
dtTsmBackupID /* Backup delete (remove) type */
} tsmDelType ;
/*-------------------------------------------------------------------------+
| Type definition for Overwrite parameter on tsmSendObj() |
+-------------------------------------------------------------------------*/
typedef enum
{
owIGNORE = 0x00,
owYES,
owNO
}tsmOwType;
/*-------------------------------------------------------------------------+
| Type definition for API Version on tsmInit() and tsmQueryApiVersion() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion; /* Structure version */
dsUint16_t version; /* API version */
dsUint16_t release; /* API release */
dsUint16_t level; /* API level */
dsUint16_t subLevel; /* API sub level */
dsmBool_t unicode; /* API unicode? */
} tsmApiVersionEx;
#define tsmApiVersionExVer 2
/*-------------------------------------------------------------------------+
| Type definition for Application Version on tsmInit() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion; /* Structure version */
dsUint16_t applicationVersion; /* application version number */
dsUint16_t applicationRelease; /* application release number */
dsUint16_t applicationLevel; /* application level number */
dsUint16_t applicationSubLevel; /* application sub level number */
} tsmAppVersion;
#define tsmAppVersionVer 1
/*-------------------------------------------------------------------------+
| Type definition for object name used on BindMC, Send, Delete, Query |
+-------------------------------------------------------------------------*/
/*-------------------------------------------------------------------------+
| Type definition for Backup delete info on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef struct tsmDelBack
#define tsmDelBackVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Archive delete info on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
dsStruct64_t objId ; /* object ID */
} tsmDelArch ;
#define tsmDelArchVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Backup ID delete info on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
dsStruct64_t objId ; /* object ID */
} tsmDelBackID;
#define tsmDelBackIDVersion 1
/*-------------------------------------------------------------------------+
| Type definition for delete info on dsmDeleteObj() |
+-------------------------------------------------------------------------*/
typedef union
{
tsmDelBack backInfo ;
tsmDelArch archInfo ;
tsmDelBackID backIDInfo;
} tsmDelInfo ;
/*-------------------------------------------------------------------------+
| Type definition for Object Attribute parameter on dsmSendObj() |
+-------------------------------------------------------------------------*/
typedef struct tsmObjAttr
{
dsUint16_t stVersion; /* Structure version */
dsChar_t owner[DSM_MAX_OWNER_LENGTH + 1]; /* object owner */
dsStruct64_t sizeEstimate; /* Size estimate in bytes of the object */
dsmBool_t objCompressed; /* Is object already compressed? */
dsUint16_t objInfoLength; /* length of object-dependent info */
char *objInfo; /* object-dependent info byte buffer */
dsChar_t *mcNameP; /* mgmnt class name for override */
tsmOwType reserved1; /* for future use */
tsmOwType reserved2; /* for future use */
dsmBool_t disableDeduplication; /* force no dedup for this object */
dsmBool_t useExtObjInfo; /* use ext objinfo up to 1536 */
} tsmObjAttr;
#define tsmObjAttrVersion 5
/*-------------------------------------------------------------------------+
| Type definition for mcBindKey returned on dsmBindMC() |
+-------------------------------------------------------------------------*/
typedef struct tsmMcBindKey
{
dsUint16_t stVersion; /* structure version */
#define tsmMcBindKeyVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Mgmt Class queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryMCData
{
dsUint16_t stVersion; /* structure version */
dsChar_t *mcName; /* Mgmt class name */
/* single name to get one or empty string to get all*/
dsmBool_t mcDetail; /* Want details or not? */
} tsmQryMCData;
#define tsmQryMCDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Archive Copy Group details on Query MC response |
+-------------------------------------------------------------------------*/
typedef struct tsmArchDetailCG
{
dsChar_t cgName[DSM_MAX_CG_NAME_LENGTH + 1]; /* Copy group name */
dsUint16_t frequency; /* Copy (archive) frequency */
dsUint16_t retainVers; /* Retain version */
dsUint8_t copySer; /* for copy serialization values, see defines */
dsUint8_t copyMode; /* for copy mode values, see defines above */
dsChar_t destName[DSM_MAX_CG_DEST_LENGTH + 1]; /* Copy dest name */
dsmBool_t bLanFreeDest; /* Destination has lan free path? */
dsmBool_t reserved; /* Not currently used */
dsUint8_t retainInit; /* possible values see dsmapitd.h */
dsUint16_t retainMin; /* if retInit is EVENT num of days */
dsmBool_t bDeduplicate; /* destination has dedup enabled */
}tsmArchDetailCG;
/*-------------------------------------------------------------------------+
| Type definition for Backup Copy Group details on Query MC response |
+-------------------------------------------------------------------------*/
typedef struct tsmBackupDetailCG
{
dsChar_t cgName[DSM_MAX_CG_NAME_LENGTH + 1]; /* Copy group name */
dsUint16_t frequency; /* Backup frequency */
dsUint16_t verDataExst; /* Versions data exists */
dsUint16_t verDataDltd; /* Versions data deleted */
dsUint16_t retXtraVers; /* Retain extra versions */
dsUint16_t retOnlyVers; /* Retain only versions */
dsUint8_t copySer; /* for copy serialization values, see defines */
dsUint8_t copyMode; /* for copy mode values, see defines above */
dsChar_t destName[DSM_MAX_CG_DEST_LENGTH + 1]; /* Copy dest name */
dsmBool_t bLanFreeDest; /* Destination has lan free path? */
dsmBool_t reserved; /* Not currently used */
dsmBool_t bDeduplicate; /* destination has dedup enabled */
}tsmBackupDetailCG;
/*-------------------------------------------------------------------------+
| Type definition for Query Mgmt Class detail response on dsmGetNextQObj()|
#define tsmQryRespMCDetailDataVersion 4
/*-------------------------------------------------------------------------+
| Type definition for Query Mgmt Class summary response on dsmGetNextQObj()|
+-------------------------------------------------------------------------*/
typedef struct tsmQryRespMCData
{
dsUint16_t stVersion; /* structure version */
dsChar_t mcName[DSM_MAX_MC_NAME_LENGTH + 1]; /* mc name */
dsChar_t mcDesc[DSM_MAX_MC_DESCR_LENGTH + 1]; /* mc description */
}tsmQryRespMCData;
#define tsmQryRespMCDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Archive queryBuffer on tsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryArchiveData
{
dsUint16_t stVersion; /* structure version */
tsmObjName *objName; /* Full dsm name of object */
dsChar_t *owner; /* owner name */
/* for maximum date boundaries, see defines above */
dsmDate insDateLowerBound; /* low bound archive insert date */
dsmDate insDateUpperBound; /* hi bound archive insert date */
dsmDate expDateLowerBound; /* low bound expiration date */
dsmDate expDateUpperBound; /* hi bound expiration date */
dsChar_t *descr; /* archive description */
} tsmQryArchiveData;
#define tsmQryArchiveDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Query Archive response on dsmGetNextQObj() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryRespArchiveData
{
dsUint16_t stVersion; /* structure version */
tsmObjName objName; /* Filespace name qualifier */
dsUint32_t copyGroup; /* copy group number */
dsChar_t mcName[DSM_MAX_MC_NAME_LENGTH + 1]; /* mc name */
dsChar_t owner[DSM_MAX_OWNER_LENGTH + 1]; /* owner name */
dsStruct64_t objId; /* Unique copy id */
dsStruct64_t reserved; /* backward compatability */
dsUint8_t mediaClass; /* media access class */
dsmDate insDate; /* archive insertion date */
dsmDate expDate; /* expiration date for object */
dsChar_t descr[DSM_MAX_DESCR_LENGTH + 1]; /* archive description */
dsUint16_t objInfolen; /* length of object-dependent info*/
dsUint8_t reservedObjInfo[DSM_MAX_OBJINFO_LENGTH]; /*object-dependent info */
dsUint160_t restoreOrderExt; /* restore order */
dsStruct64_t sizeEstimate; /* size estimate stored by user*/
dsUint8_t compressType; /* Compression flag */
dsUint8_t retentionInitiated; /* object waiting on retention event */
dsUint8_t objHeld; /* object is on "hold" see dsmapitd.h for values */
dsUint8_t encryptionType; /* type of encryption */
dsmBool_t clientDeduplicated; /* obj deduplicated by API*/
#define tsmQryRespArchiveDataVersion 7
/*-------------------------------------------------------------------------+
| Type definition for Archive sendBuff parameter on dsmSendObj() |
+-------------------------------------------------------------------------*/
typedef struct tsmSndArchiveData
{
dsUint16_t stVersion; /* structure version */
dsChar_t *descr; /* archive description */
} tsmSndArchiveData;
#define tsmSndArchiveDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Backup queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryBackupData
{
dsUint16_t stVersion; /* structure version */
tsmObjName *objName; /* full dsm name of object */
dsChar_t *owner; /* owner name */
dsUint8_t objState; /* object state selector */
dsmDate pitDate; /* Date value for point in time restore */
/* for possible values, see defines above */
dsUint32_t reserved1;
dsUint32_t reserved2;
} tsmQryBackupData;
#define tsmQryBackupDataVersion 3
/*-------------------------------------------------------------------------+
| Type definition for Query Backup response on dsmGetNextQObj() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryRespBackupData
{
dsUint16_t stVersion; /* structure version */
tsmObjName objName; /* full dsm name of object */
dsUint32_t copyGroup; /* copy group number */
dsChar_t mcName[DSM_MAX_MC_NAME_LENGTH + 1]; /* mc name */
dsChar_t owner[DSM_MAX_OWNER_LENGTH + 1]; /* owner name */
dsStruct64_t objId; /* Unique object id */
dsStruct64_t reserved; /* backward compatability */
dsUint8_t mediaClass; /* media access class */
dsUint8_t objState; /* Obj state, active, etc. */
dsmDate insDate; /* backup insertion date */
dsmDate expDate; /* expiration date for object */
dsUint16_t objInfolen; /* length of object-dependent info*/
dsUint8_t reservedObjInfo[DSM_MAX_OBJINFO_LENGTH]; /*object-dependent info */
dsUint160_t restoreOrderExt; /* restore order */
dsStruct64_t sizeEstimate; /* size estimate stored by user */
dsStruct64_t baseObjId;
dsUint16_t baseObjInfolen; /* length of base object-dependent info*/
dsUint8_t baseObjInfo[DSM_MAX_OBJINFO_LENGTH]; /* base object-dependent info */
dsUint160_t baseRestoreOrder; /* restore order */
dsUint32_t fsID;
dsUint8_t compressType;
dsmBool_t isGroupLeader;
dsmBool_t isOpenGroup;
dsUint8_t reserved1; /* for future use */
dsmBool_t reserved2; /* for future use */
dsUint16_t reserved3; /* for future use */
reservedInfo_t *reserved4; /* for future use */
dsUint8_t encryptionType; /* type of encryption */
#define tsmQryRespBackupDataVersion 8
/*-------------------------------------------------------------------------+
| Type definition for Active Backup queryBuffer on dsmBeginQuery()
|
| Notes: For the active backup query, only the fs (filespace) and objType
| fields of objName need be set. objType can only be set to
| DSM_OBJ_FILE or DSM_OBJ_DIRECTORY. DSM_OBJ_ANY_TYPE will not
| find a match on the query.
+-------------------------------------------------------------------------*/
typedef struct tsmQryABackupData
{
dsUint16_t stVersion; /* structure version */
tsmObjName *objName; /* Only fs and objtype used */
} tsmQryABackupData;
#define tsmQryABackupDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Query Active Backup response on dsmGetNextQObj() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryARespBackupData
{
dsUint16_t stVersion; /* structure version */
tsmObjName objName; /* full dsm name of object */
dsUint32_t copyGroup; /* copy group number */
dsChar_t mcName[DSM_MAX_MC_NAME_LENGTH + 1];/*management class name*/
dsChar_t owner[DSM_MAX_OWNER_LENGTH + 1]; /* owner name */
dsmDate insDate; /* backup insertion date */
dsUint16_t objInfolen; /* length of object-dependent info*/
dsUint8_t reservedObjInfo[DSM_MAX_OBJINFO_LENGTH]; /*object-dependent info */
dsUint8_t objInfo[DSM_MAX_EXT_OBJINFO_LENGTH]; /*object-dependent info */
} tsmQryARespBackupData;
#define tsmQryARespBackupDataVersion 2
/*-------------------------------------------------------------------------+
| Type definition for Backup queryBuffer on dsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryBackupGroups
{
dsUint16_t stVersion; /* structure version */
dsUint8_t groupType;
dsChar_t *fsName;
dsChar_t *owner;
dsStruct64_t groupLeaderObjId;
dsUint8_t objType;
dsUint32_t reserved1;
dsUint32_t reserverd2;
dsmBool_t noRestoreOrder;
dsmBool_t noGroupInfo;
dsChar_t *hl;
} tsmQryBackupGroups;
#define tsmQryBackupGroupsVersion 4
/*-------------------------------------------------------------------------+
| Type definition for proxynode queryBuffer on tsmBeginQuery() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryProxyNodeData
{
dsUint16_t stVersion; /* structure version */
dsChar_t *targetNodeName; /* target node name */
#define tsmQryProxyNodeDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for qryRespProxyNodeData parameter used on tsmGetNextQObj()|
+-------------------------------------------------------------------------*/
#define tsmQryRespProxyNodeDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for WINNT and OS/2 Filespace attributes |
+-------------------------------------------------------------------------*/
typedef struct tsmDosFSAttrib
{
osChar_t driveLetter ; /* drive letter for filespace */
dsUint16_t fsInfoLength; /* fsInfo length used */
osChar_t fsInfo[DSM_MAX_FSINFO_LENGTH];/*caller-determined data */
} tsmDosFSAttrib ;
/*-------------------------------------------------------------------------+
| Type definition for UNIX Filespace attributes |
+-------------------------------------------------------------------------*/
typedef struct tsmUnixFSAttrib
{
dsUint16_t fsInfoLength; /* fsInfo length used */
osChar_t fsInfo[DSM_MAX_FSINFO_LENGTH];/*caller-determined data */
} tsmUnixFSAttrib ;
/*-------------------------------------------------------------------------+
| Type definition for NetWare Filespace attributes |
+-------------------------------------------------------------------------*/
typedef tsmUnixFSAttrib tsmNetwareFSAttrib;
/*-------------------------------------------------------------------------+
| Type definition for Filespace attributes on all Filespace calls |
+-------------------------------------------------------------------------*/
typedef union
{
tsmNetwareFSAttrib netwareFSAttr;
tsmUnixFSAttrib unixFSAttr ;
tsmDosFSAttrib dosFSAttr ;
} tsmFSAttr ;
/*-------------------------------------------------------------------------+
| Type definition for fsUpd parameter on dsmUpdateFS()
+-------------------------------------------------------------------------*/
typedef struct tsmFSUpd
{
dsUint16_t stVersion ; /* structure version */
dsChar_t *fsType ; /* filespace type */
dsStruct64_t occupancy ; /* occupancy estimate */
dsStruct64_t capacity ; /* capacity estimate */
tsmFSAttr fsAttr ; /* platform specific attributes */
} tsmFSUpd ;
#define tsmFSUpdVersion 1
#define tsmQryFSDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for Query Filespace response on dsmGetNextQObj() |
+-------------------------------------------------------------------------*/
typedef struct tsmQryRespFSData
{
dsUint16_t stVersion; /* structure version */
dsChar_t fsName[DSM_MAX_FSNAME_LENGTH + 1]; /* Filespace name */
dsChar_t fsType[DSM_MAX_FSTYPE_LENGTH + 1] ; /* Filespace type */
dsStruct64_t occupancy; /* Occupancy est. in bytes. */
dsStruct64_t capacity; /* Capacity est. in bytes. */
tsmFSAttr fsAttr ; /* platform specific attributes */
dsmDate backStartDate; /* start backup date */
dsmDate backCompleteDate; /* end backup Date */
dsmDate reserved1 ; /* For future use */
dsmBool_t bIsUnicode;
dsUint32_t fsID;
dsmDate lastReplStartDate; /* The last time replication was started */
dsmDate lastReplCmpltDate; /* The last time replication completed */
/* (could have had a failure, */
/* but it still completes) */
dsmDate lastBackOpDateFromServer; /* The last store time stamp the client */
/* saved on the server */
dsmDate lastArchOpDateFromServer; /* The last store time stamp the client */
/* saved on the server */
dsmDate lastSpMgOpDateFromServer; /* The last store time stamp the client */
/* saved on the server */
dsmDate lastBackOpDateFromLocal; /* The last store time stamp the client */
/* saved on the Local */
dsmDate lastArchOpDateFromLocal; /* The last store time stamp the client */
/* saved on the Local */
dsmDate lastSpMgOpDateFromLocal; /* The last store time stamp the client */
/* saved on the Local */
dsInt32_t failOverWriteDelay; /* Minutes for client to wait before allowed */
/* to store to this Repl srvr, Specail codes: */
/* NO_ACCESS(-1), ACCESS_RDONLY (-2) */
} tsmQryRespFSData;
#define tsmQryRespFSDataVersion 5
/*-------------------------------------------------------------------------+
| Type definition for regFilespace parameter on dsmRegisterFS()
+-------------------------------------------------------------------------*/
typedef struct tsmRegFSData
{
dsUint16_t stVersion; /* structure version */
dsChar_t *fsName; /* Filespace name */
dsChar_t *fsType; /* Filespace type */
dsStruct64_t occupancy; /* Occupancy est. in bytes. */
dsStruct64_t capacity; /* Capacity est. in bytes. */
tsmFSAttr fsAttr ; /* platform specific attributes */
} tsmRegFSData;
#define tsmRegFSDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for session info response on dsmQuerySessionInfo() |
/*------------------------------------------------------------------*/
/* Replication and fail over information */
/*------------------------------------------------------------------*/
dsmFailOvrCfgType failOverCfgType; /* status of fail over */
dsChar_t replServerName[DSM_MAX_SERVERNAME_LENGTH+1]; /* repl server name */
dsChar_t homeServerName[DSM_MAX_SERVERNAME_LENGTH+1]; /* home server name */
dsChar_t replServerHost[DSM_MAX_SERVERNAME_LENGTH+1]; /* Network host name of DSM server */
dsInt32_t replServerPort; /* Server comm port on host */
} tsmApiSessInfo;
#define tsmApiSessInfoVersion 6
typedef struct
{
dsUint16_t stVersion;
dsChar_t dsmiDir[DSM_PATH_MAX + DSM_NAME_MAX +1];
dsChar_t dsmiConfig[DSM_PATH_MAX + DSM_NAME_MAX +1];
dsChar_t serverName[DSM_MAX_SERVERNAME_LENGTH+1];
dsInt16_t commMethod;
dsChar_t serverAddress[DSM_MAX_SERVER_ADDRESS];
dsChar_t nodeName[DSM_MAX_NODE_LENGTH+1];
dsmBool_t compression;
dsmBool_t compressalways;
dsmBool_t passwordAccess;
}tsmOptStruct ;
#define tsmOptStructVersion 1
/*-------------------------------------------------------------------------+
| Type definition for qryRespAccessData parameter used on dsmQueryAccess()|
+-------------------------------------------------------------------------*/
typedef struct
{
dsUint16_t stVersion ; /* structure version */
dsChar_t node[DSM_MAX_ID_LENGTH+1]; /* node name */
dsChar_t owner[DSM_MAX_OWNER_LENGTH+1]; /* owner */
tsmObjName objName ; /* object name */
dsmAccessType accessType; /* archive or backup */
dsUint32_t ruleNumber ; /* Access rule id */
}tsmQryRespAccessData;
#define tsmQryRespAccessDataVersion 1
/*-------------------------------------------------------------------------+
| Type definition for envSetUp parameter on dsmSetUp()
+-------------------------------------------------------------------------*/
typedef struct tsmEnvSetUp
{
dsUint16_t stVersion; /* structure version */
dsChar_t dsmiDir[DSM_PATH_MAX + DSM_NAME_MAX +1];
dsChar_t dsmiConfig[DSM_PATH_MAX + DSM_NAME_MAX +1];
dsChar_t dsmiLog[DSM_PATH_MAX + DSM_NAME_MAX +1];
char **argv; /* for executables name argv[0] */
dsChar_t logName[DSM_NAME_MAX +1];
dsmBool_t reserved1; /* for future use */
dsmBool_t reserved2; /* for future use */
} tsmEnvSetUp;
#define tsmEnvSetUpVersion 4
/*-------------------------------------------------------------------------+
| Type definition for dsmInitExIn_t
+-------------------------------------------------------------------------*/
typedef struct tsmInitExIn_t
{
dsUint16_t stVersion; /* structure version */
tsmApiVersionEx *apiVersionExP;
dsChar_t *clientNodeNameP;
dsChar_t *clientOwnerNameP;
dsChar_t *clientPasswordP;
dsChar_t *userNameP;
#define tsmInitExInVersion 5
/*-------------------------------------------------------------------------+
| Type definition for dsmInitExOut_t
+-------------------------------------------------------------------------*/
typedef struct tsmInitExOut_t
{
dsUint16_t stVersion; /* structure version */
dsInt16_t userNameAuthorities;
dsInt16_t infoRC; /* error return code if encountered */
/* adsm server name */
dsChar_t adsmServerName[DSM_MAX_SERVERNAME_LENGTH+1];
dsUint16_t serverVer; /* Server’s version number */
dsUint16_t serverRel; /* Server’s release number */
dsUint16_t serverLev; /* Server’s level number */
dsUint16_t serverSubLev; /* Server’s sublevel number */
dsmBool_t bIsFailOverMode; /* true if failover has occured */
dsChar_t replServerName[DSM_MAX_SERVERNAME_LENGTH+1]; /* repl server name */
dsChar_t homeServerName[DSM_MAX_SERVERNAME_LENGTH+1]; /* home server name */
} tsmInitExOut_t;
#define tsmInitExOutVersion 3
/*-------------------------------------------------------------------------+
| Type definition for dsmLogExIn_t
+-------------------------------------------------------------------------*/
typedef struct tsmLogExIn_t
{
dsUint16_t stVersion; /* structure version */
dsmLogSeverity severity;
dsChar_t appMsgID[8];
dsmLogType logType; /* log type : local, server, both */
dsChar_t *message; /* text of message to be logged */
dsChar_t appName[DSM_MAX_PLATFORM_LENGTH];
dsChar_t osPlatform[DSM_MAX_PLATFORM_LENGTH];
dsChar_t appVersion[DSM_MAX_PLATFORM_LENGTH];
} tsmLogExIn_t;
#define tsmLogExInVersion 2
/*-------------------------------------------------------------------------+
| Type definition for dsmlogExOut_t
+-------------------------------------------------------------------------*/
typedef struct tsmLogExOut_t
{
dsUint16_t stVersion; /* structure version */
} tsmLogExOut_t;
#define tsmLogExOutVersion 1
/*-------------------------------------------------------------------------+
#define tsmRenameInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmRenameOut_t
+-------------------------------------------------------------------------*/
typedef struct tsmRenameOut_t
{
dsUint16_t stVersion; /* structure version */
} tsmRenameOut_t;
#define tsmRenameOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for tsmEndSendObjExIn_t
+-------------------------------------------------------------------------*/
typedef struct tsmEndSendObjExIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t tsmHandle; /* handle for session */
} tsmEndSendObjExIn_t;
#define tsmEndSendObjExInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for dsmEndSendObjExOut_t
+-------------------------------------------------------------------------*/
typedef struct tsmEndSendObjExOut_t
{
dsUint16_t stVersion; /* structure version */
dsStruct64_t totalBytesSent; /* total bytes read from app */
dsmBool_t objCompressed; /* was object compressed */
dsStruct64_t totalCompressSize; /* total size after compress */
dsStruct64_t totalLFBytesSent; /* total bytes sent Lan Free */
dsUint8_t encryptionType; /* type of encryption used */
dsmBool_t objDeduplicated; /* was object processed for dist. data dedup */
dsStruct64_t totalDedupSize; /* total size after de-dup */
}tsmEndSendObjExOut_t;
#define tsmEndSendObjExOutVersion 3
/*-------------------------------------------------------------------------+
| Type definition for tsmGroupHandlerIn_t
+-------------------------------------------------------------------------*/
typedef struct tsmGroupHandlerIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t tsmHandle; /* handle for session */
dsUint8_t groupType; /* Type of group */
dsUint8_t actionType; /* Type of group operation */
dsUint8_t memberType; /* Type of member: Leader or member */
dsStruct64_t leaderObjId; /* OBJID of the groupleader */
dsChar_t *uniqueGroupTagP; /* Unique group identifier */
tsmObjName *objNameP ; /* group leader object name */
#define tsmGroupHandlerInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for tsmGroupHandlerExOut_t
+-------------------------------------------------------------------------*/
typedef struct tsmGroupHandlerOut_t
{
dsUint16_t stVersion; /* structure version */
} tsmGroupHandlerOut_t;
#define tsmGroupHandlerOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for tsmEndTxnExIn_t
+-------------------------------------------------------------------------*/
typedef struct tsmEndTxnExIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t tsmHandle; /* handle for session */
dsUint8_t vote;
} tsmEndTxnExIn_t;
#define tsmEndTxnExInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for tsmEndTxnExOut_t
+-------------------------------------------------------------------------*/
typedef struct tsmEndTxnExOut_t
{
dsUint16_t stVersion; /* structure version */
dsUint16_t reason; /* reason code */
dsStruct64_t groupLeaderObjId; /* groupLeader obj id returned on */
/* DSM_ACTION_OPEN */
dsUint8_t reserved1; /* future use */
dsUint16_t reserved2; /* future use */
} tsmEndTxnExOut_t;
#define tsmEndTxnExOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for tsmEndGetDataExIn_t
+-------------------------------------------------------------------------*/
typedef struct tsmEndGetDataExIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t tsmHandle; /* handle for session */
}tsmEndGetDataExIn_t;
#define tsmEndGetDataExInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for tsmEndGetDataExOut_t
+-------------------------------------------------------------------------*/
typedef struct tsmEndGetDataExOut_t
{
dsUint16_t stVersion; /* structure version */
dsUint16_t reason; /* reason code */
dsStruct64_t totalLFBytesRecv; /* total lan free bytes recieved */
}tsmEndGetDataExOut_t;
#define tsmEndGetDataExOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on tsmRetentionEvent() |
#define tsmRetentionEventInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for on tsmRetentionEvent() |
+-------------------------------------------------------------------------*/
typedef struct tsmRetentionEventOut_t
{
dsUint16_t stVersion ; /* structure version */
}tsmRetentionEventOut_t;
#define tsmRetentionEventOutVersion 1
/*-------------------------------------------------------------------------+
| Type definition for tsmUpdateObjExIn_t
+-------------------------------------------------------------------------*/
typedef struct tsmUpdateObjExIn_t
{
dsUint16_t stVersion; /* structure version */
dsUint32_t tsmHandle; /* session Handle */
tsmSendType sendType; /* send type back/arch */
dsChar_t *descrP; /* archive description */
tsmObjName *objNameP; /* objName */
tsmObjAttr *objAttrPtr; /* attribute */
dsUint32_t objUpdAct; /* update action */
ObjID archObjId; /* objId for archive */
}tsmUpdateObjExIn_t;
#define tsmUpdateObjExInVersion 1
/*-------------------------------------------------------------------------+
| Type definition for tsmUpdateObjExOut_t
+-------------------------------------------------------------------------*/
typedef struct tsmUpdateObjExOut_t
{
dsUint16_t stVersion; /* structure version */
}tsmUpdateObjExOut_t;
#define tsmUpdateObjExOutVersion 1
#ifdef _MAC
#pragma options align = reset
#endif
#endif /* _H_TSMAPITD */
/***********************************************************************
* Tivoli Storage Manager *
* API Client Component *
* *
* (C) Copyright IBM Corporation 1993,2010 *
***********************************************************************/
/**************************************************************************
* Header File Name: dsmapips.h
#ifndef _H_DSMAPIPS
#define _H_DSMAPIPS
#ifndef _WIN64
#pragma pack(1)
#endif
/*<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>*/
/* T Y P E D E F S */
/*<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>*/
#define DS_WINNT 22
#define _OPSYS_TYPE DS_WINNT
#if defined(_LONG_LONG)
/*-------------------------------------------------------------------------+
| Type definition for bool_t |
+-------------------------------------------------------------------------*/
/*
* Had to create a Boolean type that didn’t clash with any other predefined
* version in any operating system or windowing system.
*/
typedef enum
{
dsmFalse = 0x00,
dsmTrue = 0x01
}dsmBool_t ;
typedef struct
{
dsUint32_t hi; /* Most significant 32 bits. */
dsUint32_t lo; /* Least significant 32 bits. */
}dsStruct64_t ;
#endif /* DSMAPILIB */
#ifndef _WIN64
#pragma pack()
#endif
#endif /* _H_DSMAPIPS */
/***********************************************************************
* IBM Spectrum Protect *
* Common Source Component *
* *
* (C) Copyright IBM Corporation 1993,2016 *
***********************************************************************/
/***********************************************************************
* Header File Name: release.h
*
* Environment: ************************************************
* ** This is a platform-independent source file **
* ************************************************
*
#ifndef _H_RELEASE
#define _H_RELEASE
#define COMMON_VERSION 8
#define COMMON_RELEASE 1
#define COMMON_LEVEL 2
#define COMMON_SUBLEVEL 0
#define COMMON_DRIVER dsTEXT("")
/*======================================================================
The following string definitions are used for VERSION information
and should not be converted to dsTEXT or osTEXT. They are used
only at link time.
These are also used when the Jar file is built on Unix. See the
the perl script tools/unx/mzbuild/createReleaseJava
======================================================================*/
#define COMMON_VERSION_STR "8"
#define COMMON_RELEASE_STR "1"
#define COMMON_LEVEL_STR "2"
#define COMMON_SUBLEVEL_STR "0"
#define COMMON_DRIVER_STR ""
/*======================================================================
Internal version, release, and level (build) version. This
should be unique for every version+release+ptf of a product.
This information is recorded in the file attributes and data
stream for diagnostic purposes.
NOTE: DO NOT MODIFY THESE VALUES. YOU CAN ONLY ADD NEW ENTRIES!
======================================================================*/
#define COMMON_BUILD_TSM_510 1
#define COMMON_BUILD_TSM_511 2
#define COMMON_BUILD_TSM_515 3
#define COMMON_BUILD_TSM_516 4
#define COMMON_BUILD_TSM_520 5
#define COMMON_BUILD_TSM_522 6
#define COMMON_BUILD_TSM_517 7
#define COMMON_BUILD_TSM_523 8
#define COMMON_BUILD_TSM_530 9
#define COMMON_BUILD_TSM_524 10
#define COMMON_BUILD_TSM_532 11
#define COMMON_BUILD_TSM_533 12
#define COMMON_BUILD_TSM_525 13
#define COMMON_BUILD_TSM_534 14
#endif /* _H_RELEASE */
Note: DSMLINKAGE is defined differently for each operating system. See the
definitions in the dsmapips.h file for your specific operating system.
The information that is provided here contains a point-in-time copy of the files that
are distributed with the API. View the files in the API distribution package for the
latest version.
/***********************************************************************
* Tivoli Storage Manager *
* API Client Component *
* *
* (C) Copyright IBM Corporation 1993,2002 *
***********************************************************************/
/**************************************************************************/
/* Header File Name: dsmapifp.h */
/* */
/* Descriptive-name: Tivoli Storage Manager API function prototypes */
/**************************************************************************/
#ifndef _H_DSMAPIFP
#define _H_DSMAPIFP
#if defined(__cplusplus)
extern "C" {
#endif
#ifdef DYNALOAD_DSMAPI
#else
/*========================================================================*/
/* P U B L I C F U N C T I O N S */
/*========================================================================*/
);
#if defined(__cplusplus)
}
#endif
#endif /* _H_DSMAPIFP */
This section contains the function definitions for the API. It is a copy of the
tsmapifp.h header file.
Note: DSMLINKAGE is defined differently for each operating system. See the
definitions in the tsmapips.h file for your specific operating system.
/***********************************************************************
* Tivoli Storage Manager *
* API Client Component *
* *
* (C) Copyright IBM Corporation 1993,2002 *
***********************************************************************/
/**************************************************************************/
/* Header File Name: tsmapifp.h */
#if defined(__cplusplus)
extern "C" {
#endif
#ifdef DYNALOAD_DSMAPI
#else
/*========================================================================*/
/*P U B L I C F U N C T I O N S */
/*========================================================================*/
);
#if defined(__cplusplus)
}
#endif
#endif /* _H_TSMAPIFP */
Overview
The IBM Spectrum Protect family of products includes the following major
accessibility features:
v Keyboard-only operation
v Operations that use a screen reader
The IBM Spectrum Protect family of products uses the latest W3C Standard,
WAI-ARIA 1.0 (www.w3.org/TR/wai-aria/), to ensure compliance with US Section
508 (www.access-board.gov/guidelines-and-standards/communications-and-it/
about-the-section-508-standards/section-508-standards) and Web Content
Accessibility Guidelines (WCAG) 2.0 (www.w3.org/TR/WCAG20/). To take
advantage of accessibility features, use the latest release of your screen reader and
the latest web browser that is supported by the product.
Keyboard navigation
Interface information
User interfaces do not have content that flashes 2 - 55 times per second.
Web user interfaces rely on cascading style sheets to render content properly and
to provide a usable experience. The application provides an equivalent way for
low-vision users to use system display settings, including high-contrast mode. You
can control font size by using the device or web browser settings.
Web user interfaces include WAI-ARIA navigational landmarks that you can use to
quickly navigate to functional areas in the application.
Vendor software
The IBM Spectrum Protect product family includes certain vendor software that is
not covered under the IBM license agreement. IBM makes no representation about
the accessibility features of these products. Contact the vendor for accessibility
information about its products.
In addition to standard IBM help desk and support websites, IBM has a TTY
telephone service for use by deaf or hard of hearing customers to access sales and
support services:
TTY service
800-IBM-3383 (800-426-3383)
(within North America)
For more information about the commitment that IBM has to accessibility, see IBM
Accessibility (www.ibm.com/able).
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
Trademarks
IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at "Copyright and
trademark information" at www.ibm.com/legal/copytrade.shtml.
Linear Tape-Open, LTO, and Ultrium are trademarks of HP, IBM Corp. and
Quantum in the U.S. and other countries.
Java™ and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Permissions for the use of these publications are granted subject to the following
terms and conditions.
Applicability
These terms and conditions are in addition to any terms of use for the IBM
website.
Personal use
You may reproduce these publications for your personal, noncommercial
use provided that all proprietary notices are preserved. You may not
distribute, display or make derivative work of these publications, or any
portion thereof, without the express consent of IBM.
Commercial use
You may reproduce, distribute and display these publications solely within
your enterprise provided that all proprietary notices are preserved. You
may not make derivative works of these publications, or reproduce,
distribute or display these publications or any portion thereof outside your
enterprise, without the express consent of IBM.
Notices 209
Rights Except as expressly granted in this permission, no other permissions,
licenses or rights are granted, either express or implied, to the publications
or any information, data, software or other intellectual property contained
therein.
IBM reserves the right to withdraw the permissions granted herein
whenever, in its discretion, the use of the publications is detrimental to its
interest or, as determined by IBM, the above instructions are not being
properly followed.
You may not download, export or re-export this information except in full
compliance with all applicable laws and regulations, including all United
States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE
PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES
OF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A
PARTICULAR PURPOSE.
This Software Offering does not use cookies or other technologies to collect
personally identifiable information.
If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.
For more information about the use of various technologies, including cookies, for
these purposes, see IBM’s Privacy Policy at http://www.ibm.com/privacy and
IBM’s Online Privacy Statement at http://www.ibm.com/privacy/details in the
section entitled “Cookies, Web Beacons and Other Technologies,” and the “IBM
Software Products and Software-as-a-Service Privacy Statement” at
http://www.ibm.com/software/info/product-privacy.
Index 215
E function definitions, API 195, 199 management class (continued)
binding and rebinding to files 27
enablearchiveretentionprotection 30 dsmBindMC, assigned by 27
dsm.opt 30
dsm.sys 30 G querying 28
mbcs 81
encryption group leader 61
messages
application managed 45 dsmRCMsg function 124
authentication setting 44 metadata
interoperability 77 H object naming 21
transparent 47 header file dsmapips.h 153 multithreading
encryption and compression using buffer header file dsmapitd.h 153 flag 9
copy elimination 44 header file release.h 153 mtflag value 14
encryptkey 45 header file tsmapitd.h 153 multithread option 14
ending a session 15 header files overview 14
with dsmTerminate 15 dsmapifp.h 195 restrictions 14
environment dsmrc.h 143
setting up API 3 tsmapifp.h 199
environment variables
by operating system 3
high-level names
dsmRenameObj function 126
N
DSMI_CONFIG 3 node replication 53
high-level qualifier 75
DSMI_DIR 3 nodes
HP thread stack 14
DSMI_LOG 3 accessing across owners 23
envSetUp 137 authorization 71
errorlogretention names 9
when to use 71 I querying management classes 28
event IBM Knowledge Center v with client proxy support 78
eventRetentionActivate 30 inactive copies of objects 39 NULL
event logging 71 include data deduplication files 53 backup or archive group 26
event-based include objects 22
retention policy 30 include-exclude
eventRetentionActivate event 30 file 138
include-exclude list 27, 82
O
exclude data deduplication files 52 object
exclude objects 22 InSession state 117, 118
version control 39
interoperability
object ids, overview 21
access to API objects 75
object naming
F backup-archive client 75
commands 77
dsmBindMC 22
failover examples by OS 22
conventions
overview 53 file space name 21
UNIX or Linux 75
status information 54 high-level
Windows 75
fast path 31 object name 22
naming API objects 75
fast path queries 87 interoperability 75
operating system 78
file aggregation 35 low-level
file grouping 61 object name 22
file space object type 22
capacity 24 K overview 21
deleting 24 keyboard 205 object types 22
managing 24 Knowledge Center v objectID values 9
registering 24 objects
file space management access rules 23
dsmUpdateFS 24 L active copies 39
deleting 70
file space name LAN-free
file aggregation 35 deleting from server 71
data transfer 35
overview 21 expiration cycle 71
dsmEndGetDataEX function 98
file spaces inactive copies 39
dsmSetUp function 9
non-Unicode 81 turning off 71
logging events 71
file system management updating 70
low-level names
dsmDeleteFS 25 operating system interoperability 78
dsmRenameObj function 126
files option list
low-level qualifier 75
configuration 1 format 112, 115
LZ4 compression 41
object type 22 option string
LZW compression 41
option 1 API 2
flowchart fromowner 24
backup and archive example 56 options
restore and retrieve 68 M compressalways 2
fromowner option 24 makemtu 81 enablearchiveretentionprotection 30
function calls management class errorlogretention 71
short descriptions 83 associating objects 26 fromnode 23
Index 217
W
Windows 64-bit
sample application 7
Printed in USA