Tivoli OPC Extended Agent for SAP R/3. Version 3.0

Transcription

1 Tivoli OPC Extended Agent for SAP R/3 Version 3.0

2 Tivoli OPC Extended Agent for SAP R/3 (June 1998) Part number: GC Copyright Notice Copyright 1998 by Tivoli Systems, an IBM Company, including this documentation and all software. All rights reserved. May only be used pursuant to a Tivoli Systems 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 Tivoli Systems. 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. 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 Corporation. Trademarks The following product names are trademarks of Tivoli Systems or IBM Corporation: AIX, IBM, OS/2, RISC System/6000, Tivoli Management Environment, and TME 10. Microsoft, Windows, and the Windows 95 logo are trademarks or registered trademarks of Microsoft Corporation. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited. Other company, product, and service names mentioned in this document may be trademarks or servicemarks of others. Notice 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 Tivoli Systems or IBM s valid intellectual property or other legally protectable right, 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

3 these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, New York

4

5 Preface The information in this manual is intended for administrators of the Tivoli Workload Scheduler SAP R/3 Extended Agent. It provides information on how to set up and manage job scheduling of SAP R/3 jobs with Tivoli Operations Planning and Control using the SAP R/3 Extended Agent. Who Should Read This Guide The target audience for this guide is system managers who will install and configure OPC Tracker Agents, and system administrators who will perform daily administration tasks. Users of the guide should have some knowledge of: Tivoli OPC Controller and Tracker Agent, and SAP R/3 operating environment Operating system of the machine running the Tivoli OPC Tracker Agent Prerequisite and Related Documents The following documents contain information related to the installation and operation of the Tivoli OPC Tracker Agents : TME10 OPC : Tracker Agents for OS/2 and Windows NT** Platforms Installation and Operation TME 10 OPC : Tracker Agents for AIX, UNIX**, VMS** and OS/390 Open Edition Installation and Operation What This Guide Contains The sections are: Section 1 - Introduction, provides an introduction to the product features and requirements Section 2 - Installation and Configuration, describes how to install and configure the extended SAP R/3 agent, on both the tracker agent and SAP R/3. Tivoli OPC SAP R/3 Extended Agent Supplement v

6 Section 3 - Defining and Scheduling Jobs with OPC, describes how to define and schedule SAP R/3 jobs from OPC. Section 4 - R/3 Options File, provides information on how to define the R/3 options file. Conventions Used in This Guide The following conventions are used in this manual to describe the graphical and command line user interfaces. Literal Text Variables Special Characters Menu Commands Commands, keywords, programs, and pathnames are shown in courier bold typeface. They must be spelled as shown. In the following example, console is a command name, and sess and sys are option keywords. console [sess sys] Variables are placeholders that must be replaced by actual values. They are shown in courier italic typeface. In the following example, filename must be replaced with an actual file name. add filename Special characters in syntax statements must be entered as shown with the exception of the following, which are used as notation operators: [ ] brackets indicate optional items { } braces indicate required items vertical bars indicate choices between items... ellipses indicate repetition Selection of menu items more than two levels deep is shown in bold typeface with greater than signs (>) indicating the order items are selected. For example: From the Run menu, select Programs > Utils > Zapper. vi Version 3.0

7 Hierarchical Displays Selection of objects in a hierarchical display is shown in bold typeface with greater than signs (>) indicating the order objects are selected. For example: In the All Folders list, select My Computer > FAT (D:) > Applications > Tally, and then double-click ReadMe.doc. For object names that are variable, the placeholders are shown in italic typeface. For example: In the Configuration window, select Local Configuration > domain_name > Nodes > node_name > Queues. Contacting Customer Support If you encounter difficulties with any Tivoli products, you can enter to view the Tivoli Support home page. After you link to and submit the customer registration form, you will be able to access many customer support services on the Web. Use the following phone numbers to contact customer support in the United States: the Tivoli number is (1-800-TIVOLI8) and the IBM number is (press or say 8 after you reach this number). Both of these numbers direct your call to the Tivoli Customer Support Call Center. We are very interested in hearing from you about your experience with Tivoli products and documentation. We welcome your suggestions for improvements. If you have comments or suggestions about this documentation, please send to pubs@tivoli.com. Tivoli OPC SAP R/3 Extended Agent Supplement vii

