API function calls

Element	Description
Purpose	Describes the function call.
Syntax	Contains the actual C code for the function call. This code is copied from the UNIX or Linux version of the dsmapifp.h header file. See API function definitions source file. This file differs slightly on other operating systems. Application programmers for other operating systems 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 that are referenced in this section are defined in the dsmapitd.h header file. See API type definitions source files.
Return codes	Contains a list of the return codes that are specific to the function call. General system errors, such as communication errors, server problems, or user errors that might appear on any call are not listed. The return codes are defined in the dsmrc.h header file. See API return codes source file: dsmrc.h.

Table 1. API function calls
Function call and link	Description
dsmBeginGetData	Starts a restore or retrieve operation on a list of objects in storage.
dsmBeginQuery	Starts a query request to IBM Spectrum Protect™ for information.
dsmBeginTxn	Starts one or more transactions that begins a complete action. Either all of the actions succeed, or none succeed.
dsmBindMC	Associates, or binds, a management class to the object that is passed.
dsmChangePW	Changes an IBM Spectrum Protect password.
dsmCleanUp	This call is used if dsmSetUp was called.
dsmDeleteAccess	Deletes current authorization rules for backup versions or archived copies of your objects.
dsmDeleteFS	Deletes a file space from storage.
dsmDeleteObj	Turns off backup objects, or deletes archive objects in storage.
dsmEndGetData	Ends a dsmBeginGetData session that gets objects from storage.
dsmEndGetDataEx	Provides the total of LAN-free bytes that were sent.
dsmEndGetObj	Ends a dsmGetObj session that obtains data for a specified object.
dsmEndQuery	Signifies the end of a dsmBeginQuery action.
dsmEndSendObj	Indicates the end of data that is sent to storage.
dsmEndSendObjEx	Provides compression information and the number of bytes that were sent.
dsmEndTxn	Ends an IBM Spectrum Protect transaction.
dsmEndTxnEx	Provides group leader object ID information to use with the dsmGroupHandlerfunction call.
dsmGetData	Obtains a byte stream of data from IBM Spectrum Protect and place it in the caller's buffer.
dsmGetBufferData	Gets an IBM Spectrum Protect-allocated buffer of data from the IBM Spectrum Protect server.
dsmGetNextQObj	Gets the next query response from a previous dsmBeginQuery call and places it in the caller's buffer.
dsmGetObj	Obtains the requested object data from the data stream and places it in the caller's buffer.
dsmGroupHandler	Performs an action on a logical file group depending on the input that is given.
dsmInit	Starts an API session and connects the client to storage.
dsmInitEx	Starts an API session using the additional parameters that permit extended verification.
dsmLogEvent	Logs a user message to the server log file, to the local error log, or to both.
dsmLogEventEx	Logs a user message to the server log file, to the local error log, or to both.
dsmQueryAccess	Queries the server for all access authorization rules for either backup versions or archived copies of your objects.
dsmQueryApiVersion	Performs a query request for the API library version that the application client accesses.
dsmQueryApiVersionEx	Performs a query request for the API library version that the application client accesses.
dsmQueryCliOptions	Queries important option values in the user's option files.
dsmQuerySessInfo	Starts a query request to IBM Spectrum Protect for information that is related to the operation of the specified session in dsmHandle.
dsmQuerySessOptions	Queries important option values that are valid in the specified session in dsmHandle.
dsmRCMsg	Obtains the message text that is associated with an API return code.
dsmRegisterFS	Registers a new file space with the server.
dsmReleaseBuffer	Returns an IBM Spectrum Protect-allocated buffer.
dsmRenameObj	Renames the high-level or low-level object name.
dsmRequestBuffer	Obtains an IBM Spectrum Protect-allocated buffer for buffer copy elimination.
dsmRetentionEvent	Sends a list of object IDs to the server with a retention event operation to be performed on these objects.
dsmSendBufferData	Sends data from an IBM Spectrum Protect-allocated buffer.
dsmSendData	Sends a byte stream of data to IBM Spectrum Protect via a buffer.
dsmSendObj	Starts a request to send a single object to storage.
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.
dsmSetUp	Overwrites environment variable values.
dsmTerminate	Ends a session with the server and cleans up the IBM Spectrum Protect environment.
dsmUpdateFS	Updates a file space in storage.
dsmUpdateObj	Updates the objInfo information that is associated with an active backup object already on the server, or it updates archived objects.
dsmUpdateObjEx	Updates the objInfo information that is associated with a specific archive object even when there are multiple objects with same name, or it updates active backup objects.

