Using the Application Program Interface


Chapter 5. API Function Calls

This chapter describes the API function calls. The calls are listed in alphabetical order. For each function, the following items are described:

Purpose
Describes the function call.

Syntax
Contains the actual C code for the function call, copied from the UNIX version of the dsmapifp.h header file. See Appendix B, "API Function Definitions Source File".
Note:This file differs slightly on other platforms. Application programmers for other platforms should check their version of the header file, dsmapifp.h, for the exact syntax of the API definitions.

Parameters
Describes each parameter in the function call, identifying it as either input (I) or output (O), depending on how it is used. Some parameters are designated as both input and output (I/O). The data types referred to in this section are defined in the dsmapitd.h header file. See Appendix A, "API Type Definitions Source File".

Return Codes
Contains a list of the return codes specific to the function call.
Note:General system errors, such as communication errors, server problems, and user mistakes that might appear on any call, are not listed. The return codes are defined in the dsmrc.h header file. For a complete list of all the return codes with explanations, see Appendix D, "API Return Codes With Explanations".

dsmBeginGetData

The dsmBeginGetData function call starts a restore or retrieve operation on a list of objects in TSM 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 must first 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 TSM storage in the most efficient mode possible without having to rewind or remount data tapes.

If you use DSM_MAX_GET_OBJ, the list can contain every object that is defined. If you use DSM_MAX_PARTIAL_GET_OBJ, the list can contain partial objects.

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 have been obtained, or the get is canceled, the dsmEndGetData call is sent. You can then start the cycle again.

Syntax

dsInt16_t dsmBeginGetData  (dsUint32_t       dsmHandle,
   dsBool_t       mountWait,
   dsmGetType   getType,
   dsmGetList  *dsmGetObjListP);

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 the application client is willing to wait for offline media to be mounted if the data that is needed is currently offline.

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.

Refer to Figure 16 and Appendix A, API Type Definitions Source File for more information on this structure.

Refer to page *** for more information on partial object restore or retrieve.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 13. Return Codes for dsmBeginGetData

Return Code Explanation
DSM_RC_ABORT_INVALID_OFFSET (33) The offset specified during a partial object retrieve is greater than the length of the object.
DSM_RC_ABORT_INVALID_LENGTH (34) The length specified during a partial object retrieve is greater than the length of the object, or the offset plus the length extends past the end of the object.
DSM_RC_NO_MEMORY (102) There is no RAM left to complete the request.
DSM_RC_NUMOBJ_EXCEED (2029) The dsmGetList.numObjId is greater than DSM_MAX_GET_OBJ.
DSM_RC_OBJID_NOTFOUND (2063) The object ID was not found, so the object was not restored.
DSM_RC_WRONG_VERSION_PARM (2065) The API version of the application client is different from the TSM library version.

dsmBeginQuery

The dsmBeginQuery function call starts a query request to TSM for information about one of the following areas:

The query data 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 perform. Select from one of the following:

qtArchive
Queries archived objects.

qtBackup
Queries backed-up objects.

qtBackupActive
Queries active, backed-up objects only for the entire filespace name that you pass. This is referred to as "fast path" and is an efficient way to query active objects from TSM storage.
Note:On the UNIX platform, you must be the root user.

qtFilespace
Queries registered file spaces.

qtMC
Queries defined management classes.

dsmQueryBuff *queryBuffer (I)
Identifies a pointer to a buffer that is mapped to a particular data structure that is associated with the query type that you pass. These structures contain the selection criteria for each query type. Complete the fields in each structure to specify the scope of the query that you want to perform. The first field of each structure is stVersion, the structure version number.

The data structures and their related fields include:

qryArchiveData
 

objName
The full name of the object. You can use a wildcard character, such as an asterisk (*) or question mark (?) in the high- or low-level portion of the name. See High-Level and Low-Level Names. An asterisk matches zero or more characters, and a question mark matches exactly one character. The objType field of the objName can be DSM_OBJ_FILE, DSM_OBJ_DIRECTORY, or DSM_OBJ_ANY_TYPE.

owner
The owner name of the object.

insDateLowerBound
The lower boundary for the archive insert date (the date the object was archived). To obtain the default lower boundary, set the Year component to DATE_MINUS_INFINITE.

insDateUpperBound
The upper boundary for the archive insert date (the date the object was archived). To obtain the default upper boundary, set the Year component to DATE_PLUS_INFINITE.

expDateLowerBound
The lower boundary for the expiration date. The default values for both expiration date fields are the same as for the insert date fields.

expDateUpperBound
The upper boundary for the expiration date.

descr
The archive description. Enter an asterisk (*) to search on all descriptions.

qryBackupData
 

objName
The full name of the object. You can use a wildcard character, such as an asterisk (*) or question mark (?) in the high- or low-level portion of the name. See High-Level and Low-Level Names. An asterisk matches zero or more characters, and a question mark matches exactly one character. The objType field of objName can be DSM_OBJ_FILE, DSM_OBJ_DIRECTORY, or DSM_OBJ_ANY_TYPE.

owner
The object owner name.

objState
This field can have one of the three values: DSM_ACTIVE, DSM_INACTIVE, or DSM_ANY_MATCH.

pitDate
The point-in-time value. A query using this field returns the latest object that was backed up before this date and time. The objState can be Active or Inactive. Objects that were deleted before the pitDate will not be returned. For example:
   Mon - backup ABC(1), DEF, GHI
   Tue - backup ABC(2), delete DEF
   Thr - backup ABC(3)

On Friday, call the query with a point-in-time value of Wednesday at 12:00:00 a.m. It returns the following information:

    ABC(2) - an Inactive copy
    GHI    - an Active copy

It does not return DEF because it was deleted.

qryABackupData
 

objName
The full name of the object. You can use a wildcard character, such as an asterisk (*) or question mark (?) in the high- or low-level portion of the name. See High-Level and Low-Level Names. An asterisk matches zero or more characters, and a question mark matches exactly one character. The objType field of objName can be DSM_OBJ_FILE, DSM_OBJ_DIRECTORY, or DSM_OBJ_ANY_TYPE.

qryFSData
 

fsName
Enter the name of a specific file space in this field, or enter an asterisk (*) to retrieve information about all registered file spaces.

qryMCData
 

mcName
Enter the name of a specific management class, or enter an empty string (" ") to retrieve information about all management classes.
Note:You cannot use an asterisk (*).

