Tivoli Storage Manager Using the Application Program Interface Version 5 Release 1 GC32-0793-00 Tivoli Storage Manager Using the Application Program Interface Version 5 Release 1 GC32-0793-00 Note Before using this information and the product it supports, read the general information in “Appendix F. Notices” on page 237. First Edition (March 2002) This edition applies to version 5, release 1, modification 0 of the Tivoli Storage Manager Using the Application Program Interface (5698-SPM) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SH26–4123–01. © Copyright International Business Machines Corporation 1993, 2002. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures ...............v Accessing Across Nodes and Across Owners . 25 Managing Filespaces ...........26 Tables ...............vii Associating a Management Class With Objects. 28 Query Management Classes ........29 Querying the TSM System .........30 About This Book...........ix An Example .............32 Who Should Read This Manual ........ix Sending Data to a Server ..........34 Conventions Used in This Manual .......ix The Transaction Model .........34 Reading Syntax Diagrams ..........x File Aggregation............34 Related Information ...........xii Sending Objects to the Server ........35 Accessing Publications Online .......xii Understand Backup And Archive Objects . 35 How to Contact Us ...........xiii Compression .............36 Summary of Code Changes .........xiv Reading State Diagrams and Flowcharts .....36 Version 5 Release 1 Level 0 March 2002....xiv An Example .............39 Version 4 Release 2 Level 1 November 2001 . xv File Grouping .............41 Version 4 Release 2 Level 0 June 2001 ....xv Receiving Data from a Server ........43 Version 4 Release 1 Level 0 July 2000 ....xvi Perform a Partial Object Restore or Retrieve . 43 Version 3 Release 7 Level 0 September 1999 . xvi Receive Data With a Restore or Retrieve Version 3 Release 1 Level 7 May 1999 ....xvi Procedure ..............44 Version 3 Release 1 Level 6 January 1999 . xvii State Diagrams and Flowcharts .......49 Version 3 Release 1 Level 5 August 1998 . xvii An Example .............50 Version 3 Release 1 Level 3 March 1998 . xvii Updating Objects on the Server........52 Version 3 Release 1 Level 0 October 1997 . xvii Deleting Objects from the Server .......52 Logging Events .............53 Chapter 1. Introducing the API .....1 Putting It All Together...........53 Understanding Configuration Files and Options Files 1 Setting Up the API Environment........3 Chapter 4. Understanding Interoperability ...........55 Chapter 2. Building and Running the Backup-Archive Client Interoperability .....55 Sample Application ..........5 Naming Your API Objects ........55 Building the Sample Application........5 Using Commands ...........56 NetWare Operating System ........5 Operating System Interoperability .......57 OS/400 Operating System .........6 UNIX Operating System .........8 Chapter 5. Using the API With Unicode 59 Windows 32–bit Operating System ......9 Who Should Use Unicode .........59 Windows 64–bit Operating System .....10 Setting Up Unicode............59 Running the Sample Application .......11 Chapter 6. API Function Calls .....61 Chapter 3. Using the Application dsmBeginGetData ............63 Program Interface ..........13 dsmBeginQuery .............65 Key Design Recommendations ........13 dsmBeginTxn..............68 Determining Size Limits ..........14 dsmBindMC ..............69 Maintaining Version Control in the API .....14 dsmChangePW .............71 Using Multi-Threading ..........16 dsmCleanUp ..............72 Using Signals..............17 dsmDeleteAccess ............73 Starting or Ending a Session .........17 dsmDeleteFS ..............74 Session Security ............18 dsmDeleteObj .............75 Using Passwordaccess Generate Without TCA . 21 dsmEndGetData .............77 Administrative User ..........22 dsmEndGetDataEx ............78 Identifying the Object ...........23 dsmEndGetObj .............79 Filespace Name ............23 dsmEndQuery .............80 High-Level and Low-Level Names......24 dsmEndSendObj.............81 Object Type .............24 dsmEndSendObjEx ............82 Object ID ..............24 dsmEndTxn ..............83 Accessing Objects ............25 dsmEndTxnEx .............85 © Copyright IBM Corp. 1993, 2002 iii dsmGetData ..............87 Appendix E. The X/Open API .....215 dsmGetNextQObj ............88 Introduction ..............215 dsmGetObj ..............90 Version 3.7.2 Changes ..........215 dsmGroupHandler ............91 Setting Up Options Files..........216 dsmInit ................92 Using the TSM X/Open API Sample Application 216 dsmInitEx ...............95 Build the Sample Application .......216 dsmLogEvent..............99 Using the TSM X/Open API ........218 dsmLogEventEx ............100 Data Field Mapping ..........219 dsmQueryAccess ............102 Maintaining Version Control in the API . 219 dsmQueryApiVersion...........103 Starting Or Ending a Session .......220 dsmQueryApiVersionEx ..........104 Session Security ...........221 dsmQueryCliOptions ...........105 Determining the Session Parameters .....221 dsmQuerySessInfo............106 Associating a Management Class With Objects 222 dsmQuerySessOptions ..........107 The Transaction Model .........223 dsmRCMsg ..............108 Querying the TSM System ........223 dsmRegisterFS .............109 Sending Data to a Server ........225 dsmRenameObj.............110 Receiving Data from a Server .......228 dsmSendData .............112 Deleting Objects from the Server ......230 dsmSendObj..............114 Identifying the Object .........231 dsmSetAccess .............118 Setting the Owner Name ........232 dsmSetUp ..............120 Using XOpen Functions With TSM ......234 dsmTerminate .............122 TSM Changes to the XBSA Header Files ....235 dsmUpdateFS .............123 Changes to custom.h ..........235 dsmUpdateObj .............124 Changes to xbsa.h ...........235 Changes to policy.h ..........236 Appendix A. API Type Definitions Source File ............127 Appendix F. Notices ........237 Trademarks ..............239 Appendix B. API Function Definitions Source File ............169 Glossary .............241 Appendix C. API Return Codes Source Index ...............249 File ................181 Appendix D. API Return Codes With Explanations............193 iv TSM Using the API Figures 1. An Example of Obtaining the Version Level of 13. Flowchart for Backup and Archive Operations 38 theAPI..............16 14. An Example of Sending Data to a Server 40 2. An Example of Starting and Ending A Session 20 15. Example of Pseudo-code to Create a Group 43 3. Details of rcApiOut ..........21 16. An Example of Sorting Objects With the 4. An Example of Changing A Password . 21 Restore Order Fields .........46 5. An Example of Working With File Spaces, Part 17. State Diagram for Restore and Retrieve 1................27 Operations .............50 6. An Example of Working With File Spaces, Part 18. Flowchart for Restore and Retrieve Operations 50 2................28 19. An Example of Receiving Data from a Server 51 7. An Example of Working With File Spaces, Part 20. Summary State Diagram for the API ....54 3................28 21. An Example of BSAGetEnvironment ....222 8. An Example of Associating A Management 22. Flowchart for Query Operations .....225 Class With An Object .........30 23. Flowchart for Backup and Archive Operations 227 9. State Diagram for General Queries .....31 24. Flowchart for Restore and Retrieve 10. Flowchart for General Queries ......32 Operations ............230 11. An Example of Performing a System Query 32 25. Flowcharts for Delete Archive (left) and 12. State Diagram for Backup and Archive Deactivate Backup (right) Operations . 231 Operations .............37 © Copyright IBM Corp. 1993, 2002 v vi TSM Using the API Tables 1. Description of Syntax Diagram Items ....x 23. Return Codes for dsmEndGetObj .....79 2. Tivoli Storage Manager Client Manuals xii 24. Return Codes for dsmEndSendObj .....81 3. Configuration Sources in Order of Decreasing 25. Return Codes for dsmEndSendObjEx ....82 Priority ..............2 26. Return Codes for dsmEndTxn ......84 4. API Environment Variables........3 27. Return Codes for dsmEndTxnEx .....86 5. Files That You Need to Build the NetWare API 28. Return Codes for dsmGetData ......87 Sample Application ..........5 29. DataBlk Pointer Structure ........88 6. Files That You Need to Build the OS/400 API 30. Return Codes for dsmGetNextQObj ....89 Sample Application ..........7 31. Return Codes for dsmGetObj ......90 7. Files That You Need to Build the UNIX API 32. Return Codes for dsmGroupHandler ....91 Sample Application ..........8 33. Return Codes for dsmInit ........94 8. Files That You Need to Build the Windows 34. Return Codes for dsmInitEx .......97 32–bit API Sample Application ......9 35. Return Codes for dsmLogEvent ......99 9. Files That You Need to Build the Windows 36. Return Codes for dsmLogEventEx ....101 64–bit API Sample Application ......10 37. Return Codes for dsmQuerySessInfo 106 10. Design Recommendations........13 38. Return Codes for dsmRCMsg ......108 11. Platform Information .........14 39. Return Codes for dsmRegisterFS .....109 12. Summary of User Access to Objects ....25 40. Return Codes for dsmRenameObj .....111 13. Information Returned on the dsmBindMC Call 29 41. Return