Implementing TWS Extended Agent For Tivoli Storage Manager

Implementing TWS Extended agent for Tivoli Storage Manager
Insiders guide to writing a TWS Extended agent Ready-to-use solution for TSM and TWS integration TSM Extended agent code included
Vasfi Gucer Henry Daboub Warren Gill Denise Kikumoto Tina Lamacchia
ibm.com/redbooks
SG24-6030-00
International Technical Support Organization Implementing TWS Extended agent for Tivoli Storage Manager
March 2001
Take Note! Before using this information and the product it supports, be sure to read the general information in Appendix C, Special notices on page 89.
First Edition (March 2001) This edition applies to Tivoli Workload Scheduler 7.0 and Tivoli Storage Manager 4.1 Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. JN9B Building 003 Internal Zip 2834 11400 Burnet Road Austin, Texas 78758-3493 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 2001. All rights reserved. Note to U.S Government Users Documentation related to restricted rights Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 TWS overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.1 Software configurations used for this redbook . . . . . . . . . . 1.1.2 TWS concepts and terminology . . . . . . . . . . . . . . . . . . . . . 1.1.3 TWS architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.4 Extended agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 TSM overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.1 What are the benefits of a TSM Extended agent for TWS? . 1.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2. Extended agent functions 2.1 Introduction . . . . . . . . . . . . . . . . . . 2.2 Workstation definition . . . . . . . . . . . 2.3 Method options file . . . . . . . . . . . . . 2.4 Access method interface . . . . . . . . 2.4.1 Method command line syntax . 2.4.2 Task options . . . . . . . . . . . . . . 2.4.3 Example . . . . . . . . . . . . . . . . . 2.5 Method response messages . . . . . . 2.6 Execution and troubleshooting . . . . 2.6.1 Executing the method . . . . . . . 2.6.2 Killing a job. . . . . . . . . . . . . . . 2.6.3 Method troubleshooting . . . . . 2.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 . .1 . .2 . .2 . .3 . .4 . .7 . .9 . 10
. . . . . . . . . . . . . . 13 . . . . . . . . . . . . . . 13 . . . . . . . . . . . . . . 13 . . . . . . . . . . . . . . 14 . . . . . . . . . . . . . . 15 . . . . . . . . . . . . . . 15 . . . . . . . . . . . . . . 16 . . . . . . . . . . . . . . 18 . . . . . . . . . . . . . . 20 . . . . . . . . . . . . . . 21 . . . . . . . . . . . . . . 21 . . . . . . . . . . . . . . 21 . . . . . . . . . . . . . . 21 . . . . . . . . . . . . . . 22
Chapter 3. Case study - TSM Extended agent . . . . . . . . . . . . . . . . . . . 23 3.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Chapter 4. Sample scenarios . . . . . . . 4.1 Description of the scenarios . . . . . . 4.1.1 Database backup . . . . . . . . . . 4.1.2 Backup device configuration . . 4.1.3 Backup volume history . . . . . . 4.1.4 Clean volume history . . . . . . . 4.1.5 Expiration process . . . . . . . . . 4.1.6 Reclamation process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . 43 . 43 . 43 . 63 . 64 . 65 . 66 . 67
iii
4.1.7 Migration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 4.1.8 Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 4.2 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Appendix A. TSW Extended agent for TSM source code. . . . . . . . . . . . 71 Appendix B. Using the additional material . . . . . . . . B.1 Locating the additional material on the Internet . . . . . B.2 Using the Web material. . . . . . . . . . . . . . . . . . . . . . . . B.2.1 How to use the Web material . . . . . . . . . . . . . . . ....... ....... ....... ....... ...... ...... ...... ...... .. .. .. .. 87 87 87 87
Appendix C. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Appendix D. Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 D.1 IBM Redbooks collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 D.2 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 D.3 Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 IBM Redbooks fax order form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 IBM Redbooks review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
iv
Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. Extended agent network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Extended agent processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Extended agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Requesting a backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Verifying that a backup was unsuccessful . . . . . . . . . . . . . . . . . . . . . . . . . 25 Backing up a storage pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Reclamation in the tape device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Migration process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Device configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Maestro (TWS) Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Maestro (TWS) Composer window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 List of jobs scheduled on your server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Changing job definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Maestro (TWS) Console Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Jobs scheduled on TWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Right-click to see the status of the job . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Status of the job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Maestro (TWS) Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Select Jobs to create a new job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Select the CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 New Job window for database backup . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Job definition window for Database Backup . . . . . . . . . . . . . . . . . . . . . . . 47 List of jobs, including BACKUPDB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Selecting Schedules to add a new schedule . . . . . . . . . . . . . . . . . . . . . . . 48 Creating a new schedule for database backup . . . . . . . . . . . . . . . . . . . . . 49 Defining a new schedule for database backup . . . . . . . . . . . . . . . . . . . . . 50 New schedule - backup db. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 On/Except window to definite the new schedule . . . . . . . . . . . . . . . . . . . . 51 Options to define a new schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Follows Sched/Job window for database backup . . . . . . . . . . . . . . . . . . . 53 Opens Files window for database backup . . . . . . . . . . . . . . . . . . . . . . . . . 54 Needs resources window for database backup . . . . . . . . . . . . . . . . . . . . . 55 Jobs window for database backup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Adding jobs to the Current Jobs list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 New schedule on the List of Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Selecting Conman from the Maestro (TWS) Main Window . . . . . . . . . . . . 58 BACKUPDB schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Standard output for database backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Checking the status of a job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Stdlist for BACKUPDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
41. 42. 43. 44. 45. 46. 47. 48.
Job Definition window for storage pool backup . . . . . . . . . . . . . . . . . . . . . 62 Job Definition window for backup device configuration . . . . . . . . . . . . . . . 64 Job Definition window for backup volume history . . . . . . . . . . . . . . . . . . . 65 Job Definition window for clean volume history . . . . . . . . . . . . . . . . . . . . . 66 Job Definition window for the expiration process. . . . . . . . . . . . . . . . . . . . 67 Job Definition window for the reclamation process . . . . . . . . . . . . . . . . . . 68 Job Definition window for the migration process . . . . . . . . . . . . . . . . . . . . 69 Job Definition window for restore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
vi
Tables
1. Task types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2. Task options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Copyright IBM Corp. 2001
vii
viii
Preface
Tivoli Workload Scheduler (TWS) is Tivolis strategic, multiplatform distributed scheduling product, providing high-volume, complex scheduling capability. Although TWS provides native support for many platforms and applications, it is possible to extend its robust scheduling capabilities to cover additional platforms and applications. Writing an Extended agent accomplishes this. This redbook will show you how to write a TWS Extended agent. The Extended agent allows you to schedule on platforms and applications for which TWS has no native agent. Using the Extended agent, you can integrate Tivoli Storage Manager (TSM) with TWS. TWSs scheduling facility allows you to assign dependencies among TSM-scheduled tasks or to assign limits or priorities. By extending TWS to schedule these TSM tasks, you can take advantage of its advanced scheduling capabilities. This redbook will be essential for those who will write a TWS Extended agent or who will use TWS to schedule TSM functions.
The team that wrote this redbook

This redbook was produced by a team of specialists from around the world working at the International Technical Support Organization (ITSO), Austin Center. Vasfi Gucer is a Project Leader at the ITSO, Austin Center. He worked with IBM Turkey for 10 years and has been with the ITSO since January 1999. He has more than eight years of experience in systems management, networking hardware, and distributed platform software. He has worked on various Tivoli customer projects as a systems architect in Turkey and the U.S. Vasfi is also a Certified Tivoli Consultant. Henry Daboub is currently a member of the Tivoli Customer Support Global Response Team (GRT). The GRT provides on-site support to Tivoli customers with an emphasis on large environments. Henry has more than 12 years of experience in software development and support, and has supported IBM workload management products since 1997. Warren Gill is the Product Marketing Manager for TWS and Tivoli Operations Planning and Control. He has been a courseware designer and trainer for TWS and its predecessor Maestro, as well as a customer support engineer.
ix
Warren has been with Tivoli Systems since December 1997, when Tivoli acquired Unison Software. He has been using TWS since 1990. Denise Kikumoto is an IT specialist working for IBM Brazil since May 1997. She is responsible for AIX server and Lotus Notes administration. She also has extensive experience with TSM. She holds a degree in systems analysis. Tina Lamacchia has been in the IT realm for 18 years. Her career started with programming, and then administrating hundreds of UNIX systems. She has been with Tivoli Systems for more than three years. She has worked with TWS for two years and managed a TWS support team. Prior to joining Tivoli Systems, she was a TWS customer for three years and deployed the product set (including SAP Extended agent) in an Enterprise Systems Management (ESM) environment. Currently she is working in the GRT to assist ESM customers with various deployments in TWS and Tivoli Management Environment (TME). Thanks to the following people for their invaluable contributions to this project: Tivoli Systems, International Technical Support Organization, Austin Center Sergio Juri, Richard Harrison, Cesare Pagano IBM, International Technical Support Organization, Austin Center Leah Nelson
Comments welcome
Your comments are important to us! We want our redbooks to be as helpful as possible. Please send us your comments about this or other redbooks in one of the following ways: Fax the evaluation form found in IBM Redbooks review on page 103 to the fax number shown on the form. Use the online evaluation form found at ibm.com/redbooks Send your comments in an Internet note to redbook@us.ibm.com
Chapter 1. Introduction
This redbook is designed to illustrate the implementation of a Tivoli Workload Scheduler (TWS) Extended agent. The implementation the redbook team designed facilitates a communication between TWS V7.0and Tivoli Storage Manager (TSM) V4.1 to initiate regularly scheduled tasks on the TSM server. TSMs server-prompted scheduling facility allows us to initiate client backups on machines defined as TSM clients in server-prompted scheduling mode.
1.1 TWS overview

TWS is a multiplatform distributed scheduling system that provides high-volume, complex scheduling capability. A powerful scheduling language allows for precise coding of job streams with dependencies on other jobs, files, virtual resources, operator prompts, and jobs in other scheduling environments. A Java-based graphical user interface (GUI) known as the Job Scheduling Console (JSC) provides the user with the option of a dialog-based graphical interface. JSC allows a user: to create/modify scheduling objects, to create an execution plan for a batch workload, and to monitor/manage the plan when it is executing. The more experienced user can use a command line interface (CLI) for monitoring, scheduling, or troubleshooting. An application programming interface (API) allows TWS to be integrated with any application with a scheduling facility of its own. This redbook explores that interface. Chapter 5 of the Tivoli Workload Scheduler 7.0 Reference Guide, GC32-0424 provides an overview of the TWS Extended agent API. There are two basic aspects to job scheduling in TWS: the database and the plan. The database contains all the definitions for scheduling objects (for example, jobs, job streams, resources, and workstations). It also holds statistics about job and job stream execution, as well as information on the user ID that created an object and when an object was last modified. The plan contains all job scheduling activity planned for a one-day period. In TWS the plan is created every 24 hours and consists of all the jobs, job streams, dependencies, and other scheduling objects referenced in the upcoming day. All job streams for which you have created a run cycle are automatically scheduled and included in the plan. At the end of the day, the jobs and job streams not successfully executed can be rolled over into the next days plan.
1.1.1 Software configurations used for this redbook

An IBM RS/6000 43P workstation running AIX V4.3.3.0 was used in the development of this redbook. The following software was loaded onto this system: Tivoli Workload Scheduler V7.0 Tivoli Management Framework V3.7 Tivoli Job Scheduling Services V1.1 Tivoli TWS Connector V7.0 Tivoli Storage Manager V4.1 for AIX
1.1.2 TWS concepts and terminology

