This chapter describes the API function calls, listed in alphabetical order. For each function call, the items listed below are described. Table 12 provides an alphabetical listing of the API function calls, a brief description, and the page location.
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. |
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". |
Function Call | Description | Page |
---|---|---|
dsmBeginGetData | Starts a restore or retrieve operation on a list of objects in TSM storage. | dsmBeginGetData |
dsmBeginQuery | Starts a query request to TSM for information. | dsmBeginQuery |
dsmBeginTxn | Begins one or more TSM transactions that begin a complete action; either all the actions succeed or none succeed. | dsmBeginTxn |
dsmBindMC | Associates, or binds, a TSM management class to the passed object. | dsmBindMC |
dsmChangePW | Changes a TSM password. | dsmChangePW |
dsmCleanUp | Used if dsmSetUp was called. | dsmCleanUp |
dsmDeleteAccess | Deletes current authorization rules for backup versions or archived copies of your objects. | dsmDeleteAccess |
dsmDeleteFS | Deletes a filespace from TSM storage. | dsmDeleteFS |
dsmDeleteObj | Turns off backup objects, or deletes archive objects in TSM storage. | dsmDeleteObj |
dsmEndGetData | Ends a dsmBeginGetData session that obtains objects from storage. | dsmEndGetData |
dsmEndGetObj | Ends a dsmGetObj session that obtains data for a specified object. | dsmEndGetObj |
dsmEndQuery | Signifies the end of a dsmBeginQuery action. | dsmEndQuery |
dsmEndSendObj | Indicates the end of data that is sent to TSM storage. | dsmEndSendObj |
dsmEndTxn | Ends a TSM transaction. | dsmEndTxn |
dsmGetData | Obtains a byte stream of data from TSM and place it in the caller's buffer. | dsmGetData |
dsmGetNextQObj | Gets the next query response from a previous dsmBeginQuery call and places it in the caller's buffer. | dsmGetNextQObj |
dsmGetObj | Obtains the requested object data from the TSM data stream and places it in the caller's buffer. | dsmGetObj |
dsmInit | Starts a TSM API session and connects the client to TSM storage. | dsmInit |
dsmInitEx | Starts an API session using the additional parameters that permit extended verification. | dsmInitEx |
dsmLogEvent | Logs a user message to the server log file, to the local error log, or to both. | dsmLogEvent |
dsmLogEventEx | Logs a user message to the server log file, to the local error log, or to both. | dsmLogEventEx |
dsmQueryAccess | Queries the TSM server for all access authorization rules for either backup versions or archived copies of your objects. | dsmQueryAccess |
dsmQueryApiVersion | Performs a query request for the API library version that the application client accesses. | dsmQueryApiVersion |
dsmQueryApiVersionEx | Performs a query request for the API library version that the application client accesses. | dsmQueryApiVersionEx |
dsmQueryCliOptions | Queries important option values in the user's option files. | dsmQueryCliOptions |
dsmQuerySessInfo | Starts a query request to TSM for information related to the operation of the specified session in dsmHandle. | dsmQuerySessInfo |
dsmQuerySessOptions | Queries important option values that are valid in the specified session in dsmHandle. | dsmQuerySessOptions |
dsmRCMsg | Obtains the message text that is associated with an API return code. | dsmRCMsg |
dsmRegisterFS | Registers a new file space with the TSM server. | dsmRegisterFS |
dsmRenameObj | Renames the high-level or low-level object name. | dsmRenameObj |
dsmSendData | Sends a byte stream of data to TSM via a buffer. | dsmSendData |
dsmSendObj | Starts a request to send a single object to TSM storage. | dsmSendObj |
dsmSetAccess | 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. | dsmSetAccess |
dsmSetUp | Overwrites environment variable values. | dsmSetUp |
dsmTerminate | Ends a session with the TSM server and cleans up the TSM environment. | dsmTerminate |
dsmUpdateFS | Updates a file space in TSM storage. | dsmUpdateFS |
dsmUpdateObj | Updates the objInfo information associated with an active backup object already on the server, or updates archived objects. | dsmUpdateObj |
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.
dsInt16_t dsmBeginGetData (dsUint32_t dsmHandle, dsBool_t mountWait, dsmGetType getType, dsmGetList *dsmGetObjListP);
Parameters
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.
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. |
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.
dsInt16_t dsmBeginQuery (dsUint32_t dsmHandle, dsmQueryType queryType, dsmQueryBuff *queryBuffer);
Parameters
Note: | On the UNIX platform, you must be the root user. |
The data structures and their related fields include:
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.
Note: | You cannot use an asterisk (*). |
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. |
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.
dsInt16_t dsmBeginTxn (dsUint32_t dsmHandle);
Parameters
Return Codes
There are no return codes specifically for this call.
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.
dsInt16_t dsmBindMC (dsUint32_t dsmHandle, dsmObjName *objNameP, dsmSendType sendType, mcBindKey *mcBindKeyP);
Parameters
For the dsmBindMC call, stBackup and stBackupMountWait are equivalent, and stArchive and stArchiveMountWait are equivalent.
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. |
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.
dsInt16_t dsmChangePW (dsUint32_t dsmHandle, char *oldPW, char *newPW);
Parameters
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. |
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
Return Codes
There are no return codes specifically for this call.
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
Return Codes
There are no return codes specifically for this call.
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.
dsInt16_t dsmDeleteFS (dsUint32_t dsmHandle, char *fsName, unsigned char repository);
Parameters
DSM_ARCHIVE_REP /* archive repository */ DSM_BACKUP_REP /* backup repository */ DSM_REPOS_ALL /* all repository types */
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. |
The dsmDeleteObj function call inactivates backup objects or deletes archive objects in TSM storage. Call this function from within a transaction. See dsmBeginTxn for more information.
Before you send dsmDeleteObj, 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.
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: | Your node must have the appropriate permission set by your TSM administrator. To delete archive objects, you must have archive delete authority. You do not need backup delete authority to inactivate a backup object. |
dsInt16_t dsmDeleteObj (dsUint32_t dsmHandle, dsmDelType delType, dsmDelInfo delInfo)
Parameters
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. |
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 if the application needs to close the session and end the restore immediately.
dsInt16_t dsmEndGetData (dsUint32_t dsmHandle);
Parameters
Return Codes
There are no return codes specifically for this call.
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.
dsInt16_t dsmEndGetObj (dsUint32_t dsmHandle);
Parameters
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. |
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.
dsInt16_t dsmEndQuery (dsUint32_t dsmHandle);
Parameters
Return Codes
There are no return codes specifically for this call.
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.
dsInt16_t dsmEndSendObj (dsUint32_t dsmHandle);
Parameters
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. |
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:
dsInt16_t dsmEndTxn (dsUint32_t dsmHandle, dsUint8_t vote, dsUint16_t *reason);
Parameters
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.
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.
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. |
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.
dsInt16_t dsmGetData (dsUint32_t dsmHandle, DataBlk *dataBlkPtr);
Parameters
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. The last buffer was received. Check numBytes for the amount of data and then call 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. |
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.
dsInt16_t dsmGetNextQObj (dsUint32_t dsmHandle, DataBlk *dataBlkPtr);
Parameters
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 |
|
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. |
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.
dsInt16_t dsmGetObj (dsUint32_t dsmHandle, ObjID *objIdP, DataBlk *dataBlkPtr);
Parameters
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. |
The dsmInit function call starts 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.
dsInt16_t dsmInit (dsUint32_t *dsmHandle, dsmApiVersion *dsmApiVersionP, char *clientNodeNameP, char *clientOwnerNameP, char *clientPasswordP, char *applicationType, char *configfile, char *options);
Parameters
The node name is not case-sensitive.
If this parameter is set both to NULL and passwordaccess prompt, the API attempts to obtain the node name first from the options string that was passed. If it is not there, the API then attempts to obtain the node name 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.
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. |
The password is not case-sensitive.
Except when the password file is first started, the value of this parameter is ignored if passwordaccess=generate.
Each time an API application client starts a session with the server, the application type (or platform) of the client is updated on 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.
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.
The application client can use the option list to override the values of these options that the configuration file sets.
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.
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. |
The dsmInitEx function call starts an API session using the additional parameters that permit extended verification.
dsInt16_t dsmInitEx (dsmInitExIn_t *dsmInitExInP, dsmInitExOut_t *dsmInitExOutP) ;
Parameters
The node name is not case-sensitive.
If this parameter is set both to NULL and passwordaccess prompt, the API attempts to obtain the node name first from the options string passed. If it is not there, the API then attempts to obtain the node name 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.
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. |
The password is not case-sensitive.
Except when the password file is first started, the value of this parameter is ignored if passwordaccess=generate.
Each time an API application client starts a session with the server, the application type (or platform) of the client is updated on 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.
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.
The application client can use the options list to override the values of these options that the configuration file sets.
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.
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. |
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.
dsInt16_t dsmLogEvent (dsUint32_t dsmHandle, logInfo *logInfoP);
Parameters
The fields in the logInfo structure are:
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. |
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 Storage Manager Administrator's Reference for more information.
extern dsInt16_t DSMLINKAGE dsmLogEventEx( dsUint32_t dsmHandle, dsmLogExIn_t *dsmLogExInP, dsmLogExOut_t *dsmLogExOutP );
Parameters
logSevInfo, /* information ANE4990 */ logSevWarning, /* warning ANE4991 */ logSevError, /* Error ANE4992 */ logSevSevere /* severe ANE4993 */
Note: | Currently, there are no output parameters. |
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. |
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
Return Codes
There are no return codes specifically for this call.
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.
void dsmQueryApiVersion (dsmApiVersion *apiVersionP);
Parameters
dsmApiVersionP->version = 1 dsmApiVersionP->release = 1 dsmApiVersionP->level = 0
Return Codes
There are no return codes specifically for this call.
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.
void dsmQueryApiVersionEx (dsmApiVersionEx *apiVersionP);
Parameters
Return Codes
There are no return codes specifically for this call.
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.
dsInt16_t dsmQueryCliOptions (optStruct *optstructP);
Parameters
The information returned in the optStruct structure is:
Return Codes
Any return code that is associated with incorrect options or environment variables. See Appendix C, API Return Codes Source File.
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.
dsInt16_t dsmQuerySessInfo (dsUint32_t dsmHandle, ApiSessInfo *SessInfoP);
Parameters
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. |
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.
dsInt16_t dsmQuerySessOptions (dsUint32_t dsmHandle, optStruct *optstructP);
Parameters
The information returned in the optStruct structure is:
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.
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.
dsInt16_t dsmRCMsg (dsUint32_t dsmHandle, dsInt16_t dsmRC, char *msg);
Parameters
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.
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. |
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.
dsInt16_t dsmRegisterFS (dsUint32_t dsmHandle, regFSData *regFilespaceP);
Parameters
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.
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. |
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 filespace name and object ID, and changes either for high-level or low-level object names. Use this function call within a dsmBeginTxn and dsmEndTxn.
The merge flag is used to determine whether 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.
The dsmRenameObj function call tests for the following three merge conditions:
Note: | Only the owner of the object can rename it. |
dsInt16_t dsmRenameObj (dsmRenameIn_t *dsmRenameInP, dsmRenameOut_t *dsmRenameOutP);
Parameters
Note: | Currently, there are no output parameters. |
The return code numbers are provided in parentheses ( ).
Table 33. Return Codes for dsmRenameObj
Return Code | Explanation |
---|---|
DSM_RC_ABORT_MERGE_ERROR (45) | Server detected a merge error. |
DSM_RC_ABORT_DUPLICATE_OBJECT (32) | Object already exists and merge is false. |
DSM_RC_ABORT_NO_MATCH (2) | Object not found. |
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. |
dsInt16_t dsmSendData (dsUint32_t dsmHandle, DataBlk *dataBlkPtr);
Parameters
The return code numbers are provided in parentheses ( ).
Table 34. 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. |
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. |
dsInt16_t dsmSendObj (dsUint32_t dsmHandle, dsmSendType sendType, void *sendBuff, dsmObjName *objNameP, ObjAttr *objAttrPtr, DataBlk *dataBlkPtr);
Parameters
Note: | Use the MountWait types if there is any possibility that your application user might send data to a tape. |
The attributes of particular interest are:
If the size estimate specified is significantly smaller than the actual number of bytes sent, the server might have difficulty allocating enough space and end the transaction with a reason code 11 (DSM_RS_ABORT_NO_REPOSIT_SPACE).
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 will not compress.
If your object has no bit data (only the attribute information from this call), the sizeEstimate should be zero.
If the object is compressed (object compressed=bTrue), TSM does not try to compress it again. If it is not compressed, TSM decides whether to compress the object, based on the values of the compression option set by the TSM 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.
Note: | Information is not stored here automatically. When this attribute is used, the attribute, objInfoLength, must also be set to show the length of objInfo. |
The return code numbers are provided in parentheses ( ).
Table 35. 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. |
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
Note: | To specify all filespaces, use an asterisk (*) for the filespace name. |
Return Codes
The return code numbers are provided in parentheses ( ).
Table 36. 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. |
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
DSM_SINGLETHREAD DSM_MULTITHREAD
The return code numbers are provided in parentheses ( ).
Table 37. 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. |
The dsmTerminate function call ends a session with the TSM server and cleans up the TSM environment.
dsInt16_t dsmTerminate (dsUint32_t dsmHandle);
Parameters
There are no return codes specifically for this call.
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.
dsInt16_t dsmUpdateFS (dsUint32_t dsmHandle, char *fs, dsmFSUpd *fsUpdP, dsUint32_t fsUpdAct);
Parameters
Note: | For Intel platforms, the drive letter value from dsmDOSAttrib is also updated when FSINFO is selected. |
See the DSM_FSUPD definitions in Appendix A, API Type Definitions Source File for a description of these bit masks.
The return code numbers are provided in parentheses ( ).
Table 38. 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. |
The dsmUpdateObj function call updates the meta 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. |
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:
Other differences are:
The return code numbers are provided in parentheses ( ).
Table 39. 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. |