8 viii Version 3.0

9 Contents 1. Introduction Features SAP R/3 Extended Agent Process Customer Support Installation Compatibility Installing with an OPC Tracker Agent for UNIX Installing with an OPC Tracker Agent for Win NT The Setup Program Choose Destination Location Copying Files Options Editor Folder Selection Installing the X-agent on the SAP R/3 System Configure the X-agent on Tracker Agent System Scheduling SAP R/3 Jobs with Tivoli OPC Defining Jobs in SAP R/ Defining SAP R/3 Workstations in OPC R/3 Options File The R/3 Options File Entry Syntax Example The r3setup Script on UNIX Host Encrypting R/3 User Passwords on UNIX Host The Options Editor on a Windows NT X-Agent Options Editor Displaying Records in the Options File Deleting Records in the Options File Adding Records to the Options File Modifying an Entry in the Options File (5/98) Contents ix

10 x Contents (5/98)

11 1 Introduction Tivoli Workload Scheduler s SAP R/3 Extended Agent (SAP R/3 X- Agent) gives you the ability to schedule and control R/3 jobs using the job scheduling features of Tivoli OPC. With Tivoli OPC, the submission and tracking of a SAP R/3 job is done from the OPC controller via a Tracker Agent connection. The OPC controller running on OS/390 submits the R/3 job to an OPC Tracker Agent that in turn submits the job to the SAP R/3 system using the SAP R/3 X-Agent. When a SAP R/3 job submitted by OPC changes its status, the OPC controller is notified of the status changes. From the OPC controller it is possible to retrieve the job log of the submitted SAP R/3 jobs. (5/98) Introduction 1-1

12 Features Features Use Tivoli OPC s standard job dependencies and controls. Schedule R/3 jobs to run on specified days and times, and in a prescribed order. Define interdependencies between R/3 jobs and jobs that run on different platforms, including UNIX, Windows NT, and OS/390. SAP R/3 Extended Agent Process The R/3 X-Agent is defined in a standard OPC workstation definition, which associates the OPC workstation with the SAP R/3 X-Agent and identifies the access method name as r3batch. When invoked, the method reads configuration information from an options file named r3options. Each instance of R/3 is defined as a separate OPC workstation, and each has a separate entry in the r3options file. To launch an R/3 job, the OPC Tracker Agent (where the X-Agent is installed) executes r3batch, passing it information about the job. Using the workstation s 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 looks up the job in the R/3 batch table, marks it as runnable and sets its start time to "now" to launch the job. It then monitors the job through completion, writing job progress and status information to the job s standard list file. For more information about job management, refer to the Tivoli OPC documentation. Customer Support If you have any questions about the product, please call the Tivoli Customer Support Call Center: TIVOLI - 8 ( ) or Introduction (5/98)

13 Customer Support You can also contact Tivoli at the following addresses: Company home page: Support home page: address for technical support: address for documentation comments: (5/98) Introduction 1-3

14 Customer Support 1-4 Introduction (5/98)

15 2 Installation This section contains information on installing and configuring the SAP R/3 X-Agent software. SAP R/3 X-Agent installation is divided into two steps. In the first step, the X-Agent components are installed on the system where the Tivoli OPC Tracker Agent is running. In the second step, some X-Agent components need to be installed and configured on the system where SAP R/3 is running. Compatibility To use the new features of SAP R/3 X-Agent version 3.0 with Tivoli OPC, you must have installed Tivoli OPC Tracker Agent Version or later and Tivoli OPC Controller Version or later. Insure that you are working with the correct level of Tivoli OPC Tracker Agent and Tivoli OPC Controller features before using the SAP R/3 X-Agent. Installing with an OPC Tracker Agent for UNIX Follow these instructions to install the SAP R/3 X-Agent on a UNIX system running a Tivoli OPC Tracker Agent for UNIX: 1. Log in as root and change to the OPC Tracker Agent home directory (the $EQQHOME directory, usually /home/tracker). 2. Mount the installation tape or CD-ROM, and extract the software. From tape: tar xv[f tape] From CD: tar xvf cd/maestro/platform/sap.tar (5/98) Installation 2-1

