Tivoli Workload Scheduler. Scheduling Agent for R/3 User s Guide. Version GC

Transcription

1 Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide Version GC

2

3 Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide Version GC

4 Tivoli Workload Scheduler, Scheduling Agent for R/3, Version Copyright Notice Copyright IBM Corporation 2000, All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement, an IBM Software License Agreement, or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of IBM Corporation. IBM Corporation grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the IBM Corporation copyright notice. No other rights under copyright are granted without prior written permission of IBM Corporation. The document is not intended for production and is furnished as is without warranty of any kind. All warranties on this document are hereby disclaimed, including the warranties of merchantability and fitness for a particular purpose. U.S. Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corporation. Trademarks IBM, Tivoli, the Tivoli logo, AIX, and z/os are trademarks or registered trademarks of International Business Machines Corporation or Tivoli Systems Inc. in the United States, other countries, or both. Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others. Notices References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to valid intellectual property or other legally protectable right of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or 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, New York , U.S.A. ISO 9001 Certification This product was developed using an ISO 9001 certified quality system. Certification has been awarded by Bureau Veritas Quality International (BVQI) (Certification No. BVQI / A). BVQI is a world leader in quality certification and is currently recognized by more than 20 accreditation bodies.

5 Contents Preface... v Who Should Read This Guide... v What This Guide Contains.... v Publications... v Tivoli Workload Scheduler Library... v Accessing Publications Online... vi Ordering Publications... vi Providing Feedback about Publications... vi Contacting Customer Support... vi Conventions Used in This Guide... vii Chapter 1. Introduction... 1 Features... 1 R/3 Scheduling Agent Process... 1 BDCWait... 2 BDC Session Names... 2 Workload Scheduler and R/3 Job States... 3 Chapter 2. Installation... 5 Software Requirements... 5 Installation Overview... 5 Installing to a UNIX Host... 6 Installing to a Windows NT or Windows 2000 Host r3options File Reference... 8 Sample r3options File Entry... 9 Modifying the r3options File... 9 Encrypting R/3 User Passwords on a UNIX Host Installing the Scheduling Agent on the R/3 System Chapter 3. R/3 Configuration Overview Creating the Authorization Profile For R/3 Versions 3.1g, 3.1h, 3.1i, 4.0x, 4.5x, and 4.6x Creating the Workload Scheduler RFC User Copy the Correction And Transport Files Import ABAP/4 Modules into R/ Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide iii

6 Troubleshooting the R/3 Connection Changing the Workload Scheduler RFC User ID Password Option Option Migrating from Previous Versions Print Paramater and Job Class Issues Chapter 4. Setting Up for Tivoli Workload Scheduler Defining a Scheduling Agent Workstation Defining Scheduling Agent Jobs Defining a Job in Workload Scheduler Defining a Job in R/ Defining a Job in Workload Scheduler and R/ Defining Scheduling Agent Job Streams Chapter 5. R/3 Window Reference Properties - Job Definition General Page Task Page R/3 Job Definition R/3 Job Page Steps Page (ABAP) Steps Page (External Program) Index iv Version 4.0.1

7 Preface This guide provides information on how to install, configure, and use the Tivoli Workload Scheduler Scheduling Agent for R/3. Who Should Read This Guide The target audience for this guide is administrators who will install, configure, and monitor job execution on the R/3 system from the Tivoli Workload Scheduler interface. Users of the guide should have some knowledge of the following: Tivoli Workload Scheduler R/3 operating environment UNIX, Windows NT, and Windows 2000 operating systems What This Guide Contains This guide contains the following sections: Chapter 1, Introduction on page 1 Provides an introduction to the product. Chapter 2, Installation on page 5 Provides installation instructions for UNIX, Windows NT, and Windows Chapter 3, R/3 Configuration on page 11 Describes how to install R3batch. Chapter 4, Setting Up for Tivoli Workload Scheduler on page 17 Describes how to configure the scheduling agent workstation, job streams and jobs. Chapter 5, R/3 Window Reference on page 21 Describes the input fields and windows used to create jobs in Workload Scheduler and in R/3 for the Scheduling Agent for R/3. Publications This section lists publications in the Tivoli Workload Scheduler library. It also describes how to access Tivoli publications online, how to order Tivoli publications, and how to make comments on Tivoli publications. Tivoli Workload Scheduler Library The following documents are available in the Tivoli Workload Scheduler library: Table 1. List of Publications for Tivoli Workload Scheduler Task Publication Order number Installing a Workload Scheduler network Using the command line interface, scheduling language, and utility commands Tivoli Workload Scheduler Planning and Installation Tivoli Workload Scheduler Reference Guide SH SH Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide v

8 Table 1. List of Publications for Tivoli Workload Scheduler (continued) Task Publication Order number Installing and configuring limited fault-tolerant agents on AS/400 Setting up and using the Plus module Interpreting messages Using the Java -based graphical user interface Tivoli Workload Scheduler Limited Fault-Tolerant Agent for AS/400 User s Guide Tivoli Workload Scheduler Plus Module User s Guide Tivoli Workload Scheduler Error Messages Tivoli Workload Scheduler Job Scheduling Console User s Guide SH SH SH SH Accessing Publications Online You can access many Tivoli publications online using the Tivoli Information Center, which is available on the Tivoli Customer Support Web site: These publications are available in PDF or HTML format, or both. Translated documents are also available for some products. Ordering Publications You can order many Tivoli publications online at the following Web site: You can also order by telephone by calling one of these numbers: In the United States: In Canada: In other countries, for a list of telephone numbers, see the following Web site: Providing Feedback about Publications We are very interested in hearing about your experience with Tivoli products and documentation, and we welcome your suggestions for improvements. If you have comments or suggestions about our products and documentation, contact us in one of the following ways: Send an to pubs@tivoli.com. Complete our customer feedback survey at the following Web site: Contacting Customer Support If you have a problem with any Tivoli product, you can contact Tivoli Customer Support. See the Tivoli Customer Support Handbook at the following Web site: vi Version 4.0.1