TWS uses these important concepts: Job streams and calendars The job streams created using the JSC are central to TWSs ability to manage batch job execution. Each job stream is scheduled to run on a specific set of dates and times, and consists of a list of jobs that execute as a unit (such as the weekly backup application), along with times, priorities, and other dependencies that determine the exact order of execution. Job streams are dated using actual dates, days of the week, or calendars. A calendar is a set of specific dates. You can create as many calendars as required to meet your scheduling needs. For example, you can define a calendar named PAYDAYS containing a list of pay dates, a calendar named MONTHEND containing a list of each last business day of the month for the current year, and a calendar named HOLIDAYS containing a list of your companys holidays. At the start of each processing day, TWS automatically selects all the job streams that run on that day, and carries forward uncompleted job streams from the previous day. Workstations A workstation is usually an individual computer on which jobs and job streams are executed. A workstation definition is required for every computer that executes jobs in the TWS network. Workstation definitions primarily refer to physical workstations. However, in the case of Extended agents and network agents, the workstations are logical definitions that must be hosted by a physical TWS workstation.
There are several types of workstations in a TWS network: Master Domain Manager The Domain Manager in the topmost domain of a TWS network. It contains the centralized database files used to document scheduling objects. It creates the production plan at the start of each day, and performs all logging and reporting for the network. Domain Manager A Domain Manager acts as a repeater, which allows TWS to scale to large numbers of machines. The Domain Manager forwards messages between the Master Domain Manager and the agents. Backup Master A Fault-tolerant Agent (FTA) capable of temporarily assuming the responsibilities of its Domain Manager in a failover situation. This is enabled by marking the workstation as Full Status and Resolve Dependencies. Fault-tolerant Agent A workstation capable of resolving local dependencies and launching its jobs in the absence of a Domain Manager. The FTA is initialized at the beginning of the production day with all of the scheduling objects needed to perform the assigned workload. Standard agent A workstation that launches jobs only under the direction of its Domain Manager. Each job launch on the standard agent is directed in real time by the Domain Manager or Master. Extended agent A logical workstation definition that enables you to launch and control jobs on other systems and applications, such as PeopleSoft, Oracle Applications, SAP R/3, and MVS JES2 and JES3. Users can also write Extended agents, as presented in this redbook. Network agent A logical workstation definition for creating dependencies between jobs and job streams in separate TWS networks.
1.1.3 TWS architecture

The Master Domain Manager contains the centralized database files used to store scheduling objects. It creates the production plan at the start of each day, distributes the plan to the FTAs and Domain Managers in the Master Domain, and logs all transactions on the TWS network.
All communications to agents are routed through the Domain Manager, which is the management hub in a domain. The network can be managed by a mix of agents. FTAs are capable of resolving local dependencies and launching jobs should a network interruption cause them to lose communication with their Domain Managers. They can do this because each one is given a set of scheduling instructions at the beginning of every processing day. Version 7.0 introduced a new Java GUI: the Job Scheduling Console (JSC). The JSC provides a common interface to both TWS and Operations, Planning and Control (OPC).
1.1.4 Extended agents

TWS Extended agents are programs that allow TWS to manipulate and to get information about objects in other scheduling environments. Extended agents use open scheduling APIs and protocols, and they provide an effective mechanism for extending TWSs scheduling capabilities to foreign platforms and applications. Extended agents also allow segregation of applications at the workstation level by providing an alternative method other than jobmanrc process. This allows some applications to be treated differently using an alternative job scheduling method. The connection between TWS and an Extended agent is shown in Figure 1. The Extended agent is installed on one of the TWS hosts. TWS accepts information from the Extended agent. The interface between TWS and an Extended agent is called the access method. The access method is a shell script or program which resides in ~TWSHOME/methods directory. .
Figure 1. Extended agent network
Extended agent processing is explained in Figure 2. The sequence of operations is as follows:

Note
This explanation does not consider network communication issues. It is accepted that the Extended agent resides on a TWS server. If the Extended agent resides on an FTA, the sequence of operations for communication with the Extended agent will be the same but there will be additional processes for communication between the TWS Master and the FTA. 1. 2. 3. 4. 5. 6. 7. 8. Batchman process on the FTA talks to the jobman (jobman.exe on an NT system), which is owned by the root user ID. Jobman invokes JOBMAN (jobmon.exe on an NT system) process in the context of the TWS user (maestro, for example). JOBMAN talks to the access method. The access method invokes a Remote Function Call (RFC). The access method consults with the <method.opts> file. The access method talks to the system or the applications job. The access method and the job communicate with each other. The method passes the information back to the TWS host through JOBMAN.
Figure 2. Extended agent processing
The JOBMAN process launches the access method script to perform one of these tasks: Launch a job Manage a job Check for the existence of a file to satisfy an OPENS dependency Get the status of an external job The syntax of the method execution is as follows:
methodname -t task options -- taskstring
where:
task:
Is one of the following: Launch a job (LJ) Manage a previously launched job (MJ) Check availability of a file OPENS dependency (CF) Get the status of an external job (GS)
options: taskstring:
Are the list of job properties. Is the string to execute from the job definition.
The following are the options (related with the jobs properties) that should be passed to the access method: Workstation/Host/Master Workstations node definition Workstations port definition The current production run number The jobs run number The jobs schedule name The date of the schedule (in two formats) The user ID (logon) for the job The path to the output (stdlist) file for the job The job ID The job number The string from the SCRIPTNAME or DOCOMMAND entry in the job definition
An example method invocation is as follows, where job TEST is executed on the Extended agent workstation itso6 using the user ID itso and method name wgetmethod:
wgetmethod -t LJ -c ITSO6,ITSO7,ITSO7 -n ITSO6 -p 31111 -r 143,143 -s MACDSH91 -d 20000410,955381986 -l itso -o /opt/maestro/stdlist/2000.04.10/O13676.1053 -j TEST,13676 -- /home/itso//batchjobs/killer
The current Extended agents TWS provides are: UNIX Remote Shell UNIX Local MVS (JES,OPC, CA7) SAP R/3 Batch PeopleSoft Oracle Applications
Note
In addition to TWS-provided Extended agents, you can always write your own Extended agents for platforms or applications thatare not TWS supported using the open API that is documented in the Tivoli Workload Scheduler 7.0 Reference Guide, GC32-0424.
1.2 TSM overview

TSM is an end-to-end, scalable storage management solution spanning palm tops to mainframes on more than 35 platforms. Its features include: Centralized storage management Storage Area Network (SAN) features, such as LAN-free backup and tape sharing Automated network incremental and subfile backup, archive, and retrieval Fast recovery time Space management file migration
High speed policy-based disaster recovery Data protection offered for most popular groupware, e-mail, databases, and applications TSM is the core product of the Tivoli Storage Management product set. It provides a solution for distributed data and storage management in an enterprise network environment. It is the next generation of the product originally released by IBM as ADSTAR Distributed Storage Manager (ADSM). The base functions TSM and its complementary products provide are: Data protection, including: - Operational backup and restore of data: The backup process creates a copy of the data protect against the operational loss or destruction of file or application data. The customer defines how often to back up (frequency) and how many numbers of copies (versions) to hold. The restore process places the backup copy of the data into a customer-designated system or workstation. - Disaster recovery: All activities to organize, manage, and automate the recovery process from a major loss of IT infrastructure and data across the enterprise. This includes processes to move data offsite into a secure vault location, to rebuilt IT infrastructure, and to reload data successfully in an acceptable time frame. Storage resource management, including: - Vital record retention, archive, and retrieval: The archive process creates a copy of a file or a set of files representing an endpoint of a process for long-term storage. Files can remain on the local storage media or can be deleted. The customer controls how long (retention period) an archive copy is to be retained. The retrieval process locates the copies within the archival storage and places them into a costumer designated system or workstation. - Hierarchical space management: This process provides the automatic and transparent movement of operational data from the user system disk space to a central storage repository. If the user accesses this data, it is dynamically and transparently restored to the client storage.
1.2.1 What are the benefits of a TSM Extended agent for TWS?
TSM administrators must perform several types of operations regularly each day. TSM contains a built-in scheduling facility, which provides a simple mechanism to automate routine tasks. This scheduling facility does not provide the ability to assign dependencies among scheduled tasks or to assign limits or priorities. By extending TWS to schedule these tasks, you can take advantage of its advanced scheduling capabilities. The following common TSM tasks were implemented for this example: Database backup (BACKUP DB) Volume history backup (BACKUP VOLHISTORY) Device configuration backup ( BACKUP DEVCONFIG) Delete volume history ( DELETE VOLHISTORY) Inventory expiration ( EXPIRE INVENTORY) Client backup All TSM tasks executed by the TSM Extended agent ( tsmxagent), use the TSM Administrative Client Interface ( dsmadmc). The user ID used to log in to the dsmadmc interface is fetched from the tsmAdmin variable in the tsmxagent.opts file in the TWS methods directory. The password is retrieved from the TWS parameter object named TSMPASS. Client backups are performed as follows: A schedule is defined to run a backup immediately (DEFINE SCHEDULE). The schedule is associated with the client specified (DEFINE ASSOCIATION). The schedule is monitored until completion or timeout ( QUERY EVENT). The schedule is deleted ( DELETE SCHEDULE). The status is reported to TWS. As shown in Figure 3 on page 10, Extended agents are used to extend the job scheduling functions of TWS to other systems and applications.
Extended agent Host
External system or application
TWS network
Figure 3. Extended agent
An Extended agent is defined as a workstation that has a host and an access method. The host is any other workstation, except another Extended agent. The access method is a Tivoli-supplied or user-supplied script or program that the host executes whenever the Extended agent is referenced in the production plan. For example, to launch a job on an Extended agent, the host executes the access method, passing it job details as command line options. The access method communicates with the external system or application to launch the job and return the status of the job. Each Extended agent must have a logical workstation definition. This logical workstation must be hosted by a TWS physical workstation, either a Master, Domain Manager, or FTA workstation. The Extended agent workstation definition references the name of the access method and the host workstation. When jobs are launched on the Extended agent workstation, the access method is called and passes the job information to the external system. For an example of defining an Extended agent workstation, see the Tivoli Workload Scheduler 7.0 Users Guide, GC32-0423.
1.3 Summary
TWS is a multiplatform distributed scheduling program that provides high-volume, complex scheduling capability for many systems and applications. Master Domain Manager, Domain Manager, Backup Master, Fault-tolerant Agent and standard agent are various types of workstations in a TWS network. You can extend the number of platforms and applications TWS supports by writing TWS Extended agents which allow TWS to manipulate and to get information about objects in other scheduling environments.
10
TSM is a scalable storage management solution spanning palm tops to mainframes on more than 35 platforms. Centralized storage management, LAN-free backup and tape sharing, and automated network incremental and subfile backup, archive, and retrieval are some of the important functions that TSM provides.
11
12
Chapter 2. Extended agent functions

This chapter describes the functions of the Tivoli Workload Scheduler (TWS) Extended agent method, the access method interface and the communications protocols between jobs running within an access method.
2.1 Introduction
The Extended agent is defined as a workstation that has a host and an access method. The host is any other TWS workstation, except another Extended agent. The access method is a Tivoli-supplied or user-supplied script or program that the host executes whenever the Extended agent is referenced in the production plan. For example, to launch a job on an Extended agent, the host executes the access method, passing it job details as command line options. The access method communicates with the external system or application to launch the job and return the status of the job.
2.2 Workstation definition