16 Installing with an OPC Tracker Agent for Win NT where: tape The pathname of your tape drive. cd The pathname of your CD-ROM drive. platform Your platform type. One of the following: AIX IBM DECUX Digital UNIX HPUX Hewlett Packard SOLARIS Sun Solaris 3. Run the r3setup script, to decompress the X-Agent files and perform the initial setup: If you are updating existing software, run r3setup to decompress and install the new files: /bin/sh r3setup -update If you are installing the software for the first time, run r3setup to decompress and install files, and prompt for the initial values for the r3options file: /bin/sh r3setup ñnew 4. Follow the instructions provided by the r3setup script to install the SAP R/3 X-Agent. For information about the r3options file and r3setup parameters, refer to section 4, R/3 Options File. Installing with an OPC Tracker Agent for Win NT 1. Log in as a user in the Administrators group or the Domain Administrators group, as appropriate. 2. Insert the installation CD-ROM. 3. Exit any Windows applications, including the File Manager. 4. Run the setup.exe program: D:\maestro\platform\maestro\setup.exe where D is your CD-ROM drive letter and platform is either i386 or Alpha. 2-2 Installation (5/98)

17 The Setup Program The Setup Program The Welcome screen provides useful information about installing the SAP R/3 X-Agent software. To continue, click on the Next button. Choose Destination Location Use the Choose Destination Location screen to define the directory to install the SAP R/3 X-Agent s method. Click the Browse... button, and (5/98) Installation 2-3

18 Copying Files locate and select the METHODS subdirectory in OPC Tracker Agent s home directory ($EQQHOME). Click the Next button to copy the files. Copying Files Program files are copied to the specified directory and the progress is indicated as shown below. Click the Cancel button to interrupt the copy. When the copy is complete, you are informed that the options editor will be started. Click the OK button. If this is a new installation, you are informed that the r3options file does not exist, and you are asked whether you want to create it. Click the OK button to continue. Options Editor A set of options must be entered for each instance of a SAP R/3 X-Agent. The options are managed with the Options Editor, and are saved in a file named r3options in the METHODS subdirectory of the OPC Tracker Agent's home directory. 2-4 Installation (5/98)

19 Options Editor The option fields are: Host CPU Name Audit Level The name of the OPC workstation associated with this R/3 X-Agent, which will be used by OPC to submit R/3 jobs. For more information, refer to Scheduling SAP R/3 Jobs in OPC on page 3-8. The Audit level is used to log OPC activities on R/3. A higher level means more messages are logged. Valid values are 0 to 5. For R/3 versions below 3.1G, enter a value of 0. (5/98) Installation 2-5

20 Options Editor R3 Host R3 Gateway Host R3 System Name Instance Client Number Userid Password Re-enter Password Short Interval The host name of the R/3 database server. The host name of the R/3 gateway system, if any. The R/3 system identifier. The R/3 instance number on the R3 host. The R/3 client number for starting jobs. The R/3 user name that the SAP R/3 X-Agent will use to start R/3 jobs and to connect to the R/3 servers. This user must have batch administration privileges. The password for Userid. It is recommended that the R/3 user be given a password that does not expire. Re-enter the password defined above for verification purposes. The minimum interval in seconds for R/3 job status updates. The interval is lengthened as long as a job continues to run until the Long Interval is reached. The default is 30. Long Interval The maximum interval in seconds for R/3 job status updates. The default is 300. When you have entered the options, click the Done button to continue, or, if you intend to add records for other X-Agents, click the Next button to save the current record and move to the next. Repeat the process until you have made entries for each instance of a SAP R/3 X-Agent. Use the Previous button at any time to move to the previous record. To delete an entry, click the Delete button. Click the Done button to continue with the setup program. The Options Editor can also be accessed by running the program r3opt.exe at any time following the initial installation to add, change, and delete entries. For more information, refer to The Options Editor on a Windows NT X-Agent on page Installation (5/98)

21 Folder Selection Folder Selection Select a folder for the program icons, as described on the Folder Selection screen, and click the Next button to continue. You are asked to verify the folder name. Click OK to complete the installation. Installing the X-agent on the SAP R/3 System You must install a file called r3batch on your SAP R/3 system. Installing r3batch is explained in the readme.r3 file, which is shipped with the product files. It includes instructions for creating an R/3 user, and installing the following ABAP modules: 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_JOB_OPEN Z_MAE2_JOB_READLOG (5/98) Installation 2-7