dsmBeginGetData
The dsmBeginGetData function call starts a restore or retrieve operation on a list of objects in storage. This list of objects is contained in the dsmGetList structure. The application creates this list with values from the query that preceded a call to dsmBeginGetData.

dsmBeginQuery
The dsmBeginQuery function call starts a query request to the server for information about data, file spaces, and management classes.

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

dsmBindMC
The dsmBindMC function call associates, or binds, a management class to the passed object. The object is passed through the include-exclude list that is pointed to in the options file. If a match is not found in the Include list for a specific management class, the default management class is assigned. The Exclude list can prevent objects from a backup but not from an archive.

dsmChangePW
The dsmChangePW function call changes an IBM Spectrum Protect password. On a multiple-user operating system such as UNIX or Linux, only the root user or the authorized user can use this call.

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.

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.

dsmDeleteFS
The dsmDeleteFS function call deletes a file space from storage. To delete a file space, you must have the appropriate permissions that your IBM Spectrum Protect administrator gave you. To determine whether you have the necessary permissions, call dsmQuerySessInfo. This function call returns a data structure of type ApiSessInfo, that includes two fields, archDel and backDel.

dsmDeleteObj
The dsmDeleteObj function call inactivates backup objects, deletes backup objects, or it deletes archive objects in storage. The dtBackup type inactivates the currently active backup copy only. The dtBackupID type removes from the server whichever object ID is specified. Call this function from within a transaction.

dsmEndGetData
The dsmEndGetData function call ends a dsmBeginGetData session that obtains objects from storage.

dsmEndGetDataEx
The dsmEndGetDataEx function call provides the total of LAN-free bytes that were sent. It is an extension of the dsmEndGetData function call.

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

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

dsmEndSendObj
The dsmEndSendObj function call indicates the end of data that is sent to storage.

dsmEndSendObjEx
The dsmEndSendObjEx function call provides additional information regarding the number of bytes processed. The information includes: total bytes sent, compression information, lan-free bytes, and deduplication information.

dsmEndTxn
The dsmEndTxn function call ends an IBM Spectrum Protect transaction. Pair the dsmEndTxn function call with dsmBeginTxn to identify the call or set of calls that are considered a transaction. The application client can specify on the dsmEndTxn call whether the transaction must be committed or ended.

dsmEndTxnEx
The dsmEndTxnEx function call provides group leader object ID information for you to use with the dsmGroupHandler function call. It is an extension of the dsmEndTxn function call.

dsmGetData
The dsmGetData function call obtains a byte stream of data from IBM Spectrum Protect and places it in the caller's buffer. The application client calls dsmGetData when there is more data to receive from a previous dsmGetObj or dsmGetData call.

dsmGetBufferData
The dsmGetBufferData function call receives a byte stream of data from IBM Spectrum Protect through a buffer. After each call the application needs to copy the data and release the buffer through a call to dsmReleaseBuffer. If the number of buffers held by the application equals the numTsmBuffers specified in the dsmInitEx call, the dsmGetBufferData function blocks until a dsmReleaseBuffer is called.

dsmGetNextQObj
The dsmGetNextQObj function call gets the next query response from a previous dsmBeginQuery call and places the response in the caller buffer.

dsmGetObj
The dsmGetObj function call obtains the requested object data from the IBM Spectrum Protect data stream and places it in the caller's buffer. The dsmGetObj call uses the object ID to obtain the next object or partial object from the data stream.

dsmGroupHandler
The dsmGroupHandler function call performs an action on a logical file group depending on the input that is given. The client relates a number of individual objects together to reference and manage on the IBM Spectrum Protect server as a logical group.

dsmInit
The dsmInit function call starts an API session and connects the client to IBM Spectrum Protect storage. The application client can have only one active session open at a time. To open another session with different parameters, use the dsmTerminate call first to end the current session.

dsmInitEx
The dsmInitEx function call starts an API session by using the additional parameters for extended verification.