Each Extended agent must have a logical workstation definition. This logical workstation must be hosted by a TWS physical workstation, either a Master, Domain Manager, or FTA workstation. The Extended agent workstation definition references the name of the access method and the host workstation. Workstation definitions are created using the command line interface, Composer, or Job Scheduling Console (JSC). When jobs are launched on the Extended agent workstation, the access method is called and passes the job information to the external system. Suppose, for the purpose of illustration, that you have a TWS network comprised of three workstations: a Master workstation (called Copernicus), a Fault-tolerant Agent (FTA) workstation (Kepler), and an Extended agent workstation (Galileo). The following is an example of the Extended agent workstation definition:
CPUNAME galileo OS OTHER NODE focus TCPADDR 1609 FOR MAESTRO HOST kepler ACCESS nuncius
13
END
In this case, Galileo is the name of the Extended agent workstation, focus is the node name, 1609 is the TCP address, Kepler is the host, and nuncius is the name of the access method. An executable file (script or program) named nuncius must reside in the /methods subdirectory of the TWS installation. For Extended agents only, the node and tcpaddr definitions are left to the method developer to define. In other words, depending on the nature of the access method, node might have different uses.
2.3 Method options file

By default, when executing an Extended agent job, TWS tries to execute the method file as the logon defined for each job to be run by the method. When executing the method script to check for an OPENS dependency (using the check file [CF] task) TWS executes the method as root by default. You can change this behavior by using a method options file to specify special login information and other options for your access method. For example, you may wish to use the logon field of your agents job definitions to represent a logon to a foreign system that does not exist on the Extended agents host. TWS reads the file, if it exists, before executing a method. If the file is modified after TWS is started, the changes take effect when it is stopped and restarted. The file can contain TWS options and any other method information you wish to include. The options recognized by TWS are:
LJuser=username CFuser=username
where:
LJuser=username:
Specifies the login to use for the launch job (LJ) and manage job (MJ) tasks. The default is the login from the job definition. Specifies the login to use for the CF task. The default is root for UNIX, and for Windows NT it is the user name of the account in which TWS was installed.
CFuser=username:
14
Note
If the Extended agents host is a Windows NT computer, these users must be defined as TWS user objects. The options file must have the same path name as its access method, with an .opts file extension. For example, the Windows NT path name of an options file for a method named nuncius is WShome\methods\nuncius.opts.
2.4 Access method interface

The interface between TWS and an access method consists of information passed to the method on the command line, and messages returned to TWS in stdout.
2.4.1 Method command line syntax

The TWS host runs an access method using the following command line syntax:
methodname -t task options -- taskstring
where:
methodname:
Specifies the file name of the access method. In our example, this is nuncius. All access methods must be stored in the WShome/methods directory. Specifies the task to be performed, where task is one of the options listed in Table 1 on page 16:
-t task:
15
Table 1. Task types
Task LJ
Description Launches a job. The access method is called with this task option when TWS launches a job. TWS will expect the access method to continue running until the job it executes is complete. Manages a previously launched job. Use this option to synchronize job(s) if a prior LJ task terminated unexpectedly. The MJ method is called for under only a few circumstances. For example, TWS or its batchman process terminates (an operator issues a Conman STOP command to the agents host) while an Extended agent job is running. When the TWS processing is restarted, it will execute the Extended agents access method for each job that was previously running, passing it the MJ task and the same arguments initially sent to the job. The access method should use the MJ task to determine the state of the previously running job and report that state back to TWS. Checks the availability of a file. Use this option to check file OPENS dependencies. Using the Galileo workstation example, if a schedule contained the dependency (OPENS GALILEO#/this/is/my/file) TWS would call the access method for Galileo and pass it the CF task and the path (/this/is/my/file).
MJ
CF
options:
Specifies the options associated with the task. See Section 2.4.2, Task options on page 16 for more information. A string of up to 255 characters associated with the task. See Section 2.4.2, Task options on page 16 for more information.
taskstring:
2.4.2 Task options

The task options are listed in Table 2. An x means the option is valid for the task.
Table 2. Task options
Task -t LJ MJ CF
Options -c x x x -n x x x -p x x x -r x x -s x x -d x x -l x x -o x x -j x x x -q
Task string
ljstring mjstring cfstring
16
-c xagent,host,master:
Specifies the TWS names of the Extended agent, the host, and the Master Domain Manager, separated by commas. Specifies the node name of the computer associated with the Extended agent, if any. This is defined in the Extended agents workstation definition node field. Specifies the TCP port number associated with the Extended agent, if any. This is defined in the Extended agents workstation definition TCP Address field. Specifies the current run number of TWS and the specific run number associated with the job, separated by a comma. The current and specific run numbers might be different if the job is carried forward from an earlier run. Specifies the name of the jobs job stream. Specifies the schedule date (yymmdd) and the epoch equivalent, separated by a comma. Specifies the jobs user name. This is defined in the job definition Logon field. Specifies the full path name of the jobs standard list file. Any output from the job must be written to this file. Specifies the jobs name and the unique identifier assigned by TWS, separated by a comma. The name is defined in the job definition Job Name field. Specifies the qualifier to be used in a test command issued by the method against the file. Used with the LJ task. The string from the script file or command field of the job definition.
-n nodename:
-p portnumber:
-r currentrun,specificrun:
-s jstream: -d scheddate,epoch:
-l user: -o stdlist:
-j jobname,id:
-q qualifier:
-- ljstring:
17
-- mjstring:
Used with the MJ task. The information provided to TWS by the method in a %CJ response to an LJ task. Usually, this identifies the job that was launched. For example, a UNIX method can provide the process identification (PID) of the job it launched, which TWS sends as part of an MJ task. Used with the CF task. For a file OPENS dependency, the string from the Opens Files field of the job stream definition.
-- cfstring:
2.4.3 Example
Using our previous workstation definition and the options previously listed, here is an example of how your access method would be called from TWS. In this example, a job defined as tsmjob1 runs the command ADMIN VHBACKUP /opt/tsm/dat/fa20001020 in the job stream (schedule) DAILYBAK:
/opt/maestro/methods/nuncius -t LJ -c GALILEO,KEPLER,COPERNICUS -n focus -p 1609 -r 109,109 -s DAILYBAK -d 20001207,976147200 -l root -o /opt/maestro/stdlist/2000.12.07/O9041.1414 -j TSMJOB1,9041-- ADMIN VHBACKUP /opt/tsm/dat/fa20001020
Let us examine the command structure from the example.

/opt/maestro/methods/nuncius
This is the directory to the access method script.

-t LJ
The task option LJ was sent, indicating that a job is being run.
-c GALILEO,KEPLER,COPERNICUS
This option shows that Galileo is the Extended agents name, Kepler is the agents hosts name, and Copernicus is the TWS Masters name.
-n focus
Focus is the node name of the Extended agent. This name comes directly from the workstation definition for Galileo.
18
-p 1609
The number 1609 is the tcpaddr port definition from the workstation definition for Galileo.
-r 109,109
The current run number (TWS production day) is 109, as is the jobs run number. If, for example this option was -r 110,109, it would signify that the job stream (schedule) from which this job is running has been carried forward from a previous day.
-s DAILYBAK
The job stream (schedule) name from which this job is running is DAILYBAK.
-d 20001207,976147200
The current scheduling production run date is December 7, 2000. Remember that the scheduling production run date may be different than the actual calendar run date.
-l root
The job run by this method should log on to the system as root. This information comes from the job definition.
-o /opt/maestro/stdlist/2000.12.07/O9041.1414
All output (stdout and stderr) is being redirected to the file /opt/maestro/stdlist/2000.12.07/O9041.1414 on the host workstation.
-j TSMJOB1,9041
The name of the job being run is TSMJOB1, and its job number (as seen in the Conman SHOWJOBS command) is 9041. On UNIX systems only, 9041 is also the parent process ID for this job.
-- ADMIN VHBACKUP /opt/tsm/dat/fa20001020
The rest of the arguments after a double-hyphen are directly from the SCRIPTNAME or DOCOMMAND entry in the TWS job definition. In this case, the application understands the command ADMIN VHBACKUP and processes the command appropriately. Typically the access method ignores any options after the double hyphen and passes them directly to the target application. This is, of course, up to the methods author to determine.
19
Upon execution of this job, its status would be shown in the Console Manager as:
Est) CPU
(Est) Schedule
Job
State Pr Start Elapse Dependencies
GALILEO #DAILYBAK ******** SUCC 10 14:14 01:10 TSMJOB1 SUCC 10 14:14 01:10 #J9041 %
2.5 Method response messages

Methods returns information to TWS in messages written to stdout. Each line starting with a percent sign (%) and ending with a new line is interpreted as a message. The messages have the following format:
%CJ state [mjstring] %JS [cputime] %UT [errormessage]
where:
CJ: state: mjstring: JS [cputime]:
Changes the job state. The state to which the job is changed. All TWS job states are valid except hold and ready. A string of up to 255 characters that TWS will include in any MJ task associated with the job. Indicates successful completion of a job and provides its elapsed run time in seconds. This message must be presented (usually with an echo statement) before the method ends in order for the job to be considered successful. Indicates that the requested task is not supported by the method. Displays a string of up to 255 characters that TWS will include in its error message (stored in the TWS standard list file; typically this file is ~maestro/stdlist/yyyy.mm.dd/MAESTRO).
UT [errormessage]:
You can use these messages within your access method to relay information to the TWS Console Manager. By changing the status of your job, operators can pay special attention to your jobs by filtering their console windows by job status. For example, you might have jobs toggle between wait and exec
20
states by issuing an echo %CJ WAIT or echo %CJ EXEC while the job connects to the application and executes its function.
2.6 Execution and troubleshooting

The Extended agents access method is executed by TWSs jobman process, much as a standard job is launched through jobmanrc.
2.6.1 Executing the method

Before the method is launched, TWS establishes an execution environment for the method: The LJuser parameter is read from the method options file to determine the user account with which to run the method. If the parameter is not present or the options file does not exist, the user account specified in the Logon field of the jobs definition is used. In addition, the following environment variables are set: - HOME: Users home directory - LOGNAME: Login users name (from the job definition) - PATH: For UNIX, /bin:/usr/bin; for Windows, %SYSTEM%\SYSTEM32 - TZ: Time zone
2.6.2 Killing a job

While an access method is running an MJ or LJ task, it should trap a SIGTERM signal (signal 15). This is the signal sent to the job when an operator issues a kill command from the user interface. When a kill signal is caught, the method should attempt to stop or kill the job and exit without writing a %JS message.
2.6.3 Method troubleshooting

If the method cannot be executed, its state is set to fail. All output messages from an access method, except those that start with a percent sign (%), are written to the jobs standard list (stdlist) file. For GS and CF tasks that are not associated with TWS jobs, messages are written to TWSs standard list file. For information regarding a problem of any kind, check these files. For Extended agents, error, warning, and information messages are written to TWSs stdlist file.
21
A successful job launch generates the following message:

Launched job jobname for wkstation ,#J jobid for user username .
Failure to launch a job generates the following message:

Error launching jobname for wkstation :errortext
Failure of a CF task generates the following message:

Error invoking methodname for wkstation :errortext
Failure of an MJ task generates the following message:

Error managing jobname for wkstation using methodname :errortext
When a method sends a message to Jobman that is not recognized, the following message is generated:
Error:message invalid for jobname ,#j jobnumber for wkstation using methodname ."first 64 characters of the offending message "
2.7 Summary
In this chapter we covered the functions of the TWS Extended agent method, the Access Method Interface and the communications protocols between jobs running within an access method. The main functions used in an Extended agent method are: LJ: Launch job MJ: Manage job CF: Check file dependency The Extended agents access method is executed by the jobman process, much as a standard job is launched through jobmanrc.
22
Chapter 3. Case study - TSM Extended agent