22 Configure the X-agent on Tracker Agent System Z_MAE2_JOB_START Z_MAE2_JOB_STATUS Z_MAE2_JOB_STOP Configure the X-agent on Tracker Agent System Before using the SAP R/3 X-Agent to submit R/3 jobs with Tivoli OPC, the following customization steps may be required: 1. Add new entries in the r3options file. The r3setup script creates an entry in the r3options file for the OPC workstation name that was specified during the installation steps above. The SAP R/3 X-Agent uses the information stored in the r3options file to set R/3-specific parameters. This information is retrieved by the X-Agent using the OPC workstation name as a key. If you want to be able to submit SAP R/3 jobs from more than one OPC workstation, you must have an entry in the r3options file for each OPC SAP workstation. To add a new entry in the r3batch file, run the r3setup ñmaintain command. 2. Create the r3batch.opts file. After the SAP R/3 X-Agent has been installed, you can optionally create a file named r3batch.opts in the METHODS subdirectory of the OPC Tracker Agent home directory. Add the following entries to the file: LJuser=launch_user IFuser=info_user JobDef=job_definition where: launch_user is the user name on the OPC Tracker Agent host computer (UNIX or Windows NT) under which the method runs to launch R/3 jobs. For example: tracker. This name overrides the name entered in all job definitions. For more information, refer to Scheduling SAP R/3 Jobs in OPC on page Installation (5/98)

23 Configure the X-agent on Tracker Agent System info_user is the user name on the OPC Tracker Agent host computer (UNIX or Windows NT) under which the method runs to retrieve a list of R/3 jobs. It must be the same as the LJuser above. Job_definition should be set to r3batch. 3. Modify the r3options file. If necessary, you can modify the r3options file to change options, or make entries for additional instances of R/3, if any. For more information, see section 4, R/3 Options File. (5/98) Installation 2-9

24 Configure the X-agent on Tracker Agent System 2-10 Installation (5/98)

25 3 Scheduling SAP R/3 Jobs with Tivoli OPC OPC Controller submits SAP R/3 jobs via the R/3 X-Agent. The OPC Controller sends a submit event to the OPC Tracker Agent that in turn invokes the SAP R/3 X-Agent component to start and track the job on the SAP R/3 system. The definition of the workstation in OPC has been enhanced to allow the specification of the access method. When this information is specified, the Tracker Agent will submit all the jobs defined on that workstation by means of the specified access method. The access method for SAP R/3, called r3batch, must be installed on the machines where the OPC Tracker Agent associated with these workstations run. (5/98) Scheduling SAP R/3 Jobs with Tivoli OPC 3-1

26 Defining Jobs in SAP R/3 To launch a job on an R/3 X-Agent, the OPC Tracker Agent executes r3batch and passes it information about the job. Using the OPC 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 looks up the job in the R/3 batch table, marks it as runnable and sets its start time to "now" to launch the job. It then monitors the job through completion, writing job progress and status information to the job s standard list file. To schedule and control a SAP R/3 job from Tivoli OPC, you must: 1. Define in SAP R/3 the jobs that you want to start and track using OPC. You can define these jobs using standard SAP R/3 tools. 2. Define one or more workstations in the OPC Controller associated with the SAP R/3, and make sure that the corresponding entry is set in the r3options file on the Tracker Agent side. 3. Define operations in OPC that correspond to the jobs to be scheduled in SAP R/3. 4. Schedule and control SAP R/3 jobs from the OPC Controller. For more information about general concepts of job management with OPC, refer to the manuals TME 10 OPC Monitoring and Controlling the Workload and TME 10 OPC Planning and Scheduling the Workload. Defining Jobs in SAP R/3 To define a job in R/3, use the standard R/3 tools for defining jobs. Refer to the SAP R/3 documentation for information on creating the job with R/3 tools. Do not assign a start time and do not specify any dependencies. These are specified and controlled in OPC. The job is identified in OPC by its R/3 job name and job id. The same job can be scheduled to run repeatedly by OPC without having to redefine it in R/ Scheduling SAP R/3 Jobs with Tivoli OPC (5/98)