mcDetail
This field has a value of bTrue or bFalse. The value determines whether information on the backup and archive copy groups of the management class is returned.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 14. Return Codes for dsmBeginQuery

Return Code Explanation
DSM_RC_NO_MEMORY (102) There is no RAM remaining 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 TSM library version.

dsmBeginTxn

The dsmBeginTxn function call begins one or more TSM transactions that begin a complete action; either all the actions succeed or none succeed. An action can be either a single TSM call or a series of TSM calls. For example, a dsmSendObj call that is followed by a number of dsmSendData calls can be considered a single action. Similarly, a dsmSendObj with a dataBlkPtr that indicates a data area containing the object to back up is also considered a single action.

Try to group multiple objects together in a single transaction for data transfer operations. Grouping objects results in significant performance improvements in the TSM 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 as to what you can perform within a single transaction. These restrictions include:

With the API, either the application client can monitor and control these restrictions, or the API itself can monitor these restrictions and inform the application client when one or more restrictions are reached by way of appropriate return codes from the API calls.

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

There are no return codes specifically for this call.

dsmBindMC

The dsmBindMC function call associates, or binds, a TSM 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 backup but not from archive.

The application client can use the parameters 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.

You must call dsmBindMC prior to calling 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);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

dsmObjName *objNameP (I)
A pointer to the structure that contains the filespace name, high-level object name, low-level object name, and object type.

dsmSendType sendType (I)
Identifies whether this management class bind is performed for archive or backup sends. The possible values for this call specify:
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 a mcBindKey structure where the management class information is returned. The application client can use the information returned here to determine if this object fits within a multiple object transaction, or to do a management class query on the management class that is bound to the object.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 15. Return Codes for dsmBindMC

Return Code Explanation
DSM_RC_NO_MEMORY (102) There is no RAM left to complete the request.
DSM_RC_INVALID_PARM (109) One of the parameters passed has an invalid value.
DSM_RC_TL_EXCLUDED (185) The backup object is excluded and cannot be sent.
DSM_RC_INVALID_OBJTYPE (2010) Invalid object type.
DSM_RC_INVALID_SENDTYPE (2022) Invalid send type.
DSM_RC_WRONG_VERSION_PARM (2065) Application client API version is different than the TSM library version.

dsmChangePW

The dsmChangePW function call changes a TSM password. On a multiple-user platform such as UNIX, only the root user or the TSM-Authorized user can use this call.

On the Windows, OS/2, and Novell platforms, you can specify the password in the dsm.opt file. In this situation, dsmChangePW does not update dsm.opt. After the call to dsmChangePW is made, you must update dsm.opt separately.

This call must process successfully if dsmInitEx returns DSM_RC_VERIFIER_EXPIRED. The session will end if the dsmChangePW call fails in this situation.

If dsmChangePW is called for some other reason, the session will remain 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

The return code numbers are provided in parentheses ( ).

Table 16. Return Codes for dsmChangePW

Return Code Explanation
DSM_RC_ABORT_BAD_VERIFIER (6) An incorrect password was entered.
DSM_RC_AUTH_FAILURE (137) Authentication failure. Old password is incorrect.
DSM_RC_NEWPW_REQD (2030) A value must be entered for the new password.
DSM_RC_OLDPW_REQD (2031) A value must be entered for the old password.
DSM_RC_PASSWD_TOOLONG (2103) The specified password is too long.
DSM_RC_NEED_ROOT (2300) The API caller must be a root user or TSM-Authorized.

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 if the API was used in a single thread, or a multi-thread mode. Possible values include:
DSM_SINGLETHREAD
DSM_MULTITHREAD

Return Codes

There are no return codes specifically for this call.

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.

Return Codes

There are no return codes specifically for this call.

dsmDeleteFS

Note:On a UNIX platform, only a root user or TSM-Authorized user can delete a file space.

The dsmDeleteFS function call deletes a file space from TSM storage. To delete a file space, you must have the appropriate permissions that your TSMadministrator 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 called archDel and backDel.

If the file space that you need to delete contains backup versions, you must have backup delete authority (backDel = BACKDEL_YES). If it 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.

Syntax

dsInt16_t dsmDeleteFS  (dsUint32_t          dsmHandle,
   char           *fsName,
   unsigned char   repository);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

char *fsName (I)
A pointer to the filespace name to delete. The wildcard character is not permitted.

unsigned char repository (I)
Indicates whether the file space to delete is a backup repository, archive repository, or both. The possible values for this field are:
DSM_ARCHIVE_REP     /* archive repository   */
DSM_BACKUP_REP      /* backup repository    */
DSM_REPOS_ALL       /* all repository types */

Return Codes

The return code numbers are provided in parentheses ( ).

Table 17. Return Codes for dsmDeleteFS

Return Code Explanation
DSM_RC_ABORT_NOT_AUTHORIZED (27) You do not have the necessary authority to delete the file space.
DSM_RC_INVALID_REPOS (2015) Invalid value for repository.
DSM_RC_FSNAME_NOTFOUND (2060) Filespace name not found.
DSM_RC_NEED_ROOT (2300) API caller must be a root user.

dsmDeleteObj

The dsmDeleteObj function call turns off backup objects or deletes archive objects in TSM storage. Call this function from within a transaction. See dsmBeginTxn for more information.

The value of maxObjPerTxn determines the maximum number of objects that you can delete in a single transaction. To obtain this value, call dsmQuerySessInfo.

Note:You must have the appropriate permission that your TSM administrator gave you. To delete archive objects, you must have archive delete authority. You do not need backup delete authority to turn off a backup object.

Syntax

dsInt16_t dsmDeleteObj  (dsUint32_t      dsmHandle,
   dsmDelType  delType,
   dsmDelInfo  delInfo)

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

dsmDelType delType (I)
Indicates what type of object (backup or archive) to delete. Possible values include:
dtArchive
The object to delete was previously archived.
dtBackup
The object to turn off was previously backed up.

dsmDelInfo delInfo (I)
A structure whose fields identify the object. The fields are different, depending on whether the object is a backup object or an archive object. The structure for a backup object, called delBack, contains the object name and the object copy group. The structure for an archive object, called delArch, contains the object ID.

Send the query sequence that is described in Querying the TSM System to obtain the information for delInfo. The call to dsmGetNextQObj returns a data structure called qryRespBackupData for backup queries or qryRespArchiveData for archive queries. These data structures contain the information you need for delInfo.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 18. Return Codes for dsmDeleteObj