9 The handbook provides information about how to contact Tivoli Customer Support, depending on the severity of your problem, and the following information: Registration and eligibility Telephone numbers and addresses, depending on the country you are in What information you should gather before contacting support Conventions Used in This Guide The following typeface conventions are used in this book: Bold Lowercase and mixed-case commands, command options, and flags that appear within text appear like this, in bold type. Graphical user interface elements (except for titles of windows and dialogs) and names of keys also appear like this, in bold type. Italic Variables, values you must provide, new terms, and words and phrases that are emphasized appear like this, in italic type. Monospace Commands, command options, and flags that appear on a separate line, code examples, output, and message text appear like this, inmonospace type. Names of files and directories, text strings you must type, when they appear within text, names of Java methods and classes, and HTML and XML tags also appear like this, inmonospace type. Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide vii

10 viii Version 4.0.1

11 1 1. Introduction Introduction Features The Tivoli Workload Scheduler Scheduling Agent for R/3 gives you the ability to create, schedule, and control R/3 jobs using the sophisticated job scheduling features of Tivoli Workload Scheduler. With Tivoli Workload Scheduler, you can: Use Workload Scheduler standard job dependencies and controls on R/3 jobs. Create R/3 jobs using the Workload Scheduler interface. Schedule R/3 jobs to run on specified days and times, and in a prescribed order. Define inter-dependencies between R/3 jobs and jobs that run under different systems such as Oracle Applications 10.6 / 10.7 and Baan IV. Define inter-dependencies between R/3 jobs and jobs that run on other platforms, including UNIX, Windows NT, Windows 2000, z/os, and HP MPE. R/3 Scheduling Agent Process Workload Scheduler launches jobs on an R/3 Scheduling Agent workstation (x-agent). The R/3 x-agent is defined in a standard Workload Scheduler workstation definition, which gives the x-agent a name and identifies the access method as r3batch. When invoked, the method reads configuration information from an options file called r3options. Each instance of R/3 is defined as a separate x-agent, and each has a separate entry in the r3options file. To launch a job on an R/3 x-agent, the Workload Scheduler host runs the r3batch command, passing it information about the job. Using the x-agent workstation name as a key, r3batch looks up the corresponding entry in the r3options file to determine which instance of R/3 will run the job. r3batch makes a copy of the template then marks the job in R/3 as able to run and sets its start time to now. It then monitors the job through completion, writing job progress and status information to the job standard list file. Note: You cannot kill or cancel an R/3 job from Workload Scheduler on Windows NT or Windows From UNIX, the kill command terminates the R/3 job and is equivalent to the cancel command in R/3 R/3. For more information about job management, refer to the Tivoli Workload Scheduler Reference Guide. Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 1

12 BDC Wait With the Batch Data Collector (BDC) wait option, you can specify that an R/3 job launched by Workload Scheduler will not be considered complete until all of its BDC sessions have completed. This prevents other Workload Scheduler jobs that are dependent on the R/3 job from being launched until all of the related BDC sessions for the R/3 job have complete. To make use of the option, an R/3 job must be modified to write informational messages in its joblog. To do this, add a message statement to your ABAP program for each BDC session, using the following syntax: message i001(92) with 'name' message i001(92) with 'queueid' where name is the BDC session name (up to 12 characters), and queueid is the BDC queue ID (up to 20 characters). Multiple messages can be written to allow monitoring of multiple BDC sessions. BDC Session Names If BDC sessions are specified by name, Workload Scheduler will not wait for the named BDC session to complete if there are other BDC sessions of the same name that complete. Example A Workload Scheduler-launched R/3 job starts three BDC sessions with the name ORD2, then issues one BDCWAIT message: BDCWAIT:ORD2 After the first ORD2 session is complete, the status of the R/3 job is shown as SUCC in Workload Scheduler. r3batch does not know the difference between non-unique BDCs (that is, named BDCs). Using queueid Another problem of using BDC session with names is probably different system times in a distributed R/3 environment. r3batch scans for BDC sessions with the specified names which are generated during the runtime of the creator job. If the creator job does nothing other than start BDC sessions, the runtime might be very short. If no time synchronization is installed, the system time of different machines usually differs in a distributed R/3 environment. This time difference might be larger than the job runtime. It is therefore possible that the wrong time interval is scanned and the BDC sessions are never detected. To resolve this, BDC sessions can also be specified by queueid, the 20-digit BDC session identifier. Because each R/3-assigned queueid is unique, one BDCWAIT message must be issued for each separate queueid to be monitored. To determine the queueid, modify the form open_group in the R/3 object BDCRECXX as follows: form open_group. if session = 'X'. skip. write: /(20) 'Create group'(i01), group. skip. * open batchinput group call function 'BDC_OPEN_GROUP' 2 Version 4.0.1

