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

Tivoli OPC Extended Agent for SAP R/3 - IBMpublib.boulder.ibm.com/tividd/td/opc/SAP_OPC/en_US/PDF/SAP_OP… · Tivoli OPC Extended Agent for SAP R/3 Version 3.0. Tivoli OPC Extended

Embed Size (px)

Citation preview

Tivoli OPCExtended Agentfor SAP R/3

Version 3.0

Tivoli OPC Extended Agent for SAP R/3 (June 1998)Part number: GC32-0280-00Copyright NoticeCopyright © 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.

TrademarksThe 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.

NoticeReferences 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

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

PrefaceThe 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 GuideThe 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 ContainsThe 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

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 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 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 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

Menu Commands 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

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 SupportIf you encounter difficulties with any Tivoli products, you can enter http://www.support.tivoli.com 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-848-6548 (1-800-TIVOLI8) and the IBM number is 1-800-237-5511 (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 e-mail to [email protected].

Tivoli OPC SAP R/3 Extended Agent Supplement vii

viii Version 3.0

Contents

1. Introduction ................................................................ 1-1Features ...................................................................................1-2SAP R/3 Extended Agent Process.......................................1-2Customer Support..................................................................1-2

2. Installation ................................................................. 2-1Compatibility..........................................................................2-1Installing with an OPC Tracker Agent for UNIX..............2-1Installing with an OPC Tracker Agent for Win NT ..........2-2

The Setup Program ........................................................2-3Choose Destination Location .......................................2-3Copying Files ..................................................................2-4Options Editor ................................................................2-4Folder Selection ..............................................................2-7

Installing the X-agent on the SAP R/3 System..................2-7Configure the X-agent on Tracker Agent System .............2-8

3. Scheduling SAP R/3 Jobs with Tivoli OPC ............................. 3-1Defining Jobs in SAP R/3 .....................................................3-2Defining SAP R/3 Workstations in OPC............................3-3

4. R/3 Options File ............................................................ 4-1The R/3 Options File .............................................................4-1Entry Syntax............................................................................4-1

Example ...........................................................................4-2The r3setup Script on UNIX Host........................................4-2Encrypting R/3 User Passwords on UNIX Host...............4-3The Options Editor on a Windows NT X-Agent ...............4-3

Options Editor ................................................................4-4Displaying Records in the Options File ......................4-5Deleting Records in the Options File ..........................4-5Adding Records to the Options File ............................4-5Modifying an Entry in the Options File .....................4-6

(5/98) Contents ix

x Contents (5/98)

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

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 ProcessThe 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 SupportIf you have any questions about the product, please call the Tivoli Customer Support Call Center:

1 - 800 - TIVOLI - 8 (1-800-848-6548) or

1 - 800-235-5511

1-2 Introduction (5/98)

Customer Support

You can also contact Tivoli at the following addresses:

Company home page:

http://www.tivoli.com

Support home page:

http://www.support.tivoli.com

E-mail address for technical support:

[email protected]

E-mail address for documentation comments:

[email protected]

(5/98) Introduction 1-3

Customer Support

1-4 Introduction (5/98)

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.

CompatibilityTo 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 2.2.0 or later and Tivoli OPC Controller Version 2.2.0 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 UNIXFollow 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

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 NT1. 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)

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

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 FilesProgram 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 EditorA 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)

Options Editor

The option fields are:

Host CPU Name 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.

Audit Level 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

Options Editor

R3 Host The host name of the R/3 database server.

R3 Gateway Host The host name of the R/3 gateway system, if any.

R3 System Name The R/3 system identifier.

Instance The R/3 instance number on the R3 host.

Client Number The R/3 client number for starting jobs.

Userid 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.

Password The password for Userid. It is recommended that the R/3 user be given a password that does not expire.

Re-enter Password Re-enter the password defined above for verification purposes.

Short Interval 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 4-3.

2-6 Installation (5/98)

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 SystemYou 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

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 SystemBefore 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 3-8.

2-8 Installation (5/98)

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_definitionshould 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

Configure the X-agent on Tracker Agent System

2-10 Installation (5/98)

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

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/3To 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/3.

3-2 Scheduling SAP R/3 Jobs with Tivoli OPC (5/98)

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 OPCOPC 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

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)

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 JobsOPC 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

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 ParametersSAP-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)

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 11239288 -v1 default -c b -nobdcwait

BDC Wait ConsiderationWith 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

BDC Session Names

BDC Session NamesIf 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 OPCR/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)

OPC and R/3 Job Status

OPC and R/3 Job StatusWhen 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.

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.

OPC Job Status R/3 Job Status

STARTED Ready

STARTED Active

COMPLETED Finished

ENDED IN ERROR Cancelled or finished in error

(5/98) Scheduling SAP R/3 Jobs with Tivoli OPC 3-9

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 FileThe 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 Syntaxxagent r3host [r3gate] r3sys r3inst r3cli r3user r3pass [min] [max] auditlevel

where:

xagent The OPC workstation name corresponding to the OPC Tracker Agent where the SAP R/3 X-Agent runs.

r3host The host name of the R/3 database server.

r3gate The host name of the R/3 gateway system.

r3sys The R/3 system identifier.

r3inst The R/3 instance number on r3host.

r3cli The R/3 client number for starting jobs.

(5/98) R/3 Options File 4-1

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 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.

max The maximum interval in seconds for R/3 job status updates. The default is 300.

auditlevel 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.

Examplesap1 sys01 SAP 00 100 r3jobber 4R$m/FA18/37+R 240 360 2

The r3setup Script on UNIX HostTo 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 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.

-maintain 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)

Encrypting R/3 User Passwords on UNIX Host

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.

-update Decompress and install OPC R/3 software files.

Encrypting R/3 User Passwords on UNIX HostWhen 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-AgentTo 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

Options Editor

Options EditorThe 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 FieldThe host name of the R/3 gateway system, if any.

R3 System Name FieldThe R/3 system identifier.

4-4 R/3 Options File (5/98)

Displaying Records in the Options File

Instance Field The R/3 instance number on the R3 host.

Client Number FieldThe 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 FieldRe-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 FileTo display records, click the Previous Entry or Next Entry buttons.

Deleting Records in the Options FileTo delete a record, display it and click the Delete Entry button.

Adding Records to the Options FileTo 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

Modifying an Entry in the Options File

Modifying an Entry in the Options FileTo 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)

Index

Symbols

/usr/lib/maestro 2-1

A

agentfault-tolerant 1-1standard 1-1

B

BDC wait 3-8, 3-9

C

client number 4-1cpu definition 3-3

D

database server 4-1

E

encryption 4-3enigma program 4-3

G

gateway system 4-1

H

home directory 2-1

(5/98)

I

IFuser 2-8installation 2-1instance number 4-1

J

job definition 3-5job status update interval 4-2JobDef 2-8jobs

defining in Maestro 3-5job states 3-9scheduling 3-9

L

LJuser 2-8

M

master 1-1maximum interval 4-2minimum interval 4-2

O

options filesr3batch.opts 2-8

P

password 4-2, 4-3

Index-1

R

r3batch.opts file 2-8r3setup script 2-2, 4-2

S

scheduling jobs 3-9states of job 3-9system identifier 4-1

U

user name 4-2

X

x-agentcpu definition 3-3overview 3-1

Index-2 (5/98)