Return Code Explanation
DSM_RC_FS_NOT_REGISTERED (2061) File space name not registered.
DSM_RC_WRONG_VERSION_PARM (2065) Application client API version is different than the TSM library version.

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.

Depending on when dsmEndGetData is called, the API might need to finish processing a partial data stream before the process can be stopped. The caller, therefore, should not expect an immediate return from this call. Use dsmTerminate to flush the stream.

Syntax

dsInt16_t dsmEndGetData  (dsUint32_t dsmHandle);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

Return Codes

There are no return codes specifically for this call.

dsmEndGetObj

The dsmEndGetObj function call ends a dsmGetObj session that obtains data for a specified object.

The dsmEndGetObj can be started after an end of data is received for the object. This signals that all data was received, or indicates that further data will not be received for this object. You must call dsmEndGetObj before you can start another dsmGetObj call.

Depending on when dsmEndGetObj is called, the API might need to finish processing a partial data stream before the process can stop. The caller, therefore, should not expect an immediate return from this call.

Syntax

dsInt16_t dsmEndGetObj  (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 19. Return Codes for dsmEndGetObj

Return Code Explanation
DSM_RC_NO_MEMORY (102) There is no RAM left to complete the request.

dsmEndQuery

Use dsmEndQuery to signify the end of a dsmBeginQuery action.

The application client sends dsmEndQuery to complete a query. This call is either sent after all query responses are obtained through dsmGetNextQObj, or sent to end a query before all data is returned.

Note:TSM still sends the query data from the server to the client in this case, but the API just 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.

Return Codes

There are no return codes specifically for this call.

dsmEndSendObj

The dsmEndSendObj function call indicates the end of data that is sent to TSM 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 only exception to this rule is calling dsmEndTxn to end the transaction, which then discards all data sent for that 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

The return code numbers are provided in parentheses ( ).

Table 20. Return Codes for dsmEndSendObj

Return Code Explanation
DSM_RC_NO_MEMORY (102) There is no RAM left to complete this request.

dsmEndTxn

The dsmEndTxn function call ends a TSM transaction. Couple the dsmEndTxn function call with dsmBeginTxn to identify the TSM call or set of calls that are considered a transaction. The application client can specify on the dsmEndTxn call whether or not the transaction should be committed or ended.

Perform all of the following calls within the bounds of a transaction:

dsmSendObj
dsmSendData
dsmEndSendObj
dsmDeleteObj

Syntax

dsInt16_t dsmEndTxn  (dsUint32_t   dsmHandle,
   dsUint8_t    vote,
   dsUint16_t  *reason);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

dsUint8_t vote (I)
Indicates whether or not the application client wants to commit all the actions that are done between the previous dsmBeginTxn call and this call. The possible values are listed below.
   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.

dsUint16_t *reason (O)
If the call to dsmEndTxn ends with an error or the value of vote is not agreed to, this parameter will have a reason code indicating why the vote failed.
Note: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 will be DSM_RS_ABORT_BY_CLIENT (3). See Appendix C, API Return Codes Source File 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 will be DSM_RC_CHECK_REASON_CODE. In this case, the reason value will contain more information on the cause of the abort.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 21. Return Codes for dsmEndTxn

Return Code Explanation
DSM_RC_INVALID_VOTE (2011) The value specified for vote is invalid.
DSM_RC_CHECK_REASON_CODE (2302) The transaction was aborted, so check the reason field.

dsmGetData

The dsmGetData function call obtains a byte stream of data from TSM and place 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 A, API Type Definitions Source File for the type definition.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 22. Return Codes for dsmGetData

Return Code Explanation
DSM_RC_ABORT_INVALID_OFFSET (33) The offset specified during a partial object retrieve is greater than the length of the object.
DSM_RC_ABORT_INVALID_LENGTH (34) The length specified during a partial object retrieve is greater than the length of the object, or the offset plus the length extends past the end of the object.
DSM_RC_FINISHED (121) Finished processing (issue dsmEndGetObj).
DSM_RC_NULL_DATABLKPTR (2001) Datablock pointer is null.
DSM_RC_ZERO_BUFLEN (2008) Buffer length is zero for datablock pointer.
DSM_RC_NULL_BUFPTR (2009) Buffer pointer is null for datablock pointer.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different than the TSM library version.
DSM_RC_MORE_DATA (2200) There is more data to get.

dsmGetNextQObj

The dsmGetNextQObj function call gets the next query response from a previous dsmBeginQuery call and places it in the caller's buffer. The dsmGetNextQObj call is called one or more times. Each time it is called, a single query record is retrieved. If the application client needs to end the query before retrieving all of the data, you can send a dsmEndQuery call.

The dataBlkPtr 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 structure described below. On return, this structure contains the number of bytes that is actually transferred. See Appendix A, API Type Definitions Source File for the type definition of DataBlk. The structure associated with each type of query is:

Table 23. DataBlk Pointer Structure

Query Response Structure Fields
qtArchive qryRespArchiveData sizeEstimate. This field contains the value passed on a previous dsmSendObj call.
qtBackup qryRespBackupData restoreOrderExt. This field is of type dsUint16_t. Sort on this field when restoring multiple objects on a dsmBeginGetData call. An example of sorting code for this is in the API sample dapiqry.c. See also Figure 13 for a sorting example.

sizeEstimate. This field contains the value passed on a previous dsmSendObj call.

qtBackupActive qryARespBackupData
qtFilespace qryRespFSData backStartDate. This field contains the server's time stamp when the file space was updated with the backStartDate action.

backCompleteDate. This field contains the server's time stamp when the filespace was updated with the backCompleteDate action.

qtMC
qryRespMCData
qryRespMCDetailData


Return Codes

The return code numbers are provided in parentheses ( ).

Table 24. Return Codes for dsmGetNextQObj

Return Code Explanation
DSM_RC_ABORT_NO_MATCH (2) No match for the query requested.
DSM_RC_FINISHED (121) Finished processing (start dsmEndQuery).
DSM_RC_UNKNOWN_FORMAT (122) The file that TSM attempted to restore or retrieve has an unknown format.
DSM_RC_COMM_PROTOCOL_ERROR (136) Communication protocol error.
DSM_RC_NULL_DATABLKPTR (2001) Pointer is not pointing to a datablock.
DSM_RC_INVALID_MCNAME (2025) Invalid management class name.
DSM_RC_BAD_CALL_SEQUENCE (2041) The sequence of calls is invalid.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different than the TSM library version.
DSM_RC_MORE_DATA (2200) There is more data to get.
DSM_RC_BUFF_TOO_SMALL (2210) Buffer is too small.

dsmGetObj

The dsmGetObj function call obtains the requested object data from the TSM 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 indicated by the object ID is not the next object in the stream, the data stream is processed until the object is found or the stream is exhausted. 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 is placed.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 25. Return Codes for dsmGetObj

Return Code Explanation
DSM_RC_ABORT_INVALID_OFFSET (33) The offset specified during a partial object retrieve is greater than the length of the object.
DSM_RC_ABORT_INVALID_LENGTH (34) The length specified during a partial object retrieve is greater than the length of the object, or the offset plus the length extends past the end of the object.
DSM_RC_FINISHED (121) Finished processing (start dsmEndGetObj).
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different than the TSM library version.
DSM_RC_MORE_DATA (2200) There is more data to get.

dsmInit

The dsmInit function call starta a TSM API session and connects the client to TSM 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 Across Nodes and Across Owners" 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 TSM 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 set in dsmapitd.h. 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 installed on the user's workstation.

char *clientNodeNameP (I)
This parameter is a pointer to the node for the TSM session. All TSM sessions must have a node name associated with them. The maximum sizepermitted for a node name is set by the constant DSM_MAX_NODE_LENGTH in the dsmapitd.h file.

The node name is not case-sensitive.

If this parameter is set to NULL and passwordaccess prompt, the API attempts to obtain the node name first from the options string passed, and, if it is not there, from the configuration file or options files. If these attempts to find the node name fail, the UNIX API uses the system host name, while other platforms' APIs return the code DSM_RC_REJECT_ID_UNKNOWN.

This parameter must be NULL if the passwordaccess option in the dsm.sys configuration fileis set to generate. The API uses the system host name.

char *clientOwnerNameP (I)
This parameter is a pointer to the owner of the TSM session. If the platform on which the TSM session starts is a multi-user platform, an owner name of NULL (the root user) has the authority to back up, archive, restore, or retrieve any objects belonging to the application, regardless of the owner of the object.

The owner name is case-sensitive.

This parameter must be NULL if the passwordaccess option in the dsm.sys configuration file is set to generate. The API then uses the login user ID.

Note:On a multi-user platform, if passwordaccess=prompt, it is not necessary for the owner name to match the active user ID of the session running the application.

char *clientPasswordP (I)
This parameter is a pointer to the password of the node on which the TSM session runs. The maximum size allowed for a password is set by the constant DSM_MAX_VERIFIER_LENGTH in the file dsmapitd.h.

The password is not case-sensitive.

If passwordaccess=generate, the value of this parameter is ignored, except when the password file is first started.

char *applicationType (I)
This parameter identifies the application that is running the TSM session. The application client defines the value.
Note:This value is updated every time it is passed in on a dsmInit call.

Each time an API application client starts a session with the server, the application type of the client is registered with the server. We recommend that the application type value contain an operating system abbreviation because this value is entered in the "platform" field on the server. The maximum string length is DSM_MAX_PLATFORM_LENGTH.

To see the current value of the application type, call dsmQuerySessInfo.

char *configfile (I)
This parameter points to a character string that contains the fully-qualified name of an API configuration file. Options specified in the API configuration file override their specification in the client options file. Options files are defined when TSM (client or API) is installed.

For the description and use of configuration files, refer to Understanding Configuration Files and Options Files. Another source of information is the Tivoli Storage Manager Installing the Clients book.

char *options (I)
Points to a character string that can contain user options such as:

The application client can use the option list to override the values of these options that the configuration file sets.

The format of the options is:

  1. Each option specified in the option list begins with a dash (-) and is followed directly by the option keyword.
  2. The keyword, in turn, is followed directly by an equal sign (=) and then followed by the option parameter.
  3. If the option parameter contains a blank space, enclose the parameter with single or double quotes.
  4. If more than one option is specified, separate the options with blanks.

If options are NULL, values for all options are taken from the user options file or the API configuration file. You can find descriptions and usage of each option in the options.doc file or in the Tivoli Storage Manager Installing the Clients book.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 26. Return Codes for dsmInit

Return Code Explanation
DSM_RC_BAD_HOST_ID (-103) Session rejected. Unexpected 3270 emulator error.
DSM_RC_PC3270_MISSING_DLL (-123) PC3270 DLL not in user's path.
DSM_RC_3270COMM_MISSING_DLL (-124) DSM3270.DLL not in user's path.
DSM_RC_ABORT_SYSTEM_ERROR (1) The server has detected a system error and has notified the clients.
DSM_RC_REJECT_VERIFIER_EXPIRED (52) Password has expired and must be updated.
DSM_RC_REJECT_ID_UNKNOWN (53) Could not find the node name.
DSM_RC_TA_COMM_DOWN (103) The communications link is down.
DSM_RC_AUTH_FAILURE (137) There was an authentication failure.
DSM_RC_NO_STARTING_DELIMITER (148) There is no starting delimiter in pattern.
DSM_RC_NEEDED_DIR_DELIMITER (149) A directory delimiter is needed immediately before and after the "match directories" meta-string ("...") and one was not found.
DSM_RC_UNMATCHED_QUOTE (177) An unmatched quote is in the option string.
DSM_RC_NLS_CANT_OPEN_TXT (0610) Unable to open the message text file.
DSM_RC_INVALID_OPT (2013) An entry in the option string is invalid.
DSM_RC_INVALID_DS_HANDLE (2014) Invalid DSM handle.
DSM_RC_NO_OWNER_REQD (2032) Owner parameter must be NULL when passwordaccess=generate.
DSM_RC_NO_NODE_REQD (2033) Node parameter must be NULL when passwordaccess=generate.
DSM_RC_WRONG_VERSION (2064) Application client's API version has a higher value than the TSM version.
DSM_RC_PASSWD_TOOLONG (2103) The specified password is too long.
DSM_RC_NO_OPT_FILE (2220) No configuration file could be found.
DSM_RC_INVALID_KEYWORD (2221) A keyword specified in an options string is invalid.
DSM_RC_PATTERN_TOO_COMPLEX (2222) Include-exclude pattern too complex to be interpreted by TSM.
DSM_RC_NO_CLOSING_BRACKET (2223) There is no closing bracket in the pattern.
DSM_RC_INVALID_SERVER (2225) For a multi-user environment, the server in the system configuration file was not found.
DSM_RC_NO_HOST_ADDR (2226) Not enough information to connect to host.
DSM_RC_MACHINE_SAME (2227) The nodename defined in the options file cannot be the same as the system host name.
DSM_RC_NO_API_CONFIGFILE (2228) Cannot open the configuration file.
DSM_RC_NO_INCLEXCL_FILE (2229) The include-exclude file was not found.
DSM_RC_NO_SYS_OR_INCLEXCL (2230) Either the dsm.sys or the include-exclude file was not found.

dsmInitEx

The dsmInitEx function call starts an API session using the additional parameters that permit extended verification.

Syntax

dsInt16_t  dsmInitEx   (dsmInitExIn_t     *dsmInitExInP,
dsmInitExOut_t         *dsmInitExOutP) ;  

Parameters

dsmInitExIn_t *dsmInitExInP
This structure contains the 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, and DSM_API_LEVEL, and DSM_API_SUBLEVEL set in dsmapitd.h. A previous call to dsmQueryApiVersionEx must be performed to ensure that compatibility exists between the API version of the application client and the version of the API library installed on the user's workstation.

char *clientNodeNameP (I)
This parameter is a pointer to the node for the TSM session. All TSM sessions must have a node name associated with them. The constant, DSM_MAX_NODE_LENGTH in the file, dsmapitd.h, sets the maximum size permitted for a node name.

The node name is not case-sensitive.

If this parameter is set to NULL and passwordaccess prompt, the API attempts to obtain the node name first from the options string passed, and, if it is not there, from the configuration file or options files. If these attempts to find the node name fail, the UNIX API uses the system host name, while the APIs from other platforms return the code DSM_RC_REJECT_ID_UNKNOWN.

This parameter must be NULL if the passwordaccess option in the dsm.sys configuration file is set to generate. The API then uses the system host name.

char *clientOwnerNameP (I)
This parameter is a pointer to the owner of the TSM session. If the platform is a multi-user platform on which the TSM session is started, an owner name of NULL (the root user) has the authority to back up, archive, restore, or retrieve any objects belonging to the application, regardless of the owner of the object.

The owner name is case-sensitive.

This parameter must be NULL if the passwordaccess option in the dsm.sys configuration file is set to generate. The API then uses the login user ID.

Note:On a multi-user platform, if passwordaccess=prompt, it is not necessary for the owner name to match the active user ID of the session running the application.

char *clientPasswordP (I)
A pointer to the password of the node on which the TSM session runs. The maximum size allowed for a password is set by the constant, DSM_MAX_VERIFIER_LENGTH in the file, dsmapitd.h.

The password is not case-sensitive.

If passwordaccess=generate, the value of this parameter is ignored, except when the password file is first started.

char *applicationType (I)
Identifies the application that is running the TSM session. The application client identifies the value.
Note:This value is updated every time it is passed in on a dsmInitEx call.

Each time an API application client starts a session with the server, the application type of the client is registered with the server. We recommend that the application type value contain an operating system abbreviation because this value is entered in the "platform" field on the server. The maximum string length is DSM_MAX_PLATFORM_LENGTH.

To view the current value of the application type, call dsmQuerySessInfo.

char *configfile (I)
Points to a character string that contains the fully-qualified name of an API configuration file. Options specified in the API configuration file override their specification in the client options file. Options files are defined when TSM (client or API) is installed.

For the description and use of configuration files, refer to Understanding Configuration Files and Options Files. Another source of information is the Tivoli Storage Manager Installing the Clients book.

char *options (I)
Points to a character string that can contain user options such as:
  • Compressalways
  • Servername (UNIX only)
  • TCPServeraddr (non-UNIX)
  • Fromnode
  • Fromowner.

The application client can use the options list to override the values of these options that the configuration file sets.

The format of the options is:

  1. Each option specified in the option list begins with a dash (-) and is followed directly by the option keyword.
  2. The keyword, in turn, is followed directly by an equal sign (=) and then followed by the option parameter.
  3. If the option parameter contains a blank space, enclose the parameter with single or double quotes.
  4. If more than one option is specified, separate the options with blanks.

If options are NULL, values for all options are taken from the user options file or the API configuration file. You can find descriptions and usage of each option in the options.doc file or in the Tivoli Storage Manager Installing the Clients book.

char *userName;
A pointer to the administrative user name that has client authority for this node.

char *userNamePswd;
A pointer to the password for the userName, if a value is supplied.

dsmInitExOut_t *dsmInitExOut P
This structure contains the output parameters.

dsUint32_t *dsmHandle (0)
The handle that identifies this initialization session and associates it with subsequent API calls.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 27. Return Codes for dsmInitEx

Return Code Explanation
DSM_RC_BAD_HOST_ID (-103) Session rejected. Unexpected 3270 emulator error.
DSM_RC_PC3270_MISSING_DLL (-123) PC3270 DLL not in user's path.
DSM_RC_3270COMM_MISSING_DLL (-124) DSM3270.DLL not in user's path.
DSM_RC_ABORT_SYSTEM_ERROR (1) The TSM server has detected a system error and has notified the clients.
DSM_RC_REJECT_VERIFIER_EXPIRED (52) Password has expired and must be updated.
DSM_RC_REJECT_ID_UNKNOWN (53) Could not find the node name.
DSM_RC_TA_COMM_DOWN (103) The communications link is down.
DSM_RC_AUTH_FAILURE (137) There was an authentication failure.
DSM_RC_NO_STARTING_DELIMITER (148) There is no starting delimiter in pattern.
DSM_RC_NEEDED_DIR_DELIMITER (149) A directory delimiter is needed immediately before and after the "match directories" meta-string ("...") and one was not found.
DSM_RC_UNMATCHED_QUOTE (177) An unmatched quote is in the option string.
DSM_RC_NLS_CANT_OPEN_TXT (0610) Unable to open the message text file.
DSM_RC_INVALID_OPT (2013) An entry in the option string is invalid.
DSM_RC_INVALID_DS_HANDLE (2014) Invalid DSM handle.
DSM_RC_NO_OWNER_REQD (2032) Owner parameter must be NULL when passwordaccess=generate.
DSM_RC_NO_NODE_REQD (2033) Node parameter must be NULL when passwordaccess=generate.
DSM_RC_WRONG_VERSION (2064) Application client's API version has a higher value than the TSM version.
DSM_RC_PASSWD_TOOLONG (2103) The specified password is too long.
DSM_RC_NO_OPT_FILE (2220) No configuration file could be found.
DSM_RC_INVALID_KEYWORD (2221) A keyword specified in an options string is invalid.
DSM_RC_PATTERN_TOO_COMPLEX (2222) Include-exclude pattern too complex to be interpreted by TSM.
DSM_RC_NO_CLOSING_BRACKET (2223) There is no closing bracket in the pattern.
DSM_RC_INVALID_SERVER (2225) For a multi-user environment, the server in the system configuration file was not found.
DSM_RC_NO_HOST_ADDR (2226) Not enough information to connect to host.
DSM_RC_MACHINE_SAME (2227) The nodename defined in the options file cannot be the same as the system host name.
DSM_RC_NO_API_CONFIGFILE (2228) Cannot open the configuration file.
DSM_RC_NO_INCLEXCL_FILE (2229) The include-exclude file was not found.
DSM_RC_NO_SYS_OR_INCLEXCL (2230) Either the dsm.sys or the include-exclude file was not found.

dsmLogEvent

The dsmLogEvent function call logs a user message (ANE4990 T) 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 can be performed inside a session. To retrieve messages logged on the server, use the query actlog command through the Administrative Client. See the Tivoli Storage Manager Administrator's Reference for more information.

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: logServer, logLocal, logBoth.

Return Codes

Any return code associated with a handle or state that is not valid. See Appendix C, API Return Codes Source File. The return code numbers are provided in parentheses ( ).

Table 28. Return Codes for dsmLogEvent

Return Code Explanation
DSM_RC_STRING_TOO_LONG (2120) The message string is too long.

dsmLogEventEx

The dsmLogEventEx function call logs a user message to the server log file, to the local error log, or to both. This call can be performed inside a session. The TSM message number is determined by the severity. To view messages logged on the server, use the query actlog command through the Administrative Client. We recommend that you use the TSM 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). Refer to the Tivoli Distributed Storage Manager Administrator's Reference for more information.

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 */ 