13 exporting client = sy-mandt group = group user = user keep = keep holddate = holddate importing qid = myquid. message i001(92) with myqid. write: /(30) 'BDC_OPEN_GROUP'(i02), (12) 'returncode:'(i05), sy_subrc. endif. endform. Do not forget to define the variable myqid in BDCRECXX. With this approach, you have a global change in your R/3 system. Alternatively, if you do not want to make R/3 modifications, you can also copy BDCRECXX to another name, for example ZBDCRECXX, make the changes in the copy and include it into all of your programs that generate BDC sessions. You have to do this manually for each job. The completion status of a Workload Scheduler-launched R/3 job, whether SUCC or ABEND, is based entirely on the execution status of the batch job. It is not related to the success or failure of any BDC sessions, which are considered finished regardless of any errors found during BDC processing. Workload Scheduler and R/3 Job States When an R/3 job is launched by Workload Scheduler, you can monitor its progress. The status transitions in Workload Scheduler (internal status) and the corresponding R/3 status are listed in the following table. 1. Introduction Workload Scheduler Job State INTRO WAIT EXEC SUCC ABEND R/3 Job State N/A Ready Active Finished Canceled The INTRO state indicates that Workload Scheduler is in the process of introducing the job, but in R/3, the job has not yet entered the ready state. Because it takes some time to get a job queued and into the ready column, the INTRO state may last a few minutes if the R/3 system is particularly busy. Although a job may be finished in R/3, Workload Scheduler will keep it in the EXEC state if its BDC sessions are not complete and you have not selected the Disable BDC Wait option. Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 3

14 4 Version 4.0.1

15 2 Installation This section contains information on installing the Tivoli Workload Scheduler Scheduling Agent for R/3. Software Requirements To use the Tivoli Workload Scheduler Scheduling Agent for R/3 version 4.0.1, you must be running the following: Tivoli Workload Scheduler R/3 Version 3.1g, 3.1h, 3.1i, 4.0x, 4.5x, or 4.6x The appropriate R/3 Support Package as stated by the R/3 notes and This is to resolve print parameter issues known from previous versions of Tivoli Workload Scheduler Scheduling Agent for R/3 installations. To resolve different issues with... Refer to these R/3 notes... R/3 3.1i R/3 4.0x R/3 4.5x , , , , R/3 4.6x , Installation Installation Overview The following is an overview of the Workload Scheduler Scheduling Agent for R/3 installation steps. Before you start, ensure that Tivoli Workload Scheduler is properly installed on the host workstation before installing the Scheduling Agent for R/3: 1. On the system running the Scheduling Agent for R/3: a. Extract the Workload Scheduler R/3 software from the product CD-ROM: 1) For UNIX, execute the r3setup -new script to decompress the files and perform initial setup. 2) For Windows NT and Windows 2000, run the SETUP.EXE program to install the files and perform initial setup. b. Create the r3batch.opts file and install it to the TWShome/methods directory. This file is required and is created automatically during the installation. c. Create the r3options file. This file is required and is created automatically during the installation. 2. Install the r3batch ABAPs on the R/3 system. To do this: a. Create the RFC user. b. Import the correction and transport files. Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 5

16 Installing to a UNIX Host 1. Log on as root and change to the TWShome directory (usually usr/lib/maestro). 2. Mount the installation CD-ROM, and extract the software: tar xvf cd_path/sap/platform/sap.tar where: cd_path is the pathname of your CD-ROM drive. platform is your platform type. Choose from one of the following: AIX IBM OSF Compaq Tru 64 HPUX HP-UX SOLARIS Sun Solaris 3. Run the r3setup script to decompress the files, perform the initial setup, and create the r3options file: /bin/sh r3setup -new-update where: -new Specifies a new installation. -update Specifies that you are installing over a previously installed version of the R/3 Scheduling Agent. 4. Create the r3batch.opts file. This file must reside in the TWShome/methods directory. You are prompted to enter a number of attributes: LJuser=launch_user IFuser=info_user JobDef=jobdef where: launch_user is the UNIX user name that runs the r3batch method. This must be a valid UNIX account. info_user is the UNIX user name that runs the r3batch method to retrieve job information. It must be the same as the LJuser. jobdef is the job definition type to access job definition windows in Workload Scheduler. Enter r3batch to access R/3-specific job definition windows. Enter Generic for the standard composer job definition GUI. 5. Open the Job Scheduling Console or Composer program and create a workstation definition in Workload Scheduler for each instance of R/3. 6 Version 4.0.1

17 Installing to a Windows NT or Windows 2000 Host 1. Log on as a user in the Administrators group or the Domain Administrators group, as appropriate. 2. Insert the installation CD-ROM. 3. Exit all Windows applications, including Explorer. 4. Run the Setup program. To this, from the Start menu, select Run. The Run window is displayed. 5. Enter: drv:\sap\i386nt\setup.exe where: drv: specifies the location of your CD-ROM drive. The Setup program starts. 6. The Welcome window provides information about installing the R/3 x-agent software. If this version of the Workload Scheduler x-agent is going to be installed on top of an existing installation, Setup asks for your confirmation and removes the old installation. 7. To continue, click Next. The Choose Destination Location window is displayed. 8. Define the directory to install the R/3 Scheduling Agent method: a. Click Browse to locate and select the TWShome directory. b. Click Next to continue. 9. Select the Setup type you prefer. Typical Installation is the default select. 10. Click Next to continue. 11. Select the Program Folder of the Tivoli Workload Scheduler Scheduling Agent for R/3, then click Next. 12. Specify the LJuser and the IFuser, where: LJuser is the Windows user name that executes the r3batch method. This must be a valid Windows account. IFuser is the Windows user name that executes the r3batch method to retrieve job information. It must be the same as the LJuser. Setup sets the job definition type (JobDef) to r3batch by default. To access R/3-specific job definition windows in Workload Scheduler through the standard composer job definition GUI, change the JobDef entry in the r3batch.opts file to Generic. Note: If the r3batch.opts file already exists in the TWShome\methods directory, you are prompted whether to keep it or to create a new one. Click No to create a new r3batch.opts file. 13. Click Next. The r3batch.opts file is created in the TWShome\methods directory. 14. A bar graph is displayed showing the installation progress. Click Cancel if you want to interrupt the process. 2. Installation Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 7