This chapter describes scripts that will be useful to Tivoli Workload Scheduler (TWS) and Tivoli Storage Manager (TSM) administrators. These scripts are about TSM processes such as backup, storage pools, migration, reclamation, volume history, and device configuration. Because, in practice, TSM administrators generally schedule these process, it makes sense to write a TSM Extended agent for TWS that incorporates these functions. Using the TSM Extended agent, administrators can schedule these TSM operations through TWS. First, here is some background information about these operations. The following sections should be especially useful if you are not familiar with TSM scheduling operations. Backup database: Use this command to back up a TSM database to sequential access volumes (Figure 4 on page 24). To determine how much additional storage space a backup will require, use the QUERY DB command. This command displays the database pages (in megabytes) that have changed since the last backup. The syntax of the command is:
backup db devclass=dbbackup type=full sctatch=yes wait=yes
where:
backupdb: type=full:
Is the name of the devclass defined on the TSM server. Specifies that you can run the full backup on the TSM database. This parameter is optional. Possible options are: incremental, full and dbsnapshot. The default is incremental. To take the device that is scratch. The default value is yes. This parameter is optional. If you put scratch=no, then it will specify that scratch volume cannot be used. Specifies whether to wait for the server to complete processing this command in the foreground. The default is no. Possible options are: yes (the server processes the command in foreground), and no (the server processes the command in background).
scratch=yes:
wait:
You can find more details about the syntax of the commands in the Tivoli Storage Manager for AIX Administrators Reference, GC35-0404.
23
Backup process
Requests a backup
User
Figure 4. Requesting a backup
TSM server
Library
If a backup completes unsuccessfully, you can verify and restart it. For example, in Figure 5 on page 25 the backup was unsuccessful for some files and restarted.
24
Check .NSF files

Adminstration Server
vasfi.nsf desinha.nsf danes.nsf mcelo.nsf luisv.nsf
vasfi.nsf desinha.nsf vasfi.nsf mcelo.nsf
Backup
danes.nsf mcelo.nsf luisv.nsf
Library
Figure 5. Verifying that a backup was unsuccessful
Backup storage pool: Use this command to back up primary storage pool files to a copy storage pool. The operation is shown in Figure 6 on page 26. If a file already exists in the copy storage pool, the file is not backed up unless the copy is marked as damaged. However, a new copy is not created if the file in the primary storage pool is also marked as damaged. In a random-access storage pool, neither cached copies of migrated files nor damaged files are backed up. If migration for a storage pool starts during a storage pool backup, some files may be migrated before they are backed up. You may want to back up storage pools that are higher in the migration hierarchy before backing up storage pools that are lower. For example, when performing a storage pool backup to copy the contents of a storage pool offsite, if the process is not done according to the existing storage pool hierarchy, some files may
25
not be copied to the copy storage pool. This could be critical for disaster recovery purposes. When performing a storage pool backup on multiple storage pools, the primary storage pool should be completed before the backup process on the next storage pool. The syntax of the command is as follows:
backup stgpool spacemgtpool copypool
where:
spacemgtpool: copypool:
Is the primary backup that you want to back up. Is the copy storage pool defined on TSM server.
Figure 6. Backing up a storage pool
Reclamation: Specifies when the server reclaims a volume, based on the percentage of reclaimable space on a volume (Figure 7 on page 27). Reclamation makes the fragmented space on volumes usable again by moving any remaining active files from one volume to another volume, thus making the original volume available for reuse. You can specify an integer from one to 100. The value 100 means that reclamation is not performed. If you change the value from the default of 100, specify a value of 50 percent or greater so that files stored on two volumes can be combined into a single output volume. To move data from the reclaim storage pool back to the original storage pool, use the storage pool hierarchy. Specify the original storage pool as the next storage pool for the reclaim storage pool. The syntax of the command is as follows:
update stgpool copypool reclaim=50
26
where:
reclaim:
Is the percentage of the reclamation in copypool.
Figure 7. Reclamation in the tape device
Migration: You can use a primary storage pool as the destination for backup files, archive files, or files migrated from client nodes. The following command is used for this purpose:
define stgpool somepool dbbackup pooltype=primary access=readwrite maxsize=nolimt highmigh=90 lowmig=70 migprocess=1 collocate=no migcontinue=yes reusedelay=0 migdelay=0
where:
somepool: dbbackup: pooltype:
Is the pool name defined on the TSM server. Is the device class name defined on the TSM server. Specifies that you want to define a primary storage pool. The default value is primary.
27
access:
Specifies how client nodes and server processes (such as migration and reclamation) can access files in the storage pool. The default value is readwrite, but you can also define as readonly and unavailable. Specifies the maximum size for a physical file size that the server can store in the storage pool during a session with a client. The default value is nolimit. Specifies that the server starts migration for this storage pool when the amount of data in the pool reaches this percentage of the pools estimated capacity. You can specify an integer from zero to 100. The default value is 90. When the storage pool exceeds the high migration threshold, the server can start migration of files by node, to the next storage pool, as defined with the NEXTSTGPOOL parameter. You can specify highmig=100 to prevent migration for this storage pool. Specifies that the server stops migration for this storage pool when the amount of data in the pool reaches this percentage of the pools estimated capacity. You can specify an integer from zero to 99. The default value is 70. When the storage pool reaches the low migration threshold, the server does not start migration of another nodes files. Because all file spaces that belong to a node are migrated together, the occupancy of the storage pool can fall below the value you specified for this parameter. You can set lowmig=0 to permit migration to empty the storage pool. Specifies the number of processes the server uses for migrating files from this storage pool. You can specify an integer from one to 999. The default value is one. During the migration the server runs this number of processes in parallel to provide the potential for improved migration rates. Specifies the minimum number of days a file must remain in a storage pool before the file becomes eligible for migration from the storage pool. The server counts the number of days from the day the file was stored in the storage pool or retrieved by a client, whichever is more recent. The default is zero, which means you do not want to delay migration.
maxsize:
highmig:
lowmig:
migprocess:
migdelay:
28
migcontinue:
Specifies whether you allow the server to migrate files that do not satisfy the migration delay time. The default value is yes. Because you can require that files remain in the storage pool for a minimum number of days, the server may migrate all eligible files to the next storage pool yet not meet the low migration threshold. This parameter allows you to specify whether the server is allowed to continue the migration process by migrating the files that do not satisfy the migration delay time.
Figure 8 shows the migration process.
Migration process
Client
Client TSM server
Disk
Disk Backup
Library
Figure 8. Migration process
Backup device configuration: Use this command to back up the following information in one or more files: - Device class definitions - Library definitions
29
- Drive definitions To restore the TSM database, the device configurations must be available. You can use the devconfig server option to specify one or more files in which to store device configuration information. TSM updates the files whenever a device class, library, or drive is defined, updated, or deleted (Figure 9). The syntax of the command is as follows:
backup devconfig filenames=device
where:
device:
Is the directory that it will back up the information about devconfig.
Device class definitions
Drive definitions Devices Library definitions
Figure 9. Device configuration
Backup volume history: Use this command to back up sequential volume history information to one or more files. You can use volume history information when you reload the database and audit affected storage pool volumes. If you cannot start the server, you can use the volume history file to query the database about these volumes. The volume history includes information about the following types of volumes: - Database backup volumes - Database dump volumes - Export volumes
30
- The following sequential access storage pool volumes: Volumes added to storage pools Volumes reused through reclamation or move-data operations Volumes removed by using the delete volume command or during reclamation of scratch volumes The syntax of the command is:
backup volhistory filenames=volhist
where:
volhist:
Is the name of the filename that will contain information about the volhistory backup.
Delete volume history: Use this command to delete volume history file records that are no longer needed (for example, records for obsolete database backup volumes). When you delete records for volumes that are not in storage pools (for example, database backup or export volumes), the volumes return to Source Manager, which acquires them as scratch volumes. Scratch volumes of device-type files are deleted. When you delete the records for storage pools volumes remain in the TSM database. When you delete records for recovery-plan file objects from a source server, the objects on the target server are marked for deletion. The syntax of the command is as follows:
delete volhistory type=rpfile todate=11/31/00
where:
type:
Specifies the type of records, which also meet the date and their criteria, to delete from the volume history file. Rpfile specifies to delete only records that contain information about full and incremental database backup volumes and recovery plan file volumes. Specifies the date to use to select sequential volume history information to be deleted. TSM deletes only those records with a date on or before the date you specify.
todate:
For more details, you can see the Tivoli Storage Manager for AIX Administrators Reference , GC35-0404.
31
Expire inventory : Use this command to manually start inventory expiration processing. This inventory expiration process removes the client backup and archive file copies from server storage based on the policy specified in the backup and archive copy groups of the management classes to which the files are bound. The inventory expiration process that runs during server initialization does not remove these virtual volumes. Only one expiration process is allowed at any time. If an expiration process is currently running you can not start another process. The syntax of the command is as follows:
expire inventory quiet=no wait=no skipdirs=no duration=40
where:
quiet:
Specifies whether the server suppresses detailed messages about the policy changes during the expiration processing. This parameter is optional. The default value is no, which specifies that the server sends detailed informational messages. You can also put the value yes, which specifies that the server sends only summary messages. Specifies whether to wait for the server to complete processing this command in the foreground. This parameter is optional. Possible values are no, which specifies that the server processes this command in the background, and yes, which specifies that the server processes this command in the foreground. Specifies whether the server skips directory type during the expiration processing. Possible values are: no, which specifies that the server will expire files and directories based upon the appropriate policy criteria, and yes, which specifies that the server will skip directory type objects during expiration processing even if the directories are eligible for expiration. Specifies the maximum number of minutes for the expiration process to run. The process stops when the specified number of minutes have passed or when all eligible expired objects are deleted, whichever comes first. You can specify a number from one to 999,999 (optional).
wait:
skipdirs:
duration:
Restore database : To restore a database or volume to its most current state, the log mode must have been set to roll-forward continuously from the time that the last backup series was created.
32
If the log mode is set to roll-forward after a point-in-time database restoration, a database backup starts when the server is brought up for the first time. This can cause loss of data: A tape can have current data on it, but because of the point-in-time restoration, it can be marked as scratch. When the server starts for the first time, TSM may use this tape to write the database backup, thus destroying the original data on this tape. You can restore a database if the following are true: - The log mode was set to roll-forward continuously from the time the last backup series was created. - An intact recovery log is available. - An intact volume history file is available. TSM requests volume mounts to load the most recent backup series and then uses the recovery log to update the databases to its most current state. If the volume history file is unavailable, you can use one or more dsmc restore db commands to restore the database to a specific point in time. For example, to load a full backup and one or more incremental backups, issue a dsmc restore db command for the full backup and an additional dsmc restore db command for each incremental backup. When you use multiple dsmc restore db commands, specify commit=no for each command except the last one. For the last command, specify commit=yes. The database remains in an inconsistent and unusable state until you issue a dsmc restore db command with a commit=yes. The syntax of the command is as follows:
dsmc restore db devclass=device_class_name volumename=volume_name commit=no
where:
devclass:
Specifies the name of the sequential access device class to use. The device class must be defined in a device configuration file. Possible values are:
volume_name:
volumename: Specifies the backup volume to use to restore the database.
Specifies the names of the volumes. To specify multiple volumes, separate the names with commas without intervening spaces. of the volumes.
file:file_name: Specifies the name of a file that contains a list
33
commit:
Specifies whether this is the last restore command needed to restore the database. This parameter is optional. The default value is no (specifies that you will issue one or more additional dsmc restore db commands), but you can also define the value yes (specifies that this is the last restore command to restore the database).
After you analyze all the scripts, you can also test the environment and commands in the TWS structure. Initially install the TWS software on your system. Decide on which system your Master will be (this is the system on which the TWS database resides, as well as the system on which all updates are received). Please follow the installation steps in the Tivoli Workload Scheduler 7.0 Planning and Installation Guide, GC32-0422. Once the software is installed correctly, make sure your display and path are setup as well. To access the TWS database, execute the gmaestro command (which should be located in the TWShome/bin directory). Make sure you are logged on with the user maestro (default TWS user), or the name of the maestro user you have chosen. Gmaestro contains the Composer screen and the Conman screen. Further details on their functionality is explained in the document. Figure 10 shows the Maestro Main Window the gmaestro command launched.
Figure 10. Maestro (TWS) Main Window
34
You can choose the Database Manager (Composer), which will allow you to enter the CPU, CPU classes, domains, calendars, jobs, and users, or Console Manager (Conman), which displays information about schedules, jobs, CPUs, and parameters. Composer can be accessed from the Master only or wherever the mozart directory is accessible. We do not recommend that the mozart directory is mounted or mapped as the TWS database should not be accessible to all users. Composer reads the mozart directory and the corresponding file pertaining to your choice. At this point you can add, modify, copy, and delete data. Make sure you have the proper security access when performing such operations. Conman displays job status, allows for ad hoc submission, and allows you to display previous production days and their status. Again, all features may be performed if the proper access is given. When you click the Composer button, a window (Figure 11) will appear:
Figure 11. Maestro (TWS) Composer window
You can display, add, and modify information about CPU, CPU classes, domains, and users by clicking the corresponding button. If you choose the Jobs button, you may use the filter feature to list all jobs according to the chosen CPU or you can display all jobs in the TWS
35
database. Clicking the Jobs button, you will see a list of jobs, as seen in Figure 12 on page 36.
Figure 12. List of jobs scheduled on your server
You can execute modifications, additions, deletions, and/or replication (Save As choice) on an existing job. To do that, right-click the desired job, and select Modify. The following window (Figure 13 on page 37) will appear. Follow the instructions to make your changes or just display the job.
36
Figure 13. Changing job definitions
As illustrated, adding a new job should be relatively easy. However, a few explanations are needed in order for you to take full advantage of TWS. With TSM and TWS, you can take advantage of several options to ensure your TSM jobs are successful. The Recovery Options, for instance can be used to ensure that a backup is successfully executed every time. By choosing the Continue option or Rerun option, the Recovery Job and/or Recovery Prompt can be used to ensure backups are always successful. You can key in the recovery job, which may be, for example, another set of tapes to back up to if the primary tapes are not available or a different directory/system if a file system full occurs. Whichever you chose, a backup should always be successful. Also, you can use the Recovery Prompt as a messaging vehicle to the operations staff on the proper execution of the recovery job. The Interactive option is for NT systems within your TWS environment. This option is used if the scheduled job requires manual intervention. In Conman (Console Manager), you can display various information as well as submit ad hoc jobs and schedules. The information is retrieved from the Symphony file located in the maestrohome directory. When you click this button, a window (Figure 14 on page 38) will appear:
37
Figure 14. Maestro (TWS) Console Manager
By double-clicking the buttons, the corresponding information is displayed, as summarized here: CPUs: Status on each TWS system is displayed. The information on its connectivity with the Master, the run number, and the node name are displayed. The exact information can be accessed from the command line interface through the command conman -v. Domains: Displays the Master Domain, the associated Domain Manager, and its parent. Schedules: Displays all schedules along with their status, priority, start times, and dependencies Jobs: Displays all jobs along with their status, priority, start times, and dependencies. Resources: Displays resources and their associated CPUs. Resources can be used when two or more jobs require the use of the same resource, for example a set of tapes (the tape is the resource). Once one job is finished utilizing the one set of tapes or a resource, TWS releases the resource and then next job commences. Prompts: Displays the prompts description, and its associated CPU, schedule, and job.
38
Files: Displays the files with their associated CPUs, schedules, and jobs. All of these features can be used to compliment any Tivoli product, especially TSM. Each feature will be discussed in more detail in Chapter 4, Sample scenarios on page 43. Figure 15 shows you the scheduled jobs.
Figure 15. Jobs scheduled on TWS
You can see the status of the scheduled job by right-clicking. This shows you whether the job was successful, or abended or failed. Also the screen can show you if the job and/or schedule is ready and when it will start, according to start time or dependency columns, which can include resources, files, or other jobs and/or schedules. If a job fails or abends, you can see the reason why it was unsuccessful by right-clicking on the job (Figure 16 on page 40).
39
Figure 16. Right-click to see the status of the job
The Stdlist option allows you to read the log (located in the maestrohome/stdlist/MM.DD.YYYY directory) associated with that job. For further explanation on various other options, please refer to the Tivoli Workload Scheduler 7.0 User's Guide, GC32-0423. Figure 17 shows a sample stdlist output.
Figure 17. Status of the job
40
The stdlist header contains the job name, and associated schedule and CPU names, as well as the login name and the script location. As also shown, it displays the process ID, and the date and time of the job execution. The body of the stdlist contains the steps executed for the job to became successful or unsuccessful. The information contained depends solely on its script and the information to standard out (stdout). You can also print this output.
3.1 Summary
In this chapter we described the following TSM functions that can be scheduled with the TWS: Backup database: To backup a TSM database to sequential access volumes. Backup storage pool: To backup primary storage pool files to a copy storage pool. Reclamation: To reclaim a volume, based on the percentage of reclaimable space on a volume. Migration: To copy files to a library when a threshold is reached on the disk. Backup device configuration: To backup the device class, library and drive definitions. Backup volume history: To backup sequential volume history information to one or more files. Expire inventory: To manually start inventory expiration processing. Restore database: To restore a database or volume to its most current state. The information in this chapter will be especially useful if you are not familiar with TSM scheduling operations.
41
42
Chapter 4. Sample scenarios