Currently, there are no output parameters.

char appMsgID[8];
This parameter is a string to identify the specific application message. The format we recommend is three characters that are followed by four numbers. For example DSM0250.

dsmLogType logType;
This parameter specifies where to direct the event. The possible values are: logServer, logLocal, or logBoth.

char *message;
This parameter is the text of the event message to log. This must be a null-ended string. The maximum length is DSM_MAX_RC_MSG_LENGTH.

dsmLogExOut_t *dsmLogExOutP
This structure contains the output parameters.

Return Codes

Any return code associated with a handle or state that is not valid. See Appendix C, API Return Codes Source File. The return code numbers are provided in parentheses ( ).

Table 29. Return Codes for dsmLogEventEx

Return Code Explanation
DSM_RC_STRING_TOO_LONG (2120) The message string is too long.

dsmQueryAccess

The dsmQueryAccess function call queries the TSM 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:

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 filespace descriptors.

dsUint32_t *numberOfRules (O)
Returns the number of rules in the accessList array.

Return Codes

There are no return codes specifically for this call.

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. If the dsmQueryApiVersion call returns a version or version release that is older than that of the application clients, 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, 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

Return Codes

There are no return codes specifically for this call.

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 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);

Parameters

dsmApiVersionEx *apiVersionP (O)
This parameter is a pointer to the structure that contains the API library's version, release, level, and sublevel components. For example, if the library is version 3.7.0.0, then, after returning from the call, the fields of the structure contain the following values:
ApiVersionP->version = 3
ApiVersionP->release = 7
ApiVersionP->level = 0
ApiVersionP->subLevel = 0