18 15. When Setup is complete, click Finish to exit Setup. If this is a new installation, ensure the Launch the R3 Options Editor R3Opt check box is selected. This launches the options editor immediately after Setup. You can launch the options editor at any other time by from the Start menu. 16. If the options editor is launched on a new installation, the r3options file does not exist and you are asked whether or not to create it. Click OK to continue. Enter the options for each R/3 Scheduling Agent you are going to run. 17. When you have completed entering the options, click Save and confirm. The r3options file is saved in the TWShome\methods directory. 18. Click Exit and confirm. 19. Start the Job Scheduling Console or the composer program and create a workstation definition in Workload Scheduler for each instance of R/3. r3options File Reference The r3options file must reside on the Workload Scheduler host workstation in the TWShome\methods directory. It contains a set of options for each R/3 Scheduling Agent workstation. The options are separated by one or more spaces. To create and maintain the file, you can either use a text editor, or you can use the r3setup -maintain command for UNIX or the R3Opt 1.1 program from the Windows Start menu. Each set of options has the following syntax: HostWorkstationName R/3ApplicationServer [R/3GatewayHost] R/3SystemName R/3Instance ClientNumber Userid Password ShortInterval LongInterval AuditLevel [Language] [RetryCount] [Prohibition of job definiton] The options for each R/3 Scheduling Agent are: Host workstation (CPU) Name The Workload Scheduler workstation name of the x-agent for this instance of R/3. This must be the same as the workstation Name entry in the x-agent s workstation definition. R/3 Application Server The host name of the R/3 application server. R/3 Gateway Host (optional) The host name of the R/3 gateway system, if different from the R/3 host. R/3 System Name The R/3 system identifier. R/3 Instance The R/3 instance number on R/3 Host. Client Number The R/3 client number for starting jobs. Userid The R/3 user name that Workload Scheduler uses to release R/3 jobs and to connect to the R/3 servers. This user must have batch administration privileges. When R/3 jobs are released by Workload Scheduler, the job log output in R/3 is found under this user name. 8 Version 4.0.1

19 Password The password for Userid. The R/3 user should be given a password that does not expire. Reenter Password Reenter the password defined previously. Short Interval The minimum interval in seconds for R/3 job status updates. The default is 30. Long Interval The maximum interval in seconds for R/3 job status updates. The default is 300. Audit Level The Audit level is used to log Workload Scheduler activities on R/3. A higher level means more messages are logged. Valid values are 0 to 5. Language (optional) The language x-agent uses to log on to the R/3 system. If this entry is omitted, x-agent will use English as the log on language. The syntax for the language is L=xx where xx specifies either the one-byte R/3 language or the two-byte ISO language. For example, L=DE would select German as the log on language of the x-agent. Note: To get the messages of the x-agent in the selected language, you will need a proper message catalog. Currently, only an English message catalog is provided. Retry count (optional) The number of retries to execute an R/3 function module, if the R/3 system becomes unavailable. If you leave this field blank, Workload Scheduler Scheduling Agent for R/3 uses a default value to determine the number of retries. The syntax for the retry count is RETRY=x, where x is the number of retries. Prohibition of job definition If present, this flag prohibits definition of R/3 jobs through Workload Scheduler. The syntax for this flag is NOJOBDEFS. Sample r3options File Entry The following is a sample r3options file entry for an R/3 Scheduling Agent workstation called SAP001: SAP001 SYS01 SYS01 SAP MAESTRO <ENCRYPTED> L=DE RETRY=4 NOJOBDEFS Modifying the r3options File The r3options file can be modified with any text editor. Alternatively: For a UNIX host, log on as root and run the r3setup -maintain command. For a Windows host, log on as administrator and select the R3Opt 1.1 program from the Start menu. Note: If you use a Windows text editor, ensure it does not add any special end-of-line characters. Encrypting R/3 User Passwords on a UNIX Host When you make your entries in the r3options file using the r3setup script, the r3pass value is automatically encrypted before it is written in the file. If you modify the file with a 2. Installation Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 9

20 text editor, you must run the enigma program to encrypt the password before writing it in the file. Run the encryption command as follows: enigma [password] You can include the password on the command line or enter it in response to a prompt. The program returns an encrypted version that you can then enter in the r3options file. Installing the Scheduling Agent on the R/3 System Install r3batch ABAP modules on the R/3 system. Installing the r3batch ABAP modules is explained in detail in R/3 Configuration on page 11. It includes instructions for creating an RFC user and installing the following ABAP modules: J_1O1_BDC_STATUS J_1O1_DATE_TIME J_1O1_JOB_COPY J_1O1_JOB_DELETE J_1O1_JOB_FIND J_1O1_JOB_FINDALL J_1O1_JOB_OPEN J_1O1_JOB_LOG J_1O1_JOB_START J_1O1_JOB_STATUS J_1O1_JOB_STOP 10 Version 4.0.1

21 3 R/3 Configuration Overview To communicate and control job execution on R/3, Tivoli Workload Scheduler requires you to install correction and transport files on the R/3 database system. These steps require an R/3 BASIS Administrator. These procedures add new ABAP/4 function modules to your R/3 system, and several new internal tables. No existing R/3 system objects are modified. Here is an overview of the procedure: 1. Create the authorization profile. 2. Create the Workload Scheduler RFC user ID. 3. Copy the correction and transport files from the Tivoli Workload Scheduler server to the R/3 server. 4. Import correction and transport files into R/3. 5. Verify the installation. 3. R/3 Configuration Creating the Authorization Profile Before you create an RFC user ID for Workload Scheduler batch processing, you must create the profile of the authorizations that the Workload Scheduler user requires. These authorizations differ depending on your version of R/3. The R/3-defined authorizations are found under the Object Class Basis:Administration. Notes: 1. It is possible that S_RFC_ALL is found under the Object Class Cross-application Authorization Objects or Non-application-specific Authorization Objects. 2. For some special jobs, it might be necessary to give additional authorizations to the Workload Scheduler user. For R/3 Versions 3.1g, 3.1h, 3.1i, 4.0x, 4.5x, and 4.6x Create the following authorization profile: 1. Create a profile called ZMAESTRO. Note: Depending on the revision of the R/3 system, the following warning can occur: Choose another profile name (this name does not conform to the standard) Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 11