This chapter will address several scenarios when utilizing Tivoli Workload Scheduler (TWS) with Tivoli Storage Manager (TSM) product sets. This chapter will demonstrate how to schedule TSM functions within TWS. Primarily we will create jobs and schedules in TWS to handle such functions. We will address dependency options and display jobs/schedules output.
Note
In these scenarios we used the legacy TWS user interface (Composer and Conman) instead of the new Job Scheduling Console (JSC), which was available with the TWS V7.0. The TWS Extended agent for the TSM code we introduce in this redbook is valid for TWS V7.0, and for TWS versions prior to 7.0, in which JSC is not supported.
4.1 Description of the scenarios

The scenarios described involve information about backup databases, backup storage pools, migration, and various other typical scenarios.
4.1.1 Database backup

Our first scenario is database backup. You can specify the type of backup that your company requires. This depends on the necessary datas level of availability for recovery purposes, as well as addressing service level agreements (SLAs) between your company and third party vendors. We will start with scheduling a TSM function in TWS: 1. Execute the TWS interface and choose Composer from the main menu (Figure 18 on page 44).
43
Figure 18. Maestro (TWS) Main Window
2.
From the Scheduling Objects selections, choose Jobs (Figure 19 on page 45).
44
Figure 19. Select Jobs to create a new job
3. 4.
From the Actions menu, choose New Job. Select the CPU definition in which the new job will reside (Figure 20). In TWS, a CPU must be identified with the job or where the backup script resides.
Figure 20. Select the CPU
45
5.
Once you have chosen the associated CPU, type the job name and click OK (Figure 21). The job name should be your identifier for easy ad hoc scheduling as well as monitoring. A naming convention is highly recommended when planning your TWS environment.
Figure 21. New Job window for database backup
6.
Complete the necessary fields of the new Job Definition window (Figure 22 on page 47). Logon refers the user ID that will execute the job (script or command). Enter the script name or the command, making sure the path is included (or the .jobmanrc is present in the users directory. See Tivoli Workload Scheduler 7.0 Planning and Installation Guide, GC32-0422). The path can also be a parameter if necessary (see Tivoli Workload Scheduler 7.0 Users Guide,GC32-0423 for more details on the Parameter object). The Interactive option is for Windows NT jobs to run interactively on the Windows NT desktop. Recovery Options is an important field to consider. When a job does not does not complete successfully (or the state is abended) the entered Recovery Job is executed.
46
Figure 22. Job definition window for Database Backup
7. 8.
Choose File->Save and then File->Close. As jobs are entered in the database, utilizing the View Filter option can help you search for a specific job. The list of jobs is seen in Figure 23 on page 48.
47
Figure 23. List of jobs, including BACKUPDB.
Once a job is defined, it must be entered in an existing or new schedule. The following steps will assist you with schedule definitions: 1. From Composer, choose Schedules (Figure 24).
Figure 24. Selecting Schedules to add a new schedule
48
2.
From the Actions menu, select New, to add a schedule (Figure 25). If you want to change the parameters of an existing schedule, choose Modify.
Figure 25. Creating a new schedule for database backup
3.
If you choose the New schedule option, select the CPU associated with the schedule and enter the schedule name (Figure 26 on page 50). Naming convention methodology is highly recommended for easy monitoring and ad hoc scheduling.
49
Figure 26. Defining a new schedule for database backup
4.
Once the correct information is entered, click OK (Figure 27).
Figure 27. New schedule - backup db
5.
The Schedule Definition window (Figure 28 on page 51) requires various pieces of information.
50
Figure 28. On/Except window to definite the new schedule
6.
Choose the date on which the schedule will execute from the On/Except tab (Figure 28). In our scenario, the schedule will run Everyday. Choose this option. If this was a weekly backup, you would only wish to choose Saturday or Sunday. You can also create a calendar with scheduled dates.
51
Figure 29. Options to define a new schedule
7.
Under the Options tab, enter the schedules run time (Figure 29). Indicate the schedules priority, as well as the limit of jobs running per schedule. Please note that the offset cannot be used at the job and schedule level.
52
Figure 30. Follows Sched/Job window for database backup
8.
The Follows Sched/Job option (Figure 30) is one of the many TWS dependency options. For instance, if this schedule consisted of a job that starts the backup schedule, you may have this schedule and/or job dependent on an existing job that exports the database. This means the backup schedule would only start if the exporting of the database was completed successfully or the job state was SUCC. In the Opens Files tab (Figure 31 on page 54) it is not necessary to enter a file as a dependency for our scenario. Leave this blank.
9.
53
Figure 31. Opens Files window for database backup
10.
Clicking the Needs Resources tab (Figure 32 on page 55), brings up the Needs Resources window. Resources represent physical or logical scheduling resources that can be used as dependencies for jobs and job streams. The resource may be an available device (a tape or tape device). If other schedules/jobs are dependent on the same device, you may use the resource option to run schedules/jobs in a particular sequence.
54
Figure 32. Needs resources window for database backup
11.
The Jobs tab allows the existing job(s) to be defined for the schedule. You must initially select the CPU and the desired job (Figure 33 on page 56).
55
Figure 33. Jobs window for database backup
12.
After selecting the desired job, click the Add button. The job should appear in the Current Jobs column (Figure 34). Repeat this step until all desired jobs are displayed in this column.
Figure 34. Adding jobs to the Current Jobs list
56
13. 14.
When you finish adding jobs, select File->Save, and then File->Close. Your schedule (Figure 35) is now complete and ready to be executed after a Jnextday run, as it will be part of your production Symphony file. If you wish to submit the schedule immediately, you can do this from the Conman window.
Figure 35. New schedule on the List of Schedules
Choose Conman from the main TWS window (Figure 36 on page 58) to execute the new schedule and/or job. The report displays job information and you can use it for various monthly reports.
57
Figure 36. Selecting Conman from the Maestro (TWS) Main Window
Important
You will not be able to display the newly created schedule and/or job until a Jnextday run. The Jnextday script processes the following steps: a. Runs schedulr to select the appropriate schedules for the new day. b. Runs compiler to create an interim Production Control file. c. Runs reptr to print the pre-production reports. d. Stops TWS processing. e. Runs stageman to carry forward uncompleted schedules, to log the old Production Control file, and to install the new file. f. Starts TWS processing for the new day. g. Runs reptr to print the post-production reports from the most recent log file. h. Runs logman to log job statistics from the most recent log file.
15.
If you wish to submit the schedule and/or job immediately, choose the Submit option from the header tab. In the Submit window, you can choose Schedules, Jobs, File, or Command . In this case choose Job or Schedule. Complete the appropriate fields and your job/schedule is submitted.
58
16.
When a Jnextday is completed, choose the appropriate object and display the production environment. Depending on security, this may not be possible. Ask your TWS administrator for your security options. Choose the Schedules object to display the schedule name, state of the schedule, its priority, the schedules duration, the number of jobs in that schedule, and the schedules limit and dependencies. In our example, the BACKUPDB schedule contains its state (SUCC), priority, start time, and other pertinent information (Figure 37).
Figure 37. BACKUPDB schedule
17.
By clicking the right button of the mouse, you can view the standard output (Figure 38).
Figure 38. Standard output for database backup
59
Figure 39. Checking the status of a job
18.
The standard output (better known in TWS as the stdlist) displays the header information: logon user, the job ID (or process ID), and the start date and time (Figure 39 and Figure 40). The body of the stdlist contains the standard output of the job and its exit code, which will determine the status of the job.
Figure 40. Stdlist for BACKUPDB
Follow the same steps when scheduling any job and/or schedule. The dependencies are the only differences.
60
Lets summarize the steps needed to schedule a job in TWS to back up a database. To back up a database, you will need to define a copy of a storage pool on your server. Eliminating this copy would result in errors when scheduling in TWS. To define a copy of a storage pool on your server, please refer to the relevant user guide for your server platform. 1. 2. 3. 4. 5. 6. 7. 8. 9. From the Maestro (TWS) Main Window, click on Composer (Database Manager). Choose Jobs from the Scheduling Objects selections. From the Actions menu, choose New Job. After you select the corresponding CPU and enter the job name (following your naming conventions). Enter the logon ID. This is the user ID that will execute the job. Enter the script name (including path). Enter the command or script (including path). The path can be entered in a parameter, in the .jobmanrc file, or in the command or script field. If the job resides on an NT system and it requires a manual intervention, Interactive must be selected. Enter the Recovery Option. If the job does not complete successfully, you must choose an action. The Stop option will wait for your manual next step. The Continue option would not be used in this scenario.The Rerun option allows the job to be executed again without manual intervention. Figure 41 on page 62 displays the Job Definition window.
61
Figure 41. Job Definition window for storage pool backup
10.
Select File->Save, and then File->Close . To define a new schedule for this job, choose Composer, and then select Schedules. Our objective is to create a new schedule.
11. 12. 13. 14.
On Actions menu, click New. Choose the associated CPU and enter the Schedule Name. Select the date(s) or pre-defined calendar to execute the schedule as well as its dependencies (if any). Select File->Save, and then File->Close . You now have a job and schedule in the TWS database to backup a storage pool. There are several ways to execute your schedule. a. If you have added this schedule and job in a production environment, you can only submit this schedule in an ad hoc fashion. Submit the job or schedule from the Conman window, choosing Submit Schedule or Submit Job, answering the necessary prompt. b. If the schedule and job were created in a test environment, you can rerun the Jnextday script from the command line. This will allow the schedule and job to run in the Symphony file (or TWS production
62
day). The schedule will execute immediately (if no time was entered) or it will execute on the given time.
Note
A new run number is generated when a Jnextday process is executed and all executing jobs will appear as CF (carryforward schedules.)
To view the state of the job and schedule: 15. 16. 17. Go to Maestro (TWS) Main Window and click on Conman (Console Manager). Choose Schedules or Jobs to view the state of the job. To display the standard output or result of the job, right-click the mouse button and choose Stdlist.
4.1.2 Backup device configuration