Return Codes

There are no return codes specifically for this call.

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.

For more information about the options, see Tivoli Storage Manager Installing the Clients.

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 information returned in the optStruct structure is:

dsmiDir
The value of the environment variable, DSMI_DIR.

dsmiConfig
The client option file as specified by the environment variable, DSMI_CONFIG.

serverName
The name of the TSM server.

commMethod
The communication method selected. See the #defines for DSM_COMM_* in dsmapitd.h.

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
The values are: bTrue for generate; bFalse for prompt.

Return Codes

Any return code that is associated with incorrect options or environment variables. See Appendix C, API Return Codes Source File.

dsmQuerySessInfo

The dsmQuerySessInfo function call starts a query request to TSM for information related to the operation of the specified session in dsmHandle. A structure of type ApiSessInfo is passed in the call, with all available session related information entered. This call is typically started after a successful dsmInitEx call.

The information returned in the ApiSessInfo structure includes the following:

See Appendix A, API Type Definitions Source File 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.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 30. Return Codes for dsmQuerySessInfo

Return Code Explanation
DSM_RC_NO_SESS_BLK (2006) No server session block information.
DSM_RC_NO_POLICY_BLK (2007) No server policy information available.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different than the TSM library version.

dsmQuerySessOptions

The dsmQuerySessOptions function call queries important option values that are valid in the specified session in dsmHandle. A structure of type optStruct is passed in the call and contains the information.