22 This warning can be ignored or another name can be chosen. 2. Insert the following authorizations: Object Text Authorization S_RFC Auth. check for RFC access S_RFC_ALL S_XMI_PROD Auth. for External S_XMI_ADMIN Management Interfaces (XMI) S_BTCH_ADM Background Processing: S_BTCH_ADM Background administrator S_BTCH_NAM Background Processing: S_BTCH_ALL Background User Name S_BTCH_JOB Background Processing: Operations on Background Jobs S_BTCH_ALL S_XMI_LOG Internal Access Authorizations S_XMILOG_ADM for XMI Log S_SPO_ACT Spool: Actions S_SPO_ALL S_SPO_DEV Spool: Device Authorizations S_SPO_DEV_AL Creating the Workload Scheduler RFC User For Workload Scheduler to communicate with R/3, you must create a user ID in R/3 for Workload Scheduler batch processing. For security reasons, use a new user ID rather than an existing one. 1. Create a new RFC user ID. 2. Give this new RFC user ID the following attributes: The user type should be CPIC or Communications, depending on the R/3 release. A password at least six characters in length; Workload Scheduler requires this password to start or monitor R/3 jobs. If this password changes in R/3, you must update the r3options file with the new password. Assign the appropriate security profiles depending on your version of R/3. Copy the Correction And Transport Files The setup file loads two correction and transport files into the Workload Scheduler home directory. You must copy these correction and transport files to the R/3 server and import them into the R/3 database. 1. On your R/3 database server, log into your R/3 system as an administrator. 2. Copy the control file and data file from the TWShome directory to the following directories on your R/3 database server: copy controlfile /usr/sap/trans/cofiles/ copy datafile /usr/sap/trans/data/ The names of the controlfile and datafile vary from release to release. Some example file names are K000xx.tv1 (control file) and R000xx.tv1 (data file). 12 Version 4.0.1

23 Import ABAP/4 Modules into R/3 This procedure generates, activates, and commits new ABAP/4 function modules to your R/3 system and several new internal tables. No existing R/3 system objects are modified. 1. Change to the following directory: cd /usr/sap/trans/bin 2. Add the transport file to the buffer: tp addtobuffer transport sid where: transport is the transport request file. sid is your R/3 system ID. The name of the transport request is tv1k000xxx. 3. Run the tp tst command to test the import: tp tst transport sid After you have run this command, examine the log files in the /user/sap/trans/log directory for error messages. Warnings of severity level 4 are normal. If you have errors, check with a person experienced in correction and transport, or try using unconditional modes to do the import. 4. Run the following command to import all the files in the buffer: tp import transport sid This command generates the new ABAP/4 modules and commits them to the R/3 database. They automatically become active. After you have run this command, examine the log files in the /user/sap/trans/log directory for error messages. Warnings of severity level 4 are normal. If a problem is encountered, use unconditional mode when executing this step: tp import transport sid U R/3 Configuration 5. When the import is complete, check the log files to verify that the import was successful. The log files are in the /usr/sap/trans/log directory. Troubleshooting the R/3 Connection If you are unable to submit R/3 jobs using Workload Scheduler after the R/3 configuration, perform the following tests: Ensure you can ping the R/3 system from the Workload Scheduler system. This will show basic network connectivity. Run the following telnet command to verify connectivity: telnet systemname 33xx where systemname is the system name or IP address of the R/3 server and xx is the R/3 instance. Log on to the R/3 system as an administrator and verify that the Workload Scheduler RFC user (created in the Creating the Workload Scheduler RFC User on page 12) exists. Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 13

24 Create a new Workload Scheduler job to be run under R/3, and add the following advanced options: -debug -trace These options are selected using the radio buttons in the the Properties - Job Definition Task page in the Job Scheduling Console. Using the -debug option, additional debug information is included in the job stdlist file (in Workload Scheduler). When you use the -trace option, a trace file is created in the Workload Scheduler home directory. On UNIX, this trace file is called dev_rfc. On Windows, the file is called rfcxxxxx_xxxxx.trc. Ensure you delete the trace option from the job after you have performed debug procedures. The trace file can become very large and unmanageable. Note: Typically these options are for debugging the scheduling agent and should not be used in standard production. Verify that an R/3 gateway process is active on the R/3 system to which you are connecting. Verify that a sapgwnn entry is present in the Workload Scheduler system services file. Note: If YP/NIS (or any other directory service) is managing the services entries, verify that the master services file on your Workload Scheduler system is being used rather than the local services file. If you are installing on an AIX system that does not use U.S. English, you must install the U.S. Language Environment on the Workload Scheduler workstation and the R/3 database workstation. Otherwise the error BAD TEXTENV (or a similar error message) might appear in the dev_rfc trace file and connections to R/3 will fail. Changing the Workload Scheduler RFC User ID Password If the password of the Workload Scheduler RFC user ID is modified after the initial installation, the r3options file must be updated with this change. Option 1 For a UNIX host, log on as root and run the r3setup -maintain command. For a Windows host, log on as administrator and run the R3Opt1.1 program from the Start menu. In either case, you are prompted to specify a new password for the Workload Scheduler RFC user ID Option 2 On UNIX, log on as root to the system where Workload Scheduler is installed. On Windows, log on as an administrator and start a DOS shell on the system where Workload Scheduler is installed. 1. Generate an encrypted version of the new password using the enigma command in TWShome/bin. To do this, in a command shell, type: 14 Version 4.0.1