You can use this command to backup information about device class definitions, library definitions, and drive definitions. If you do not have a library installed on your server, you can also back up information about your disk. In order to schedule backup device configuration using TWS, you must define a new schedule and job. Follow the same steps described in Section 4.1.1, Database backup on page 43 to prepare your job and schedule. The Job Definition window for backup device configuration is seen in Figure 42 on page 64.
63
Figure 42. Job Definition window for backup device configuration
Once you create the new schedule and job to back up a device configuration, test your newly created schedule and job as in Section 4.1.1, Database backup on page 43.
4.1.3 Backup volume history

You can use this command to back up sequential volumes to one or more files. To define a new job and a new schedule for this event, follow the steps described in Section 4.1.1, Database backup on page 43. The Job Definition window for backup volume history is seen in Figure 43 on page 65.
64
Figure 43. Job Definition window for backup volume history
4.1.4 Clean volume history

Use this command to delete volume history file records that are no longer needed (that is, obsolete databases). To define a new job and a new schedule for this event, follow the steps described in Section 4.1.1, Database backup on page 43. The Job Definition window for clean volume history is seen in Figure 44 on page 66.
65
Figure 44. Job Definition window for clean volume history
4.1.5 Expiration process

This inventory expiration process removes client backup and archive file copies from server storage based on policy specified in the backup and archive copy groups of the management classes to which the files are bound. To define a new job and a new schedule for this event, follow the steps described in Section 4.1.1, Database backup on page 43. The Job Definition window for the expiration process is seen in Figure 45 on page 67.
66
Figure 45. Job Definition window for the expiration process
4.1.6 Reclamation process

Reclamation makes the fragmented space on volumes usable again by moving any remaining active files from one volume to another volume, thus making the original volume available for reuse. To define a new job and a new schedule for this event, follow the steps described in Section 4.1.1, Database backup on page 43. The Job Definition window for the reclamation process is seen in Figure 46 on page 68.
67
Figure 46. Job Definition window for the reclamation process
4.1.7 Migration process

You can use a primary storage pool as the destination for backup files, archive files, or files migrated from client nodes. To define a new job and a new schedule for this event, follow the steps described in Section 4.1.1, Database backup on page 43. The Job Definition window for the migration process is seen in Figure 47 on page 69.
68
Figure 47. Job Definition window for the migration process
4.1.8 Restore
You can restore files, a single database, databases, or volume history files. For more information, see the Tivoli Storage Manager for AIX Administrators Reference, GC35-0404. To define a new job and a new schedule for this event, follow the steps described in Section 4.1.1, Database backup on page 43. The Job Definition window for restore is seen in Figure 48 on page 70.
69
Figure 48. Job Definition window for restore
4.2 Summary
In this chapter we investigated the following TSM functions that can be scheduled by using TWS Extended agent for TSM. Backup device configuration Backup volume history Clean volume history Database backup Expiration process Migration process Reclamation process Restore Instead of using the native TSM scheduler, we used our TWS custom Extended agent for TSM to schedule these tasks through TWS. This way we were able to use TWSs extended scheduling capabilities.
70
Appendix A. TSW Extended agent for TSM source code