This call is typically started after a successful dsmInitEx call. The values returned might be different from the values returned on a dsmQueryCliOptions call, depending on values passed to the dsmInitEx call, primarily optString, and optFile. For information about option precedence, see Understanding Configuration Files and Options Files.

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:

dsmiDir
The value of the environment variable, DSMI_DIR.

dsmiConfig
The client option file, dsm.opt, that the environment variable, DSMI_CONFIG, specifies.

serverName
The name of the TSM server.

commMethod
The communication method selected. See the #defines for DSM_COMM_* in dsmapitd.h.

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; bFalse for prompt.

For more information about the options, see Tivoli Storage Manager Installing the Clients.

Return Codes

Any return code associated with incorrect options or environment variables. See Appendix C, API Return Codes Source File.

dsmRCMsg

The dsmRCMsg function call obtains the message text that is associated with an API return code.

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.

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 for which you want the associated message text. The API return codes are listed in the file dsmrc.h. See Appendix C, API Return Codes Source File 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

The return code numbers are provided in parentheses ( ).

Table 31. Return Codes for dsmRCMsg

Return Code Explanation
DSM_RC_NULL_MSG (2002) The msg parameter for dsmRCMsg call is a NULL pointer.
DSM_RC_INVALID_RETCODE (2021) Return code passed to dsmRCMsg call is an invalid one.
DSM_RC_NLS_CANT_OPEN_TXT (0610) Unable to open the message text file.

dsmRegisterFS

The dsmRegisterFS function call registers a new file space with the TSM server. Register a file space first before you can back up any data to it.