27 Defining SAP R/3 Workstations in OPC Note: For R/3 jobs controlled by OPC, the job log output in R/3 is found under the user name defined in the r3user option of the r3options file. Refer to section 4, R/3 Options File for more information. Note: R/3 jobs have an authorization user name, which may be different for each step in the job. Normally, this name defaults to the user that created the job. For R/3 jobs run by OPC, the authorization user fields are not changed. Permissions are neither gained nor lost relative to running the same jobs without OPC. Defining SAP R/3 Workstations in OPC OPC requires a workstation definition for each end node where a job is submitted. A workstation definition is required for each instance of the R/3 X-Agent that will execute SAP R/3 jobs submitted by OPC. In the OPC Controller, more than one workstation can be defined for an OPC Tracker Agent. To enable a workstation to submit SAP R/3 jobs, this workstation must be defined in the following way: Its destination must be the name (specified in the ROUTOPTS statement of the OPC parmlib) of the Tracker Agent where the SAP R/3 X-Agent is installed. Its associated access method name must be set to r3batch. The following figures show an example of a SAP R/3 workstation named SAP1 that is associated to a Tracker Agent where the SAP R/3 X-Agent is installed. All jobs submitted on that workstation will be handled as SAP R/3 jobs. (5/98) Scheduling SAP R/3 Jobs with Tivoli OPC 3-3

28 Defining SAP R/3 Workstations in OPC To set access method parameters for an OPC workstation, enter m on the command line of the above panel. Normal workstations do not have access method data associated with them, while workstations handling SAP R/3 jobs must have the access method name set to r3batch. 3-4 Scheduling SAP R/3 Jobs with Tivoli OPC (5/98)

29 Defining OPC Operations for SAP R/3 Jobs The Node Address and Port Number fields are optional fields and are not used when you specify r3batch as the access method name. Defining OPC Operations for SAP R/3 Jobs OPC operation definitions are required for each R/3 job you intend to schedule. R/3 jobs are defined like other OPC jobs and include job name and R/3-specific options. An OPC application (as defined in the OPC database) can contain operations that can be both SAP R/3 operations and normal operations, you can also create dependencies between a R/3 operation and a normal operation. OPC operations that correspond to SAP R/3 jobs are defined in OPC similarly to the way that you define normal operations. To make an operation that corresponds to a SAP R/3 job, you should observe the following rules: The operation number and jobname are your choice. The workstation name associated to the operation must be the name of a SAP R/3 workstation. You must edit the JOBLIB member for that jobname and insert SAP R/3 job-specific parameters (that is, the R/3 job name and job id, or the R/3 userid), as shown in the following example: (5/98) Scheduling SAP R/3 Jobs with Tivoli OPC 3-5

30 SAP R/3 Job Parameters The meaning of the above syntax is explained in the next chapter. When defining a SAP R/3 job to OPC, the SAP R/3 job must already exist in the R/3 job database or must be created before it is scheduled by OPC. SAP R/3 Job Parameters SAP-specific information for the job must be coded in the joblib member that is specified when defining an operation in the application database. SAP-specific information is defined in the following way: -job r3jobname -user r3username [-i r3jobid] [-vn varname [ ] ] [-c a b c ] [-nobdcwait] [-s step_number] [-trace] [-debug] [-flag IMMED] where: -job r3jobname Mandatory parameter, is the name of the job in R/3. Embedded spaces in the name are not allowed, but a name with spaces must be imbedded in single quotes. -user r3username Mandatory parameter, is the name of the R/3 job creator. Embedded spaces are not allowed in the name. -i r3jobid Optional parameter, is the R/3 job id. If used, it must identify a job with the same name and user as specified with -job and -user or the OPC jobname and username, whichever are applicable. -v[n] vname Optional parameter, describes the variants to be passed to the R/3 job. Where n is the variant step number (default is 1) and vname is the variant name. Embedded spaces in the name are allowed, but names with spaces must be enclosed in single quotes. Multiple variants can be included, if separated by spaces. -c Optional parameter, is the class under which the job will run in R/3. It can be one of: a, b, or c. This overrides the class specified in the R/3 job definition, which is the default. This definition is valid only for SAP releases prior to 3.1.G. 3-6 Scheduling SAP R/3 Jobs with Tivoli OPC (5/98)