#!/bin/ksh set +u #--------------------------------------------------------------------------# This method script executes commands on the Tivoli Storage Manager server # for administrative and client backup purposes # # In order to use it, install it in the ~maestro/methods directory, # and create an x-agent workstation definition that uses it. For # example: # CPUNAME TSMADMIN # OS OTHER # NODE dontcare # TCPADDR 9000 # FOR MAESTRO # # HOST TWSFTA ACCESS tsmxagent
# END # # Create jobs for this x-agent with the following commands in the # "script name" field on the job definition: # # ADMIN DBBACKUP type devclass # # where type is either full or incremental # and where devclass is a devclass name
71
# defined in TSM. # This will run a backup database command. # # # ADMIN VHBACKUP filename # # where filename is a valid unix file for output # This will run a backup volhistory command. # # # ADMIN DCBACKUP filename # # where filename is a valid unix file for output. # This will run a backup devconfig command. # # ADMIN DELVOLHIST type todate # # where type is a string for the type parameter # and where todate is a date of form MM/DD/YYYY # This will run a delete volhistory command. # See the TSM Admin Reference for type parameter. # # ADMIN EXPIRE INVENTORY duration # # where duration is a numeric value # This will run an expire inventory command. #
72
# # CLIENT client # # where client is the name of a server-prompted # TSM client ready for scheduling # This will run a client backup schedule for the # client specified. #--------------------------------------------------------------------------PATH=$PATH:/bin:/usr/bin:/sbin:/usr/sbin:/etc/:/posix:/usr/ucb:/usr/bsd export PATH # Initialize some of the variables. SCHEDULE_NAME="" FORMATTED_SCHED_DATE="" UNIVERSAL_DATE="" NODE_NAME="" JOB_NAME="" JOB_ID="" STREAM_LOGON="" MAESTRO_CPU="" MAESTRO_HOST="" MAESTRO_MASTER="" PORT_NUMBER="" TEST_OPTIONS="" CURRENT_RUN_NUMBER="" REQUIRED_RUN_NUMBER="" STDLIST="" TASK=""
73
PARENT="NO" XARG1="" XARG2="" XARG3="" TMPJOBNAME="" JOBSTATUS="" DEVCLASS="" BACKUPTYPE="" FILENAMES="" TODATE="" DURATION="" RET9="" DSMADMC="/usr/bin/dsmadmc"
# The number of seconds to pause between client status checks CHECKFREQ=10 # The number of times to check client status JOBTIMEOUT=120 if [ -z "$UNISON_EXEC_PATH" ] then PROG_NAME=`basename $0` EXEC_PATH=`dirname $0` else PROG_NAME=`basename $UNISON_EXEC_PATH` EXEC_PATH=`dirname $UNISON_EXEC_PATH` fi BANNER="TWS Extended agent for TSM"
74
MAE_HOME=`dirname $EXEC_PATH` # Add maestro home to PATH. PATH=$MAE_HOME/bin:$MAE_HOME:$PATH export PATH echoerr() # Function to display error messages. { TIME=`date +%H:%M` echo "${PROG_NAME}:$TIME/" "$@" >&2 } # The name of the TSM adminstrator logon is in the tsmagent.opts file if [ -f ${PROG_NAME}.opts ] then USERID=àwk -F= '$1 ~ /tsmAdmin/ { print $2 }' ${PROG_NAME}.opts` else echoerr "Using default admin logon" USERID="admin" fi USAGE="Invalid Usage. See Tivoli Workload Scheduler Users Guide for correct usage ." print_version() { echo "$BANNER" } command_exist() { if type "$@" 2>&1 | grep -i "not *found" > /dev/null 2>&1 then
75
echoerr "Command $@ not found." return 1 else return 0 fi } Check_File() # Check for existance of a file on the extended agent machine. { [ -z "$TEST_OPTIONS" ] && TEST_OPTIONS="-f" test $TEST_OPTIONS "$FILE_NAME" exit $? } fail_job() { send_Message "CJ FAIL" exit 1 } abend_job() { send_Message "CJ ABEND" exit 1 } succeed_job() { send_Message "JS" exit 0
76
} tsm_admin_command() # Run dsmserv admin command { case $XARG2 in DBBACKUP|dbbackup) send_Message "CJ EXEC" BACKUPTYPE=$XARG3 DEVCLASS=$XARG4 $DSMADMC -id=$USERID -password=$PASSWORD backup db \ devclass=$DEVCLASS type=$BACKUPTYPE scratch=yes wait=yes [ ! $? -eq 0 ] && fail_job succeed_job ;; VHBACKUP|vhbackup) send_Message "CJ EXEC" FILENAMES=$XARG3 $DSMADMC -id=$USERID -password=$PASSWORD backup volhistory \ filenames=$FILENAMES [ ! $? -eq 0 ] && fail_job succeed_job ;; DCBACKUP|dcbackup) send_Message "CJ EXEC" FILENAMES=$XARG3 $DSMADMC -id=$USERID -password=$PASSWORD backup devconfig \ filenames=$FILENAMES wait=yes
77
[ ! $? -eq 0 ] && fail_job succeed_job ;; DELVOLHIST|delvolhist) send_Message "CJ EXEC" BACKUPTYPE=$XARG3 TODATE=$XARG4 $DSMADMC -id=$USERID -password=$PASSWORD delete volhistory \ type=$BACKUPTYPE todate=$TODATE [ ! $? -eq 0 ] && fail_job succeed_job ;; EXPIRE|expire) send_Message "CJ EXEC" DURATION=$XARG3 $DSMADMC -id=$USERID -password=$PASSWORD expire inventory \ duration=$DURATION wait=yes [ ! $? -eq 0 ] && fail_job succeed_job ;; esac
} tsm_client_command() # run tsm client backup { TEMPJOBNAME="TWS"$JOB_ID
78
send_Message "CJ EXEC" $DSMADMC -id=$USERID -password=$PASSWORD define schedule \ standard $TEMPJOBNAME \ action=incremental startdate=today starttime=now dayofweek=any \ expiration=TODAY [ ! $? -eq 0 ] && fail_job $DSMADMC -id=$USERID -password=$PASSWORD define association standard \ $TEMPJOBNAME $XARG2 [ ! $? -eq 0 ] && fail_job COUNTER=JOBTIMEOUT while [ 1 ] do sleep $CHECKFREQ COUNTER=èxpr $COUNTER - 1` if [ $COUNTER -eq 0 ] then $DSMADMC -id=$USERID -password=$PASSWORD delete schedule \ standard $TEMPJOBNAME fail_job else JOBSTATUS=`$DSMADMC -id=$USERID -password=$PASSWORD query event \ standard \* | grep $TEMPJOBNAME | grep Completed` if [ ! -z then $DSMADMC -id=$USERID -password=$PASSWORD delete schedule \ standard $TEMPJOBNAME succeed_job "$JOBSTATUS" ]
79
fi fi done $DSMADMC -id=$USERID -password=$PASSWORD delete schedule \ standard $TEMPJOBNAME [ ! $? -eq 0 ] && fail_job } Launch_Job() # Launch the job { if [ $# -lt 2 ]; then echoerr "Invalid job definition. Too few arguments!" fail_job fi [ -z "$SCRIPT_NAME" ] && exit 1 touch "$STDLIST" TMP_PATH=/tmp XARG1=ècho "$SCRIPT_NAME" | cut -d' ' -f1` XARG2=ècho "$SCRIPT_NAME" | cut -d' ' -f2` XARG3=ècho "$SCRIPT_NAME" | cut -d' ' -f3` XARG4=ècho "$SCRIPT_NAME" | cut -d' ' -f4` case $1 in ADMIN|admin) tsm_admin_command $@ ;; CLIENT|client) tsm_client_command $@
80
;; *) echoerr "Invalid job definition. Must be ADMIN or CLIENT!" fail_job esac exit 0 } Check_Connection() #Check connection { exit 0 } Manage_Job() { exit 1 } send_Message() { echo "%" "$@" return 0 } echo $BANNER if command_exist parms then PASSWORD=`parms TSMPASS` else echoerr "Could not find the TWS parms utility."
81
exit 3 fi #Parse the arguments while [ $# -gt 0 ] do OPT="$1" [ "ècho %$OPT | cut -c2`" != "-" ] && break shift case $OPT in -c) OPT_ARG="$1" shift MAESTRO_CPU=ècho "$OPT_ARG" | cut -d',' -f1` MAESTRO_HOST=ècho "$OPT_ARG" | cut -d',' -f2` MAESTRO_MASTER=ècho "$OPT_ARG" | cut -d',' -f3` ;; -d) OPT_ARG="$1" shift FORMATTED_SCHED_DATE=ècho "$OPT_ARG" | cut -d',' -f1` UNIVERSAL_DATE=ècho "$OPT_ARG" | cut -d',' -f2` ;; -j) OPT_ARG="$1" shift JOB_NAME=ècho "$OPT_ARG" | cut -d',' -f1` JOB_ID=ècho "$OPT_ARG" | cut -d',' -f2`
82
;; -l) OPT_ARG="$1" shift STREAM_LOGON="$OPT_ARG" ;; -n) OPT_ARG="$1" shift NODE_NAME="$OPT_ARG" ;; -o) OPT_ARG="$1" shift STDLIST="$OPT_ARG" ;; -p) OPT_ARG="$1" shift PORT_NUMBER="$OPT_ARG" ;; -q) OPT_ARG="$1" shift TEST_OPTIONS="$OPT_ARG" ;; -r)
83
OPT_ARG="$1" shift CURRENT_RUN_NUMBER=ècho "$OPT_ARG" | cut -d',' -f1` REQUIRED_RUN_NUMBER=ècho "$OPT_ARG" | cut -d',' -f2` ;; -s) OPT_ARG="$1" shift SCHEDULE_NAME="$OPT_ARG" ;; -t) OPT_ARG="$1" shift TASK="$OPT_ARG" ;; -V) print_version exit 0 ;; --) break ;; *) echoerr "$USAGE" exit 1 ;; esac
84
done REMAINING_ARGS="$*" if [ ! "$TASK" = "CC" ] then if [ "$#" = "0" ] || [ -z "$TASK" ] then echoerr "$USAGE" exit 1 fi fi case $TASK in CF) FILE_NAME="$REMAINING_ARGS" Check_File ;; MJ) JOB_PID=ècho "$REMAINING_ARGS" | cut -d" " -f1` STDLIST=ècho "$REMAINING_ARGS" | cut -d" " -f2` Manage_Job ;; LJ) SCRIPT_NAME="$REMAINING_ARGS" send_Message "CJ WAIT" Launch_Job $SCRIPT_NAME ;; CC) Check_Connection
85
;; *) echoerr $USAGE send_Message "UT $USAGE" exit 2 ;; esac exit 3
86
Appendix B. Using the additional material

This redbook also contains Web material. See the appropriate section below for instructions on using and downloading Web material.
B.1 Locating the additional material on the Internet

The Web material associated with this redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG246030
Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks
Select Additional materials and open the directory that corresponds with the redbook form number.
B.2 Using the Web material

The additional Web material that accompanies this redbook includes the following: File name TSMX-agent.zip X-agent.zip Description TWS Extended agent for Tivoli Storage Manager code (zipped) Warren Gills presentation about how to write a TWS Extended agent (zipped and PowerPoint Viewer included)
B.2.1 How to use the Web material

Create a subdirectory (folder) on your workstation and copy the contents of the Web material into this folder.
87
88
Implementing TWS Extended agent for Tivoil Storage Manager
Appendix C. Special notices

This publication is intended to help Tivoli professionals who want write a Tivoli Workload Scheduler Extended agent or to integrate Tivoli Workload Scheduler and Tivoli Storage Manager. The information in this publication is not intended as the specification of any programming interfaces that are provided by Tivoli Workload Scheduler or Tivoli Storage Manager. See the PUBLICATIONS section of the IBM Programming Announcement for Tivoli Workload Scheduler and Tivoli Storage Manager for more information about what publications are considered to be product documentation. References in this publication to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent program that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program or service. Information in this book was developed in conjunction with use of the equipment specified, and is limited in application to those specific hardware and software products and levels. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The information contained in this document has not been submitted to any formal IBM test and is distributed AS IS. The use of this information or the implementation of any of these techniques is a customer responsibility and depends on the customer's ability to evaluate and integrate them into the customer's operational environment. While each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee
89
that the same or similar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. Any pointers in this publication to external Web sites are provided for convenience only and do not in any manner serve as an endorsement of these Web sites. The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries:
IBM CT e (logo) Lotus Notes Netfinity Redbooks Logo System/390 AS/400 Current Lotus Notes Redbooks RS/6000 XT
The following terms are trademarks of other companies: Tivoli, Manage. Anything. Anywhere.,The Power To Manage., Anything. Anywhere.,TME, NetView, Cross-Site, Tivoli Ready, Tivoli Certified, Planet Tivoli, and Tivoli Enterprise are trademarks or registered trademarks of Tivoli Systems Inc., an IBM company, in the United States, other countries, or both. In Denmark, Tivoli is a trademark licensed from Kjbenhavns Sommer - Tivoli A/S. C-bus is a trademark of Corollary, Inc. in the United States and/or other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States and/or other countries. PC Direct is a trademark of Ziff Communications Company in the United States and/or other countries and is used by IBM Corporation under license. ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United States and/or other countries. UNIX is a registered trademark in the United States and other countries
90
licensed exclusively through The Open Group. SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others.
Appendix C. Special notices
91
92
Appendix D. Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.
D.1 IBM Redbooks collections

Redbooks are also available on the following CD-ROMs. Click the CD-ROMs button at ibm.com/redbooks for information about all the CD-ROMs offered, updates and formats.
CD-ROM Title Collection Kit Number IBM System/390 Redbooks Collection SK2T-2177 IBM Networking Redbooks Collection SK2T-6022 IBM Transaction Processing and Data Management Redbooks Collection SK2T-8038 IBM Lotus Redbooks Collection SK2T-8039 Tivoli Redbooks Collection SK2T-8044 IBM AS/400 Redbooks Collection SK2T-2849 IBM Netfinity Hardware and Software Redbooks Collection SK2T-8046 IBM RS/6000 Redbooks Collection SK2T-8043 IBM Application Development Redbooks Collection SK2T-8037 IBM Enterprise Storage and Systems Management Solutions SK3T-3694
D.2 Other resources

These publications are also relevant as further information sources: Tivoli Workload Scheduler 7.0 Reference Guide, GC32-0424 Tivoli Workload Scheduler 7.0 Planning and Installation Guide, GC32-0422 Tivoli Workload Scheduler 7.0 Users Guide,GC32-0423 Tivoli Storage Manager for AIX Administrators Reference, GC35-0404
D.3 Referenced Web sites

These Web sites are also relevant as further information sources: http://www.tivoli.com/ Tivolis external Web site
93
94
How to get IBM Redbooks

This section explains how both customers and IBM employees can find out about IBM Redbooks, redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided. Redbooks Web Site ibm.com/redbooks Search for, view, download, or order hardcopy/CD-ROM Redbooks from the redbooks Web site. Also read redpieces and download additional materials (code samples or diskette/CD-ROM images) from this redbooks site. Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just a few chapters will be published this way. The intent is to get the information out much quicker than the formal publishing process allows. E-mail Orders Send orders by e-mail including information from the IBM Redbooks fax order form to: In United States or Canada Outside North America Telephone Orders United States (toll free) Canada (toll free) Outside North America 1-800-879-2755 1-800-IBM-4YOU Country coordinator phone number is in the How to Order section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl e-mail address pubscan@us.ibm.com Contact information is in the How to Order section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl
Fax Orders United States (toll free) Canada Outside North America 1-800-445-9269 1-403-267-4455 Fax phone number is in the How to Order section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl
This information was current at the time of publication, but is continually subject to change. The latest information may be found at the Redbooks Web site. IBM Intranet for Employees IBM employees may register for information on workshops, residencies, and Redbooks by accessing the IBM Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materials repository for workshops, presentations, papers, and Web pages developed and written by the ITSO technical professionals; click the Additional Materials button. Employees may access MyNews at http://w3.ibm.com/ for redbook, residency, and workshop announcements.
95
IBM Redbooks fax order form