25 enigma newpass where newpass is the new password for the Workload Scheduler RFC user ID. The enigma command prints an encrypted version of the password. 2. Copy the encrypted password into the r3options file, which is located in the TWShome/methods directory. The file can be edited with any text editor. Ensure you copy the password exactly, preserving upper case, lower case, and punctuation. The encrypted password looks similar to: #TjM-pYm#-z82G-rB If the encrypted password is mistyped, Workload Scheduler will not be able to start or monitor R/3 batch jobs. Migrating from Previous Versions This version of the Tivoli Workload Scheduler Scheduling Agent for R/3 supports all releases of R/3 from 3.1g to 4.6x. To achieve R/3 XBP certification for R/3 release 4.0 and 4.5, a few changes had to be made to the scheduling agent. The Tivoli Workload Scheduler Scheduling Agent for R/3 4.x uses the official R/3 RFC interfaces for job scheduling. These are: The SXMI_XBP interface for R/3 releases 3.1g to 4.0x The BAPI_XBP interface since release 4.5a To avoid conflicts with other vendors, the Workload Scheduler ABAP modules now belong to the Workload Scheduler partner namespace J_1O1_xxx. After you have completed the imports as described in Import ABAP/4 Modules into R/3 on page 13, the RFC J_1O1_xxx function modules are installed on your system. If you had a previous installation of Tivoli Workload Scheduler Scheduling Agent for R/3 on your system, you can delete the following function modules from your R/3 system: Z_MAE2_BDC_STATUS Z_MAE2_DATE_TIME Z_MAE2_JOB_COPY Z_MAE2_JOB_DELETE Z_MAE2_JOB_FIND Z_MAE2_JOB_FINDALL Z_MAE2_JOP_OPEN Z_MAE2_JOB_LOG Z_MAE2_JOB_START Z_MAE2_JOB_STATUS Z_MAE2_JOB_STOP These are old versions of the Tivoli ABAP functions, which belong to the customer name space. You can also delete the function group YMA3. It is not necessary to delete the function modules and the function group, but you should do so if you want to clean up your system. Print Paramater and Job Class Issues Tivoli Workload Scheduler Scheduling Agent for R/3 Version 4.x uses the official R/3 RFC interfaces for job scheduling. When you migrate from previous versions of Tivoli Workload Scheduler Scheduling Agent for R/3, there can be problems with print parameters in jobs launched by Workload Scheduler. This is because of limitations in the RFC interfaces. 3. R/3 Configuration Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 15

26 The following table shows the supported print parameters: Print Parameter 3.1x 4.0x 4.5x 4.6x output device U U U U print immediately U U U U delete after output U U U U number of copies U U U U archiving mode U U U U authorization U U U U selection cover page x U U U sap cover page U U U U spool retention period U U U U recipient x x U U lines x x U U columns x x U U To resolve the loss of print parameters during job copy, install the appropriate R/3 Support Package as stated in the R/3 notes and The same applies to the job class. Official R/3 interfaces allow only class C jobs. Installing the R/3 Support Package also resolves this issue. 16 Version 4.0.1

27 4 Setting Up for Tivoli Workload Scheduler This chapter describes how to: Create the Scheduling Agent for R/3 workstation in the Workload Scheduler network Create jobs in Workload Scheduler that correspond to jobs already in the R/3 database Create jobs in the R/3 database controlled by Workload Scheduler Create job streams that use Scheduling Agent for R/3 jobs Defining a Scheduling Agent Workstation R/3 Scheduling Agent workstation definitions are required for each instance of R/3 that will run Workload Scheduler controlled jobs. To define an R/3 Scheduling Agent workstation: 1. In the Tivoli Job Scheduling Console, highlight the scheduler engine. 2. From the Selected menu, select New Workstation. The Properties - Workstation in Database window is displayed. 3. In the Name field, enter a scheduler name for the R/3 x-agent workstation. This must be the same name that was entered in the r3options files as the xagent parameter. The name can contain eight alphanumeric characters, or 16 alphanumeric characters if you are using the expanded database option. The workstation name must start with a letter. 4. In the Node field, type null. 5. In the TCP Port field, type 1. This field is not valid for an R/3 Scheduling Agent workstation, but requires at least one number other than In the Operating System field, select OTHER. 7. In the Domain field, select the domain for this workstation. Note that the domain for the Scheduling Agent for R/3 must be the same as the domain for the host workstation. 4. Setting Up for Tivoli Workload Scheduler 8. If your scheduler network is using the Time Zone option, enter the time zone of the Scheduling Agent workstation. 9. In the Description field, enter a description for the scheduling agent. This field is an optional text description of the workstation and can be up to 40 characters. 10. Select the Workstation Type as scheduling agent. The Auto Link checkbox is automatically selected, and the Ignore checkbox is enabled, but deselected. Refer to the Tivoli Workload Scheduler Reference Guide for more information. Full Status, Resolve Dep, and Server are disabled because they are not applicable to R/3 workstation definitions. Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 17