31 BDC Wait Consideration -nobdcwait Optional parameter, when this option is selected, r3batch will not wait for the completion of BDC sessions that were started by the R/3 job. -s step_number Optional parameter, specifies the SAP R/3 step from which the SAP R/3 job will be run. -debug -trace Optional parameters, to activate the r3batch trace. It will create the dev_rfc file in the OPC Tracker Agent home directory. -flag immed Optional parameter, if specified, the job will be submitted immediately by the SAP R/3 system, otherwise it will be submitted as soon as possible. Example : -job myjob -user usr1 -i v1 default -c b -nobdcwait BDC Wait Consideration With the BDC wait option, you can specify that an R/3 job launched by OPC will not be considered complete until all of its BDC (Batch Data Collector) sessions have completed. This prevents other OPC jobs that are dependent on the R/3 job from being launched until its BDC sessions 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(zm) with name message i001(zm) 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. (5/98) Scheduling SAP R/3 Jobs with Tivoli OPC 3-7

32 BDC Session Names BDC Session Names If BDC sessions are specified by name, multiple BDC sessions can be created with the same name. In this case, all of the BDC sessions with matching names must complete, provided they were created during the execution of the OPC-launched R/3 job. Sessions with matching names created before the job starts or after it finishes are ignored. For example, if an OPC-launched R/3 job starts three BDC sessions with the name ORD2, and issues one BDCWAIT message: "BDCWAIT:ORD2". All three ORD2 sessions must complete before the R/3 jobís status is shown as COMPLETED in OPC. 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. The completion status of an OPC-launched R/3 job, whether Completed or Error, is based entirely on the batch job s execution status. 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. Scheduling SAP R/3 Jobs in OPC R/3 jobs are scheduled in the same manner as any other OPC operations and can include dependencies and other OPC-specific controls. 3-8 Scheduling SAP R/3 Jobs with Tivoli OPC (5/98)

33 OPC and R/3 Job Status OPC and R/3 Job Status When a SAP R/3 job is launched by OPC, you can monitor its progress from the ISPF panels of the OPC current plan. The status transitions in OPC and the corresponding R/3 status are listed below. OPC Job Status STARTED STARTED COMPLETED ENDED IN ERROR R/3 Job Status Ready Active Finished Cancelled or finished in error Although a job may be finished in R/3, OPC will keep it in the STARTED status if its BDC sessions are not complete, and you have not selected the -nobdcwait option in the job definition. (5/98) Scheduling SAP R/3 Jobs with Tivoli OPC 3-9

34 4 R/3 Options File This section provides detailed reference information about the R/3 options file r3options, and the programs used to create and maintain it. The R/3 Options File The options file resides on the OPC Tracker Agent host in the METHODS subdirectory of the OPC Tracker Agent home directory ($EQQHOME). It contains an entry for each instance of R/3. The fields in an entry are separated by one or more spaces. The file can be created and maintained with any text editor, or you can use r3setup (UNIX) or R3OPT.EXE (Windows NT). Entry Syntax where: xagent r3host [r3gate] r3sys r3inst r3cli r3user r3pass [min] [max] auditlevel xagent r3host r3gate r3sys r3inst r3cli The OPC workstation name corresponding to the OPC Tracker Agent where the SAP R/3 X-Agent runs. The host name of the R/3 database server. The host name of the R/3 gateway system. The R/3 system identifier. The R/3 instance number on r3host. The R/3 client number for starting jobs. (5/98) R/3 Options File 4-1

35 Example r3user The R/3 user name that OPC will use to start R/3 jobs and to connect to the R/3 server systems. This user must have batch administration privileges as described in Appendix A. When R/3 jobs are run by OPC, the job log output in R/3 is found under this user name. r3pass The password for r3user. It is recommended that the R/3 user be given a password that does not expire. min max auditlevel Example The minimum interval in seconds for R/3 job status updates. The interval is lengthened as long as a job continues to run until the max interval is reached. The default is 30. The maximum interval in seconds for R/3 job status updates. The default is 300. The audit level is used to specify which messages are logged to R/3. Valid values are 0 to 5. The higher the value, the more information is logged to R/3. sap1 sys01 SAP r3jobber 4R$m/FA18/37+R The r3setup Script on UNIX Host To create and manage the r3options file on an OPC Tracker Agent for UNIX, use the r3setup script. To start the r3setup script, execute the following command: r3setup -new -maintain -update where: -new -maintain Decompress and install OPC R/3 software files, and prompt for values to be entered in the r3options file. If the X-Agent name you enter is the same as an existing entry, that entry is replaced. Prompt for values to be entered in the r3options file. If the X-Agent name you enter is new, a new entry is made in the file. If the X-Agent name you enter is the same as 4-2 R/3 Options File (5/98)