Please send me the following: Title Order Number Quantity
First name Company Address City Telephone number Invoice to customer number Credit card number
Last name
Postal code Telefax number
Country VAT number
Credit card expiration date
Card issued to
Signature
We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not available in all countries. Signature mandatory for credit card payment.
96
Abbreviations and acronyms

ADSM AIX API CF CLI CPU ESM FTA GRT GS GUI IBM ITSO JSC LJ MJ MVS OPC PID RFC SAN SLA TCP TME ADSTAR Distributed Storage Manager Advanced Interactive Executive application programming interface check file command line interface central processing unit Enterprise Systems Management Fault-tolerant Agent Global Response Team get status of job graphical user interface International Business Machines Corporation International Technical Support Organization Job Scheduling Console launch job manage job Multiple Virtual Storage Operations, Planning and Control process identification Remote Function Call Storage Area Networks service level agreement Transmission Control Protocol Tivoli Management Environment TMR TSM TWS Tivoli Management Region Tivoli Storage Manager Tivoli Workload Scheduler
97
98
Symbols
.jobmanrc 46
A
abended 46 access method 4, 5 ADSM See ADSTAR Distributed Storage Manager ADSTAR Distributed Storage Manager 8 application programming interface 1 archival storage 8 archive 7, 8
B
Backup Master 3 backup volumes 30 batch job execution 2 Batchman process 5
C
CA7 7 centralized database 3 CF task 14 client backups 1 command line interface 1, 13 commit 34 common interface 4 compiler 58
D
data protection 8 databases 8 DEFINE ASSOCIATION 9 DEFINE SCHEDULE 9 DELETE SCHEDULE 9 dependencies 1 device class definitions 29 disaster recovery 8 DOCOMMAND 6 Domain Manager 3, 4 drive definitions 30 dump volumes 30 duration 32
export volumes 30 Extended agent 4, 9, 10, 13 access method 10 access method interface 15 API 1 architecture 5 example 18 executing the method 21 host 10 interface 4 interface between TWS 4 jobname 17 killing a job 21 logical workstation definition 10 messages 20 method command line syntax 15 method options file 14 method troubleshooting 21 nodename 17 password 9 portnumber 17 processing 5 qualifier 17 referenced 10 sample options file 14 sample scenarios 43 segregation of applications 4 special login information 14 stdlist 17 troubleshooting 21 user 17 Windows NT 15 workstation definition 13 external job 6 external system 13
F
fast recovery 7 Fault-tolerant Agent See FTA Follows Sched/Job option 53 foreign platforms 4 FTA 5 Full Status 3
E
e-mail 8
G
groupware 8
99
H
hierarchical space management 8
NEXTSTGPOOL 28 node 14
I
Interactive option 46
O
offset 52 OPC 4 open API 7 OPENS dependency 6 Opens Files 53 operator prompts 1 Oracle Applications 3, 7
J
Java 1 JES2 3 JES3 3 job execution 1 job ID 6 job number 6 Job Scheduling Console 1, 2, 13 job stream execution 1 jobman.exe 5 jobmanrc 4 jobmon.exe 5 JSC See Job Scheduling Console
PeopleSoft 3, 7 physical workstation 13 PID 18 port definition 2, 6 production run number 6
Q
QUERY EVENT 9
L
LAN-free backup 7 launch a job 6 library definitions 29 line 13 LJ task 14 local dependencies 4 logical workstation 13
R
Recovery Options 46 remote console 3 Remote Function Call 5 repeater 3 reptr 58 Resolve Dependencies 3 retrieval 7 roll over 1 root user ID 5 run cycle 1
M
Maestro 34 manage a job 6 management hub 4 Master Domain Manager 3 method.opts 5 methods directory 4 migration 7 MJ task 14 MVS JES2 3 MVS JES3 3
S
SAN 7 SAP R/3 3 Batch 7 schedule name 6 scheduling API 4 scheduling protocol 4 schedulr 58 SCRIPTNAME 6 service level agreement 43 shell script 4 skipdirs 32 SLA
N
Needs Resources 54 Network agent 3 network communication 5
100
Implementing TWS Ex tended agent for Tivoli Storage Manager
See service level agreement space management 7 stageman 58 Standard agent 3 stdout 41 Storage Area Networks See SAN storage resource management 8 subfile backup 7 Submit option 58 Symphony file 62 synchronize job 16
T
tape sharing 7 tcpaddr 14 timeout 9 Tivoli Job Scheduling Services 2 Tivoli Management Framework 2 Tivoli Storage Management 8 Tivoli Storage Manager 11 See TSM Tivoli TWS Connector 2 troubleshooting 1 TSM 7, 11, 23 Administrative Client Interface 9 archive process 8 backup 23 backup storage pool 25 backup volume history 41 client backups 9 Composer 34 data protection 8 database 23, 31 disaster recovery 8 Extended agent benefits 9 incremental backup 7 Main Window 34 migration 23, 27 overview 7 processes 23 reclamation 23, 26 Restore Database 41 restore database 32 retrieval process 8 scheduling facility 1 scratch volumes 31 task 9
volume history 23 TSM scenarios backup device configuration 63 backup volume history 64 clean volume history 65 database backup 43 expiration process 66 migration process 68 reclamation process 67 restore 69 TSMPASS 9 tsmxagent 9 tsmxagent.opts 9 TWS 2, 4 architecture 3 Backup Master 3 calendars 2 concepts 2 Conman 57 Connector 2 CPU 38 current run number 17 database 1 database files 3 default user 34 Domain Manager 3 Extended agent 3 Fault-tolerant Agent 3 Files 39 job streams 2 Jobs 38 JSC Client 3 legacy user interface 43 Master 5 Master Domain Manager 3 methods directory 9 network 2 plan 1 production day 62 production plan 13 Prompts 38 Recovery Options 37 Resources 38 scaling 3 Schedules 38 scheduling API 4 separate networks 3 server 5 Standard agent 3
101
standard output 60 task options 16 terminology 2 types of workstations 3 versions prior to 7.0 43 workstations 2
U
UNIX Local 7 UNIX Remote Shell 7
V
View Filter option 47 virtual resources 1 vital record retention 8
W
wait 32 wgetmethod 7
102
Implementing TWS Ex tended agent for Tivoli Storage Manager
IBM Redbooks review

Your feedback is valued by the redbook authors. In particular we are interested in situations where a redbook "made the difference" in a task or problem you encountered. Using one of the following methods, please review the redbook, addressing value, subject matter, structure, depth and quality as appropriate. Use the online Contact us review redbook form found at ibm.com/redbooks Fax this form to: USA International Access Code + 1 845 432 8264 Send your comments in an Internet note to redbook@us.ibm.com
Document Number Redbook Title Review
SG24-6030-00 Implementing TWS Extended agent for Tivoli Storage Manager
What other subjects would you like to see IBM Redbooks address?
Please rate your overall satisfaction: Please identify yourself as belonging to one of the following groups: Your e-mail address: The data you provide here may be used to provide you with information from IBM or our business partners about our products, services or activities. Questions about IBMs privacy policy?
O Very Good
O Good
O Average
O Poor O Solution Developer
O Customer O Business Partner O IBM, Lotus or Tivoli Employee O None of the above
O Please do not use the information collected here for future marketing or promotional contacts or other communications beyond the scope of this transaction.
The following link explains how we protect your personal information. ibm.com/privacy/yourprivacy/
103
(0.2spine) 0.17<->0.473 90<->249 pages

Insiders guide to writing a TWS Extended agent Ready-to-use solution to integrate TSM and TWS TSM Extended agent code included
Tivoli Workload Scheduler (TWS) is Tivolis strategic, multiplatform distributed scheduling product that provides high-volume, complex scheduling capability. Although TWS has native support for many platforms and applications, it is possible to extend the TWSs robust scheduling capabilities to cover platforms and applications beyond those TWS supports. The way to do this is to write an Extended agent. This redbook shows you how to write a TWS Extended agent that allows you to schedule on platforms and applications for which TWS has no native agent. Tivoli Storage Manager (TSM) is used as a sample application to integrate with TWS using the Extended agent. Using TWSs scheduling facility allows you to assign dependencies among TSM scheduled tasks or to assign limits or priorities. By extending TWS to schedule these TSM tasks, you can take advantage of its advanced scheduling capabilities. This redbook will be essential for those who will write a TWS Extended agent or will use TWS to schedule TSM functions.
INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION
BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.
For more information: ibm.com/redbooks

SG24-6030-00 ISBN 0738419753

Implementing TWS Extended Agent For Tivoli Storage Manager - Sg246030

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Implementing TWS Extended Agent For Tivoli Storage Manager - Sg246030

Uploaded by

Copyright:

Available Formats

Implementing TWS Extended agent for Tivoli Storage Manager

41. 42. 43. 44. 45. 46. 47. 48.

Implementing TWS Extended agent for Tivoli Storage Manager

Copyright IBM Corp. 2001

Implementing TWS Extended agent for Tivoli Storage Manager

The team that wrote this redbook

Copyright IBM Corp. 2001

Implementing TWS Extended agent for Tivoli Storage Manager

1.1 TWS overview

Copyright IBM Corp. 2001

1.1.1 Software configurations used for this redbook

1.1.2 TWS concepts and terminology

Implementing TWS Extended agent for Tivoli Storage Manager

1.1.3 TWS architecture

1.1.4 Extended agents

Figure 1. Extended agent network

Implementing TWS Extended agent for Tivoli Storage Manager

Extended agent processing is explained in Figure 2. The sequence of operations is as follows:

Figure 2. Extended agent processing

Implementing TWS Extended agent for Tivoli Storage Manager

1.2 TSM overview

Implementing TWS Extended agent for Tivoli Storage Manager

Extended agent Host

External system or application

Implementing TWS Extended agent for Tivoli Storage Manager

Implementing TWS Extended agent for Tivoli Storage Manager

Chapter 2. Extended agent functions

2.2 Workstation definition

Copyright IBM Corp. 2001

2.3 Method options file

Implementing TWS Extended agent for Tivoli Storage Manager

2.4 Access method interface

2.4.1 Method command line syntax

Chapter 2. Extended agent functions

Table 1. Task types

2.4.2 Task options

ljstring mjstring cfstring

Implementing TWS Extended agent for Tivoli Storage Manager

Chapter 2. Extended agent functions

Let us examine the command structure from the example.

This is the directory to the access method script.

Implementing TWS Extended agent for Tivoli Storage Manager

Chapter 2. Extended agent functions

State Pr Start Elapse Dependencies

2.5 Method response messages

Implementing TWS Extended agent for Tivoli Storage Manager

2.6 Execution and troubleshooting

2.6.1 Executing the method

2.6.2 Killing a job

2.6.3 Method troubleshooting

Chapter 2. Extended agent functions

A successful job launch generates the following message:

Failure to launch a job generates the following message:

Failure of a CF task generates the following message:

Failure of an MJ task generates the following message:

Implementing TWS Extended agent for Tivoli Storage Manager

Chapter 3. Case study - TSM Extended agent

backup db devclass=dbbackup type=full sctatch=yes wait=yes

Copyright IBM Corp. 2001

Implementing TWS Extended agent for Tivoli Storage Manager

Check .NSF files