28 11. In the Access Method field, enter the name of the R/3 access method, r3batch. This file is run by the scheduler host to connect to an instance of R/ In the Host field, enter the scheduler name of the scheduling agent host. This is the scheduler master, fault-tolerant agent, or standard agent that hosts the R/3 scheduling agent definition. 13. Select OK to save the workstation definition. Defining Scheduling Agent Jobs To control job execution on the R/3 workstation from Tivoli Workload Scheduler you must define the following: Define jobs in R/3 that you want to run under Workload Scheduler control. You can define these jobs using standard R/3 tools, or the Job Scheduling Console. Define jobs in Workload Scheduler that correspond to the jobs in R/3. The Workload Scheduler job definitions are used in scheduling and defining dependencies, but the R/3 jobs are actually run. Defining a Job in Workload Scheduler This procedure creates a new job definition in the Workload Scheduler database for a job that already exists in the R/3 database. 1. In the Job Scheduling Console, highlight the scheduler engine. 2. From the Selected menu, select New Job Definition. The Select a Task Type window is displayed. 3. From the Task Type scroll down menu, select the SAP job type and click OK. The Properties - Job Definition window is displayed. 4. In the Name field, enter a scheduler name for the R/3 job. The name can contain 8 alphanumeric characters or 40 alphanumeric characters if you are using the expanded database option. The job name must start with a letter. 5. In the Workstation field, click the ellipsis (...) to open a Find window to select an available workstation. 6. In the Description field, enter a description for the job. This field is an optional text description of the job and can be up to 64 alphanumeric characters. 7. In the Login field, enter the Workload Scheduler log on ID that is used to run the job. 8. Click Add Parameter to add any predefined parameters to the log on ID. 9. In the Recovery Options fields, specify any recovery options for the R/3 job. Refer to the Tivoli Workload Scheduler Reference Guide for information about recovery options. 10. Select Task. 11. Next to the Job Name field, click the ellipsis (...). The SAP Pick List window is displayed. 12. Use the pick list to find and select an R/3 job and click OK. The job information is is displayed in the Task page. 13. Click OK to save the job definition to the scheduler database. 18 Version 4.0.1

29 Defining a Job in R/3 To create R/3 jobs that are controlled by Workload Scheduler, use either of the following: The standard R/3 tools for defining jobs The Job Scheduling Console Refer to the R/3 documentation for information on creating jobs with R/3 tools. When creating jobs in R/3, do not assign a start time and do not specify any dependencies. These are specified and controlled in Workload Scheduler. The job is identified in Workload Scheduler by its R/3 job name and job ID. The same job can be scheduled to run repeatedly by Workload Scheduler without having to redefine it each time in R/3. Note: For R/3 jobs controlled by Workload Scheduler, the job log output in R/3 is found under the user name defined in the r3user option of the r3options file. Defining a Job in Workload Scheduler and R/3 This procedure creates a new job definition in the Workload Scheduler database and a new job definition in the R/3 database. 1. In the Job Scheduling Console, highlight the scheduler engine. 2. From the Selected menu, select New Job Definition. The Select a Task Type window is displayed. 3. From the Task Type scroll down menu, select the SAP job type and click OK. The Properties - Job Definition window is displayed. 4. In the Name field, enter a scheduler name for the R/3 job. The name can contain eight alphanumeric characters, or 40 alphanumeric characters if you are using the expanded database option. The job name must start with a letter. 5. In the Workstation field, click the ellipsis (...) button to open a Find window to select an available workstation. 6. In the Description field, enter a description for the job. This field is an optional text description of the job and can be up to 64 alphanumeric characters. 7. In the Login field, enter the Workload Scheduler log on ID that is used to run the job. 8. Click Add Parameter to add any predefined parameters to the log on ID. 9. In the Recovery Options fields, specify any recovery options for the R/3 job. Refer to the Tivoli Workload Scheduler Reference Guide for information about recovery options. 10. Select Task. 11. Next to the Job Name field, click New. The SAP Job Definition window is displayed. 12. O the SAP Job page, enter information about the job you are creating: a. In the Job Name field, type an R/3 job name. b. In the User Name field, type the name of the R/3 user who runs the job. c. In the Target Host field, type the name of the target workstation where this job is run. 13. In the Steps page you must add an ABAP or external program to the R/3 job. a. Click the Add row button to add a row to the steps table. b. Double-click in the Type field and select whether this is to be an ABAP or External step. 4. Setting Up for Tivoli Workload Scheduler Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 19

30 c. In the Name field, enter an ABAP name or a fully qualified path and file name for an external program. d. In the Userfield, type the name of the R/3 user who runs this step. e. In the Var/Parm field, type a variant name or a parameter, if necessary. Variants are used with ABAPs, and parameters are used with external programs, but both are optional. Not all ABAPs require variants and not all external programs require parameters. f. In the Target Host field, enter the R/3 workstation where this step runs. Target hosts are only required for external programs. 14. When you have completed creating the ABAP or external program steps, click OK. The R/3 job definition is saved to the R/3 database and the window is closed. If the R/3 job was successfully saved to the R/3 database, the Properties - Job Definition Task page should display an R/3 job ID. 15. Click OK in the Properties - Job Definition window to save the job definition to the scheduler database. Defining Scheduling Agent Job Streams R/3 job streams are scheduled in the same manner as other Workload Scheduler job streams and can include dependencies, run cycles, time restrictions, and other controls, except Files dependencies. Before creating job streams you must define the R/3 jobs to the Workload Scheduler database. To define a job stream using R/3 jobs: 1. In the Job Scheduling Console, select the scheduler engine. 2. From the Selected menu, select New Job Stream. The Job Stream Editor and Properties - Job Stream windows are displayed. 3. In the Properties - Job Stream window, in the Name field, enter a name for the job stream. The name can contain eight alphanumeric characters, or 16 alphanumeric characters if you are using the expanded database option. The job stream name must start with a letter. 4. In the Workstation field, enter the name of the R/3 sheduling agent workstation that runs this job stream or use the ellipsis (...) button to search for an R/3 workstation. 5. When you have finished, click OK to close the Properties - Job Stream window. All the fields in the Properties - Job Stream window, other than Name and Workstation, are optional. 6. Add the R/3 jobs that you want to be part of this job stream: a. In the Job Stream Editor, from the Actions menu, select Add Job, then Job Definition. The Properties - Job Definition window is displayed. b. In the Name field, enter the Workload Scheduler name of the R/3 job you want to add to the job stream. c. Repeat these steps to add all the desired R/3 jobs. Note: If you add two or more jobs you can specify dependencies between these jobs. 7. Create run cycles that determine the days that this job stream will run. 8. Save the job stream by clicking Save from the File menu. 20 Version 4.0.1