36 Encrypting R/3 User Passwords on UNIX Host -update an existing entry, that entry is replaced. This option is used to add new R/3 X-Agents to an existing installation, or to update a previous entry. Decompress and install OPC R/3 software files. Encrypting R/3 User Passwords on 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 text editor, you must run the enigma program to encrypt the password before writing it in the file. Run enigma 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. The Options Editor on a Windows NT X-Agent To manage the r3options file on a Tivoli OPC Tracker Agent for NT, run the options editor r3opt.exe. This program is also run as part of the setup.exe program when you first install the SAP R/3 X-Agent software. (5/98) R/3 Options File 4-3

37 Options Editor Options Editor The Options Editor lets you add, modify and delete entries for one or more SAP R/3 X-Agents. The options are saved in the r3options file. As you work with entries, note that the title bar always identifies the current entry. The option fields are: Host CPU Name The name of the OPC workstation associated with that SAP R/3 X-Agent. Audit Level The Audit level used to log X-Agent activities on R/3. A higher level means more messages are logged. Valid values are 0 to 5. For R/3 versions below 3.1G, enter a value of 0. R3 Host Field The host name of the R/3 database server. R3 Gateway Host Field The host name of the R/3 gateway system, if any. R3 System Name Field The R/3 system identifier. 4-4 R/3 Options File (5/98)

38 Displaying Records in the Options File Instance Field The R/3 instance number on the R3 host. Client Number Field The R/3 client number for starting jobs. Userid Field The R/3 user name that SAP R/3 X-Agent will use to start R/3 jobs and to connect to the R/3 servers. This user must have batch administration privileges. Password Field The password for Userid. It is recommended that the R/3 user be given a password that does not expire. Re-enter Password Field Re-enter the password defined above for verification purposes. Short Interval Field The minimum interval in seconds for R/3 job status updates. The interval is lengthened as long as a job continues to run until the Long Interval is reached. The default is 30. Long Interval Field The maximum interval in seconds for R/3 job status updates. The default is 300. Displaying Records in the Options File To display records, click the Previous Entry or Next Entry buttons. Deleting Records in the Options File To delete a record, display it and click the Delete Entry button. Adding Records to the Options File To add a new record: 1. Click the Next Entry button until a blank record appears. 2. Fill in the options. 3. To save the record and exit, click the Done button. To save the record and create another record, click the Next Entry button. (5/98) R/3 Options File 4-5

39 Modifying an Entry in the Options File Modifying an Entry in the Options File To modify a record: 1. Display the record. 2. Change any options. 3. To save the record and exit, click the Done button. To save the record and move to another record, click the Next Entry or Previous Entry button. 4-6 R/3 Options File (5/98)

40 Index Symbols /usr/lib/maestro 2-1 A agent fault-tolerant 1-1 standard 1-1 B BDC wait 3-8, 3-9 C client number 4-1 cpu definition 3-3 D database server 4-1 E encryption 4-3 enigma program 4-3 G gateway system 4-1 H home directory 2-1 I IFuser 2-8 installation 2-1 instance number 4-1 J job definition 3-5 job status update interval 4-2 JobDef 2-8 jobs defining in Maestro 3-5 job states 3-9 scheduling 3-9 L LJuser 2-8 M master 1-1 maximum interval 4-2 minimum interval 4-2 O options files r3batch.opts 2-8 P password 4-2, 4-3 (5/98) Index-1

41 R r3batch.opts file 2-8 r3setup script 2-2, 4-2 S scheduling jobs 3-9 states of job 3-9 system identifier 4-1 U user name 4-2 X x-agent cpu definition 3-3 overview 3-1 Index-2 (5/98)