Application clients should not use the same file space names that a backup-archive client would use.

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 TSM server.
Note:The fstype field includes the prefix, API:. All filespace queries will display this string. For example, if the user passes myfstype for fstype in dsmRegisterFS, the actual value string on the server will return 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

The return code numbers are provided in parentheses ( ).

Table 32. Return Codes for dsmRegisterFS

Return Code Explanation
DSM_RC_INVALID_FSNAME (2016) Invalid file space name.
DSM_RC_INVALID_DRIVE_CHAR (2026) Drive letter is not an alphabetic character.
DSM_RC_NULL_FSNAME (2027) Null filespace name.
DSM_RC_FS_ALREADY_REGED (2062) File space is already registered.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different than the TSM library version.
DSM_RC_FSINFO_TOOLONG (2106) Filespace information too long.

dsmSendData

The dsmSendData function call sends a byte stream of data to TSM via a buffer. The application client can pass any type of data for storage on the server. This data is typically file data, but it is not limited to such. You can call dsmSendData multiple times, in the event the byte stream of data that you want to send is large.

Note:The application client cannot reuse the buffer that is specified in dsmSendData until the dsmSendData call returns.

Note:If TSM returns code 157 (DSM_RC_WILL_ABORT), start a call to dsmEndSendObj and then to dsmEndTxn with a vote of DSM_VOTE_COMMIT. The application should then receive return code 2302 (DSM_RC_CHECK_REASON_CODE) and pass the reason code back to the application user. This will inform the user why the server is ending the transaction.

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 is 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 A, API Type Definitions Source File for the type definition.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 33. Return Codes for dsmSendData

Return Code Explanation
DSM_RC_NO_COMPRESS_MEMORY (154) Insufficient memory available to do data compression or expansion.
DSM_RC_COMPRESS_GREW (155) During compression the compressed data grew in size compared to the original data.
DSM_RC_WILL_ABORT (157) An unknown and unexpected error occurred, causing the transaction to halt.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different than the TSM library version.
DSM_RC_NEEDTO_ENDTXN (2070) Need to end transaction.
DSM_RC_OBJ_EXCLUDED (2080) The object is excluded by the include-exclude list.
DSM_RC_OBJ_NOBCG (2081) The object has no backup copy group and will not be sent to the server.
DSM_RC_OBJ_NOACG (2082) The object has no archive copy group and will not be sent to the server.

dsmSendObj

The dsmSendObj function call starts a request to send a single object to TSM 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:

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.

Note:For certain object types, byte stream data might not be associated with the data; for example, a directory entry with no extended attributes.

Before dsmSendObj is called, a preceding dsmBindMC call must be made to properly bind a management class to the object that you want to back up or archive. The API keeps this binding so that it can associate the proper management class with the object when it is sent to the server. If you permit the management class that is bound on a dsmSendObj call to default for an object type of directory (DSM_OBJ_DIRECTORY), the default might not be the default management class. Instead, the management class with the greatest retention time will be used. If more than one management class exists with this retention time, the first one that is encountered will be used.

Follow all object data that is sent to TSM 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 via the dsmSendData call, the dsmEndSendObj follows the last send to indicate the state change.

Note:If TSM returns code 157 (DSM_RC_WILL_ABORT), start a call to dsmEndTxn with a vote of DSM_VOTE_COMMIT. The application should then receive return code 2302 (DSM_RC_CHECK_REASON_CODE) and pass the reason code back to the application user. This will inform the user why the server is ending the transaction.

If the reason code is 11 (DSM_RS_ABORT_NO_REPOSIT_SPACE), it is possible that the sizeEstimate is too small for the actual amount of data. The application needs to determine a more accurate sizeEstimate and send the data again.

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 are:

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 contains the archive description.

dsmObjName *objNameP (I)
This parameter is a pointer to the structure that contains the filespace name, high-level object name, low-level object name, and object type. See Identifying the Object for more information.

ObjAttr *objAttrPtr (I)
This parameter is used to pass object attributes of interest to the application. See Appendix A, API Type Definitions Source File for the type definition.

The attributes of particular interest are:

DataBlk *dataBlkPtr (I/O)
This parameter points to a structure that includes both a pointer to the buffer of data that is to be backed up or archived and the size of that buffer. This parameter applies to dsmSendObj only. If you want to begin sending data on a subsequent dsmSendData call, rather than on the dsmSendObj call, set the buffer pointer in the DataBlk structure to NULL. On return, this structure contains the number of bytes that is actually transferred. See Appendix A, API Type Definitions Source File for the type definition.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 34. Return Codes for dsmSendObj

Return Code Explanation
DSM_RC_NO_COMPRESS_MEMORY (154) Insufficient memory available to do data compression or expansion.
DSM_RC_COMPRESS_GREW (155) During compression the compressed data grew in size compared to the original data.
DSM_RC_WILL_ABORT (157) An unknown and unexpected error occurred, causing the transaction to be halted.
DSM_RC_TL_NOACG (186) The management class for this file does not have a valid copy group for the send type.
DSM_RC_NULL_OBJNAME (2000) Null object name.
DSM_RC_NULL_OBJATTRPTR (2004) Null object attribute pointer.
DSM_RC_INVALID_OBJTYPE (2010) Invalid object type.
DSM_RC_INVALID_OBJOWNER (2019) Invalid object owner.
DSM_RC_INVALID_SENDTYPE (2022) Invalid send type.
DSM_RC_WILDCHAR_NOTALLOWED (2050) Wildcard characters not allowed.
DSM_RC_FS_NOT_REGISTERED (2061) File space not registered.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different than the TSM library version.
DSM_RC_NEEDTO_ENDTXN (2070) Need to end transaction.
DSM_RC_OBJ_EXCLUDED (2080) The object is excluded by the include-exclude list.
DSM_RC_OBJ_NOBCG (2081) The object has no backup copy group and will not be sent to the server.
DSM_RC_OBJ_NOACG (2082) The object has no archive copy group and will not be sent to the server.
DSM_RC_DESC_TOOLONG (2100) Description is too long.
DSM_RC_OBJINFO_TOOLONG (2101) Object information is too long.
DSM_RC_HL_TOOLONG (2102) High-level qualifier is too long.
DSM_RC_FILESPACE_TOOLONG (2104) File space name is too long.
DSM_RC_LL_TOOLONG (2105) Low-level qualifier is too long.
DSM_RC_NEEDTO_CALL_BINDMC (2301) dsmBindMC must be called first.

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);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