dsmLogEvent
The dsmLogEvent function call logs a user message (ANE4991 I) to the server log file, to the local error log, or to both. A structure of type logInfo is passed in the call. This call must be performed while at InSession state inside a session. Do not perform it within a send, get, or query. To retrieve messages logged on the server, use the query actlog command through the administrative client.

dsmLogEventEx
The dsmLogEventEx function call logs a user message to the server log file, to the local error log, or to both. This call must be made while at an InSession state within a session. The call cannot be made within a send, get, or query call.

dsmQueryAccess
The dsmQueryAccess function call queries the server for all access authorization rules for either backup versions or archived copies of your objects. A pointer to an array of access rules is passed in to the call, and the completed array is returned. A pointer to the number of rules is passed in to indicate how many rules are in the array.

dsmQueryApiVersion
The dsmQueryApiVersion function call performs a query request for the API library version that the application client accesses.

dsmQueryApiVersionEx
The dsmQueryApiVersionEx function call performs a query request for the API library version that the application client accesses.

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.

dsmQuerySessInfo
The dsmQuerySessInfo function call starts a query request to IBM Spectrum Protect 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 started after a successful dsmInitEx call.

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.

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

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

dsmReleaseBuffer
The dsmReleaseBuffer function returns a buffer to IBM Spectrum Protect. The application calls dsmReleaseBuffer after a dsmGetDataEx was called and the application has moved all the data out of the buffer and is ready to release it. dsmReleaseBuffer requires that dsmInitEx was called with the UseTsmBuffers set to btrue and a non-zero value was provided for numTsmBuffers. dsmReleaseBuffer should also be called if the application is about to call dsmTerminate and it still holds data buffers.

dsmRenameObj
The dsmRenameObj function call renames the high-level or low-level object name. For backup objects, pass in the current object name and changes either for high-level or low-level object names. For archive objects, pass in the current object file space name and object ID, and changes either for high-level or low-level object names. Use this function call within dsmBeginTxn and dsmEndTxn calls.

dsmRequestBuffer
The dsmRequestBuffer function returns a buffer to IBM Spectrum Protect. The application calls dsmRequestBuffer after a dsmGetDataEx was called and the application has moved all the data out of the buffer and is ready to release it.

dsmRetentionEvent
The dsmRetentionEvent function call sends a list of object IDs to the IBM Spectrum Protect server, with a retention event operation to be performed on these objects. Use this function call within dsmBeginTxn and dsmEndTxn calls.

dsmSendBufferData
The dsmSendBufferData function call sends a byte stream of data to IBM Spectrum Protect through a buffer that was provided in a previous dsmReleaseBuffer call. The application client can pass any type of data for storage on the server. Usually this data are file data, but it is not limited to file data. You can call dsmSendBufferData several times, if the byte stream of data that you are sending is large. Regardless of whether the call succeeds or fails, the buffer is released.

dsmSendData
The dsmSendData function call sends a byte stream of data to IBM Spectrum Protect through a buffer. The application client can pass any type of data for storage on the server. Usually, these data are file data, but are not limited to such. You can call dsmSendData several times, if the byte stream of data that you want to send is large.

dsmSendObj
The dsmSendObj function call starts a request to send a single object to storage. Multiple dsmSendObj calls and associated dsmSendData calls can be made within the bounds of a transaction for performance reasons.

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.

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

dsmTerminate
The dsmTerminate function call ends a session with the IBM Spectrum Protect server and cleans up the IBM Spectrum Protect environment.

dsmUpdateFS
The dsmUpdateFS function call updates a file space in IBM Spectrum Protect storage. This update ensures that the administrator has a current record of your file space.

dsmUpdateObj
The dsmUpdateObj function call updates the meta information associated with an active backup or archive object already on the server. The application bit data is not affected. To update an object, you must give a specific non-wildcard name. To update an archived object, set the dsmSendType to stArchive. Only the latest named archive object is updated.

dsmUpdateObjEx
The dsmUpdateObjEx function call updates the meta information that is associated with an active backup or archive object that is on the server. The application bit data is not affected. To update an object, you must specify a non-wildcard name, or you can specify the object ID to update a specific archived object. You cannot use wildcard characters when specifying the name. To update a backup object, set the dsmSendType parameter to stBackup. To update an archived object, set the dsmSendType parameter to stArchive.