31 5 R/3 Window Reference 5. R/3 Window Reference This chapter provides reference information about the windows used to define jobs in Tivoli Workload Scheduler. Some of these windows are used to make changes in the R/3 database. Properties - Job Definition This window is used to define jobs to the Workload Scheduler database. It has two pages, the General page and the Task page. The General page is for specifying Workload Scheduler job information. The Task page is for specifying R/3 job information. General Page This page is used to define Workload Scheduler job information. Information entered on this page is saved to the scheduler database. Figure 1. Properties - Job Definition General Page Task Type Displays the task type. This field is determined by your entry in the Select a Task Type window. It should read SAP for all Scheduling Agent for R/3 jobs. Name Enter the Workload Scheduler name for this job. The job name can have up to eight Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 21

32 alphanumeric characters for unexpanded database, or 40 alphanumeric characters for expanded database. The name can include a dash and underscore, but must begin with a letter. Workstation Click the Find button (...) to search for and select a workstation or workstation class that runs this job. Description Enter a description for this job. The description can have up to 64 characters. Login Enter a valid UNIX or Windows log on name that runs the r3batch method.the login script can have up to 47 characters. Special characters must be in quotes. Add Parameter Click this to add a parameter to the login field. Recovery Options Refer to the Tivoli Workload Scheduler Reference Guide for information about recovery options. Task Page This page is used to enter the information about the R/3 job that is actually run. Information entered in this page is saved to the scheduler database. Figure 2. Properties Job Definition Task Page Task Type Displays the task type. This field is determined by your entry in the Select a Task Type window. It should read SAP for all Scheduling Agent for R/3 jobs. Job Name Displays the name of the R/3 job to be run. Click the Find button(...) or click New to complete these fields. 22 Version 4.0.1

33 Find button The Find button is displayed as an ellipsis (...). Click this to display the SAP Pick List window. This window is used to search the R/3 database for jobs. New button Click New to display the SAP Job Definition window. This window is used to create or modify the tasks within an R/3 job. Refer to R/3 Job Definition for more information. User Name Displays the R/3 user who runs the job. Read-only. Job ID Displays the R/3 job ID. Read-only. Class R/3 Job Definition Displays the class of the R/3 job. All jobs run by Workload Scheduler are run as class C, regardless of the R/3 class defined. Also, all R/3 jobs created with Workload Scheduler are given the class C. Read-only. Details Click Details to display the R/3 Job Details window. This windows containss information about the job and previous executions. Advanced Options The following advanced options can be added to the job definition: -debug Use this option to include additional debug information in the job stdlist file. -trace Use this option to create a trace file called dev_rfc in the Workload Scheduler home directory. Ensure you delete the trace option from the job after you have performed debug procedures. The dev_rfc file can become very large and unmanageable. Note: Typically, these options are for debugging the Scheduling Agent and should not be used in standard production. Disable BDC Wait Select this check box to disable the BDC wait option. If you leave this check box blank, you specify that an R/3 job launched by Workload Scheduler will not be considered complete until all of its BDC sessions are complete. This prevents other Workload Scheduler jobs that are dependent on the R/3 job from being launched until its BDC sessions complete. For more information on the DBC wait option, see BDC Wait on page 2. Status Click Status to display the status of the job. This window is used to define jobs to the R/3 database. This window has two tabs, the R/3 Job tab and the Steps tab. The R/3 Job tab is for specifying R/3 job information; the Steps tab is for creating the ABAP or External program steps that make up the job. Note that the Steps Tab changes slightly depending on whether you are creating an ABAP step or an external program step. 5. R/3 Window Reference Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 23

34 R/3 Job Page This page is used to define the R/3 job definition information for R/3 jobs you are creating or modifying. Information entered on this page is saved in the R/3 database. Figure 3. SAP Job Definition R/3 Job Page Job Name Type the name of the R/3 job. User Name Type the name of the R/3 user who runs this job. Job ID Displays the ID number of the job defined by the R/3 application. Read-only. Class Displays the class of the R/3 job. All jobs run by Workload Scheduler are run as class C, regardless of the R/3 class defined. Also, all R/3 jobs created with Workload Scheduler are given the class C. Read-only. Target Host Enter the R/3 workstation that runs the job. This option only applies to external programs. Steps Page (ABAP) This tab is used to define the ABAP steps of an R/3 job. Information entered on this tab is saved to the R/3 database. 24 Version 4.0.1

35 5. R/3 Window Reference Figure 4. SAP Job Definition Steps Page (ABAP) Type Specify the type of step you are creating, ABAP or external program. Name Type the name of the ABAP module you are adding to the job. Var / Parm Type any variants you want to use with the ABAP step. Variants are used for ABAP modules, and parameters are used for external programs. Target Host This field is not used with ABAP modules. Print Parameters Specify any print parameters you want to use with this ABAP step: Number of Copies Specify how many copies of a document you want to print. List Lines Specify the number of lines per list page. Destination Specify the name of the destination output device. Columns Specify the column character width. The maximum line width of a list 255 characters. Recipient Specify the name of the spool request recipient. The name will appear on the cover sheet of the hardcopy printouts. The default valueof the recipient name is the current user name. Print Immediately Select this check box to send the spool request to the output device at once. Insert Step Button Click this button to insert a new ABAP or external program step to the job. The row is added to the top of the list of steps. Tivoli Workload Scheduler Scheduling Agent for R/3 User s Guide 25