dsmAccessType accessType (I)
This parameter specifies the type of objects for which you want to give access. Possible values are:

atBackup
Specifies that access is being set to backup objects.

atArchive
Specifies that the access is being set for archive objects.

dsmObjName *objNameP (I)
This parameter is a pointer to the structure that contains the filespace name, the high-level object name, and the low-level object name.
Note:To specify all filespaces, use an asterisk (*) for the filespace name.

char *node (I)
This parameter is a pointer to the node name for which access is given. For any node, specify '*'.

char *owner (I)
This parameter is a pointer to the user name on the node to which you gave access. For all users, specify '*'.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 35. Return Codes for dsmSetAccess

Return Code Explanation
DSM_RC_INVALID_ACCESS_TYPE Invalid access type specified.
DSM_RC_FILE_SPACE_NOT_FOUND (124) Specified filespace was not found on the server.
DSM_RC_QUERY_COMM_FAILURE Communication error during server query.
DSM_RC_NO_FILES_BACKUP No files were backed up for this file space.
DSM_RC_NO_FILES_ARCHIVE No files were archived for this file space.
DSM_RC_INVALID_SETACCESS Invalid formulation of set access.

dsmSetUp

The dsmSetUp function call overwrites environment variable values. Call dsmSetUp before dsmInitEx. The values that were passed in the envSetUp structure will overwrite any existing environment variables or defaults. If you specify NULL for a field, values will be taken from the environment. If you do not set a value, the values will be taken from the defaults.

You cannot use the Trusted Communication Agent (TCA) when you use multi-thread mode. If you want your application to use passwordaccess generate, then you must be root or TSM-Authorized.

Note:If you use dsmSetUp, always call dsmTerminate before dsmCleanUp.

Syntax

dsInt16_t DSMLINKAGE dsmSetUp
        (dsBool_t    mtFlag,
         envSetUp    *envSetUpP);         

Parameters

dsBool_t mtFlag (I)
This parameter specifies if the API will be used in a single thread, or a multi-thread mode. Values include:
   DSM_SINGLETHREAD
   DSM_MULTITHREAD

enSetUp *envSetUpP(I)
This parameter is a pointer to the structure that holds the overwrite values. Specify NULL if you do not want to override existing environment variables. The fields in the envSetUp structure include:

dsmiDir
A fully-qualified directory path that contains a message file on UNIX. It also specifies the dsmtca and dsm.sys directories.

dsmiConfig
The fully-qualified name of the client options file.

dsmiLog
The fully-qualified path of the error log directory.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 36. Return Codes for dsmSetUp

Return Code Explanation
DSM_RC_INVALID_OPT (-0400) An invalid option was found.
DSM_RC_NO_HOST_ADDR (-0405) The TCPSERVERADDRESS for this server is not defined in the server name stanza in the system options file.
DSM_RC_NO_OPT_FILE (0406) The options file specified by filename cannot be found.
DSM_RC_MACHINE_SAME (0408) The NODENAME defined in the options file cannot be the same as the system HostName.
DSM_RC_INVALID_SERVER (0409) The system options file does not contain the SERVERNAME option.
DSM_RC_INVALID_KEYWORD (0410) An invalid option keyword was found in the dsmInitEx configuration file, the option string, dsm.sys, or dsm.opt.
DSM_RC_PATTERN_TOO_COMPLEX (0411) The include or exclude pattern issued is too complex to be accurately interpreted by TSM.
DSM_RC_NO_CLOSING_BRACKET (0412) The include or exclude pattern is incorrectly constructed. The closing bracket is missing.
DSM_RC_NLS_CANT_OPEN_TXT (0610) The system is unable to open the message text file.
DSM_RC_NLS_INVALID_CNTL_REC (0612) The system is unable to use the message text file.
DSM_RC_NOT_ADSM_AUTHORIZED (0927) You must be the TSM-Authorized user to have multithreading and passwordaccess generate.
DSM_RC_NO_INCLEXCL_FILE (2229) The include-exclude file was not found.
DSM_RC_NO_SYS_OR_INCLEXCL (2230) Either the dsm.sys or the include-exclude file was not found.

dsmTerminate

The dsmTerminate function call ends a session with the TSM server and cleans up the TSM environment.

Syntax

dsInt16_t dsmTerminate  (dsUint32_t dsmHandle);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

Return Codes

There are no return codes specifically for this call.

dsmUpdateFS

The dsmUpdateFS function call updates a file space in TSM storage. This ensures that the TSM 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 filespace name.

dsmFSUpd *fsUpdP (I)
This parameter is a pointer to the structure that has the proper fields completed for the update that you want. Complete only those fields that need updating.

dsUint32_t fsUpdAct (I)
A two-byte bit map that indicates which of the above fields to update. The bit masks are:

See the DSM_FSUPD definitions in Appendix A, API Type Definitions Source File for a description of these bit masks.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 37. Return Codes for dsmUpdateFS

Return Code Explanation
DSM_RC_FS_NOT_REGISTERED (2061) Filespace name is not registered.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different than the TSM library version.
DSM_RC_FSINFO_TOOLONG (2106) Filespace information is too long.

dsmUpdateObj

The dsmUpdateObj function call updates the objInfo information associated with an active backup object already on the server, or updates archived objects. The application bit data will not be 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.

Note:The server must be at 3.1.2.1 or a higher level.

You can only start the dsmUpdateObj call in the session state; it cannot be called inside a transaction because it performs its own transaction. Also, you can update only one object at a time.

Note:On the UNIX platform, if you change the owner field, you will not be able to 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.

Other differences are:

dsUint16_t objUpdAct
The bit masks and possible actions for objUpdAct are:

DSM_BACKUPD_OBJINFO
Updates objInfo, objInfoLength, and sizeEstimate.

DSM_BACKUPD_OWNER
Updates the owner of the object.

DSM_ARCHUPD_DESCR
Updates the Description field. Enter the value for the new description through the SendBuff parameter. See the sample program for proper use.

DSM_ARCHUPD_OBJINFO
Updates objInfo, objInfoLength, and sizeEstimate.

DSM_ARCHUPD_OWNER
Updates the owner of the object.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 38. Return Codes for dsmUpdateObj

Return Code Explanation
DSM_RC_INVALID_ ACTION (2232)
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 (2050) Wildcard characters not allowed.
DSM_RC_ABORT_NO_MATCH (2) Previous query does not match.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]