Tivoli Maestro Oracle Applications Extended Agent Guide. Version 1.3 MO

Transcription

1 Tivoli Maestro Oracle Applications Extended Agent Guide Version 1.3 MO

2

3 Tivoli Maestro Oracle Applications Extended Agent Guide (April 1998) 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. Pentium, MMX, LANDesk, and ActionMedia are trademarks or registered trademarks of Intel Corporation in the United States and other countries. 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 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 Who Should Read This Guide The target audience for this guide is system managers who will install and configure the Tivoli Maestro Oracle Applications Extended Agent, and system administrators who perform daily administration tasks. Users of the guide should have some knowledge of: The UNIX operating system The Tivoli Maestro and Oracle Applications operating environment Prerequisite and Related Documents The following document contains information related to the Tivoli Maestro Oracle Applications Extended Agent: Tivoli Maestro User Guide Provides information about setting up and managing the Tivoli Maestro environment. It also provides general information about extended agents. What This Guide Contains The sections are: Section 1 Introduction provides an introduction to the product and installation instructions. Section 2 Setting Up and Operation describes how to configure the extended agent cpu, and how to document and schedule Oracle Applications jobs. Section 3 Options File Reference describes the extended agent options, and the format of the 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 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. Tivoli Maestro Oracle Applications X-Agent Guide v

6 Special Characters Menu Commands Hierarchical Displays 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. 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. vi

7 Contents 1. Introduction Features Software Requirements Support for Oracle Applications Version 10.6 and Installation CD-ROM Installation Tape Installation Interface Software Customer Support Set Up and Operation Defining an Oracle Applications Extended Agent Cpu Command Line Example Defining Jobs in Oracle Applications Defining Oracle Applications Jobs in Maestro Command Line Example Scheduling Oracle Applications Jobs Command Line Example Maestro and Oracle Applications Job States Options File Reference The mcmoptions File Entry Syntax Example Encrypting Oracle Applications User Passwords (4/98) Contents vii

8 viii Contents (4/98)

9 1 Introduction The Oracle Applications extended agent (x-agent) gives you the ability to schedule Oracle Applications jobs using the sophisticated job scheduling features of Maestro. Oracle Apps Maestro Host X-Agent Maestro Win NT Maestro Unix Maestro MVS X-Agent Maestro HP MPE Note: The Maestro Host, the Maestro Oracle Application X-agent, and the Oracle Applications Instance must be installed on the same physical node. Features Use Maestro s standard job dependencies (except Open File dependancies). Schedule Oracle Applications jobs to run on specified days, times, and in a prescribed order. Define inter-dependencies between Oracle Applications jobs and jobs that run on different systems such as SAP R/3 and Baan IV. Define inter-dependencies between Oracle Applications jobs and jobs that run on different platforms, including Windows NT, MVS, HP MPE, and UNIX. (4/98) Introduction 1-1

10 Software Requirements Software Requirements To install and use the Oracle Applications x-agent you must have the following software installed: Maestro version 5.0 Oracle RDBMS x or higher. Oracle Applications version 10.5 or 10.6 ANSI C compiler One of the following supported operating systems: HP-UX version 9.x or 10.x Sun Solaris version 2.3 or higher IBM AIX or higher. Support for Oracle Applications Version 10.6 and 10.7 The Oracle Extended Agent version 1.3 is certified for Oracle Applications versions 10.6 and Installation CD-ROM Installation To install the Oracle Applications x-agent software on the Maestro UNIX host computer, perform the following steps: 1. Log in as an Oracle Applications UNIX user, who has access to all the files under the Oracle Application Top directory. 2. Create a temporary directory and change to the temporary directory: mkdir temp cd temp 3. Copy the integration software from the CD-ROM into the temporary directory: tar -xvf cd_device/maestro/platform/ora_ver/oracle.tar where: cd_device The pathname of your CD drive. platform The target platform from the list below. AIX IBM HPUX Hewlett-Packard SOLARIS Sun Solaris ora_ver Either ORA106 for Oracle Applications 10.6 or ORA107 for Oracle Applications Introduction (4/98)

11 Tape Installation Note: If you are running the Oracle Applications demo database, substitute the APPDEMO.env file in steps 4 and Modify the Oracle Applications APPLSYS.env file as follows: a. Append MCM to the APPLSHAR and APPLFULL variables. APPLSHAR= ALR FF MCM APPLFUL= FND AD AX AK GL RG INV OP MCM b. Define and export the shell variable MCM_TOP: MCM_TOP=$APPL_TOP/mcm/integration export MCM_TOP c. Add the $MCM_TOP/bin to the PATH variable by entering the following lines at the bottom of the APPLSYS.env file: PATH=$PATH:$MCM_TOP/bin export PATH 5. Run the APPLSYS.env file to set the environment:. APPLSYS.env Note: Make sure that the Oracle Applications login has permissions to write into the maestrohome and methods directories. 6. Run the installation script mcminstall from the temp directory. An Oracle Tivoli screen is displayed. 7. Enter I and press return. The installation scripts are started and the integration files are installed to the maestrohome/methods directory. If the installation script returns a 0 the install was successful. A return code of 1 indicates that the install failed. 8. Delete the temporary directory: cd.. rm temp The installation is complete. Tape Installation To install the Oracle Applications x-agent software on the Maestro UNIX host computer, perform the following steps: 1. Log in as an Oracle Applications UNIX user, who has access to all the files under the Oracle Application Top directory. 2. Create a temporary directory and change to the temporary directory: (4/98) Introduction 1-3

12 Tape Installation mkdir temp cd temp 3. Copy the integration software from the tape into the temporary directory: tar -xv[f device] MAESTRO/platform/ora_ver/ORACLE.TAR where: device The pathname of your Tape drive. platform The target platform from the list below. AIX IBM HPUX Hewlett-Packard SOLARIS Sun Solaris ora_ver Either ORA106 for Oracle Applications 10.6 or ORA107 for Oracle Applications Untar the product files: tar -xvf MAESTRO/platform/ora_ver/ORACLE.TAR Note: If you are running the Oracle Applications demo database, substitute the APPDEMO.env file in steps 4 and Modify the Oracle Applications APPLSYS.env file as follows: a. Append MCM to the APPLSHAR and APPLFULL variables. APPLSHAR= ALR FF MCM APPLFUL= FND AD AX AK GL RG INV OP MCM b. Define and export the shell variable MCM_TOP: MCM_TOP=$APPL_TOP/mcm/integration export MCM_TOP c. Add the $MCM_TOP/bin to the PATH variable by entering the following lines at the bottom of the APPLSYS.env file: PATH=$PATH:$MCM_TOP/bin export PATH 6. Run the APPLSYS.env file to set the environment:. APPLSYS.env Note: Make sure that the Oracle Applications login has permissions to write into the maestrohome and methods directories. 7. Run the installation script mcminstall from the temp directory. An Oracle Tivoli screen is displayed. 1-4 Introduction (4/98)

13 Interface Software 8. Enter I and press return. The installation scripts are started and the integration files are installed to the maestrohome/methods directory. If the installation script returns a 0 the install was successful. A return code of 1 indicates that the install failed. 9. Delete the temporary directory: cd.. rm temp The installation is complete. Interface Software The interface between Tivoli Maestro and Oracle Applications is comprised of the following software: MCMAGENT is the Oracle Applications x-agent access method. MCMLJ submits a job to Oracle Concurrent Manager (OCM). MCMSTAT monitors the status of the job submitted. MCMTJ terminates the job submitted, on receiving a kill signal from Maestro. mcm.mk mcmoptions is a makefile utility for linking the above programs with Oracle Applications. is a sample options file which contains details about the environment to be set before starting the Oracle Applications x-agent. This file must strictly follow the format specified. Refer to section 3, Options File Reference for information on creating the mcmoptions file. Maestro Host MCMAGENT MCMLJ MCMSTAT Oracle Concurrent Manager MCMTJ Maestro Oracle (4/98) Introduction 1-5

14 Customer Support Customer Support If you have any questions about the product, please call the Tivoli Customer Support Call Center: TIVOLI8 ( ) or You can also contact Tivoli at the following addresses: Company home page: Support home page: address for technical support: address for documentation comments: 1-6 Introduction (4/98)

15 2 Set Up and Operation Maestro can launch and monitor jobs on an instance of Oracle Applications using an Oracle Applications x-agent cpu. The Oracle Applications x-agent is defined in a standard Maestro cpu definition, which gives the x-agent a name and identifies the access method as MCMAGENT. Each instance of Oracle Applications is defined as a separate x-agent cpu, and each must have a separate entry in the mcmoptions file. The cpu definition for the Oracle Application x-agent is a logical definition for an instance of Oracle Applications. Oracle Applications and the Maestro Host run on the same physical cpu. Maecpu1 Maestro Host Oracpu1 X-agent cpu definition MCMAGENT access method mcmoptions Oracpu2 X-agent cpu definition MCMAGENT access method job1 Oracle Applications instance 01 job2 Oracle Applications instance 02 To launch an Oracle Applications job, Maestro executes the x-agent s access method, MCMAGENT, passing it the x-agent s cpu name and information about the job. Using the x- agent s cpu name as a key, MCMAGENT looks up the corresponding entry in the mcmoptions file to determine which instance of Oracle Applications it will connect to (refer to section 3, Options File Reference for more information on the mcmoptions file). The Oracle Applications x-agent can then launch jobs on that instance of Oracle Applications and monitor the jobs through completion, writing job progress and status information to the job s standard list file. (4/98) Set Up and Operation 2-1

16 Defining an Oracle Applications Extended Agent Cpu Note: Before an Oracle Applications job can be launched by Maestro it must be defined in Oracle Applications and in Maestro. Defining an Oracle Applications Extended Agent Cpu Oracle Applications x-agent cpu definitions are required for each instance of Oracle Applications that will execute Maestro-scheduled jobs. They are defined in the standard manner and include the name of the x-agent s host and the access method name. The following figure shows a Composer CPU Definition window for an Oracle Applications x- agent named ORA002. For information about using Composer to define a cpu, refer to the Tivoli Maestro User Guide. The fields are: CPU Name Node TCP Address Operating System Description Maestro Options The Maestro name of the Oracle Applications x-agent. It can contain up to eight alphanumeric characters starting with a letter. Not used. Enter at least one letter. Not used. Enter at least one number. Select OTHER. A description of the cpu. It can contain up to 40 alphanumeric characters. This field is optional. Not used. 2-2 Set Up and Operation (4/98)

17 Command Line Example Server Host CPU Access Not used. The Maestro name of the host system. This is the Maestro master, fault-tolerant agent, or standard agent that hosts the Oracle Applications x-agent cpu. Click the CPUs... button to select a cpu from a list. The name of the Oracle Applications access method, MCMAGENT. This is executed by the Maestro host to connect to an instance of Oracle Applications. Click the Methods... button to select MCMAGENT from a list. Command Line Example Cpu definitions can also be entered at the Composer command line. The cpu definition shown in the previous example would be entered as follows: cpuname ORA002 node null os other description "Oracle extended agent #002" for maestro host goliath access MCMAGENT end For information about using the Composer command line interface to create cpu definitions, refer to the Tivoli Maestro User Guide. Defining Jobs in Oracle Applications In Oracle Applications, jobs that are to be scheduled with Maestro are defined in the same manner as other Oracle Applications jobs (and can be submitted in OCM). When you are submitting the job in OCM, specify the scheduling and resubmission information. When you are submitting the job through Maestro, Maestro will take care of the scheduling and resubmission information. To define a job, use the Define Concurrent Program Executables and Define Concurrent Program forms and fill in the general data information for the job. The job is now available for scheduling from Maestro (and can also be submitted in OCM as well). Running a Single Job Concurrently If an Oracle Applications job is scheduled to run more than once in Maestro, and Maestro launches it concurrently, the jobs will run normally. However, if the Oracle Applications user has specified that the job cannot run concurrently, the second job will enter a state of WAIT until the first job completes. (4/98) Set Up and Operation 2-3

18 Defining Oracle Applications Jobs in Maestro Defining Oracle Applications Jobs in Maestro Maestro job definitions are required for each Oracle Applications job you intend to schedule. Oracle Applications jobs are defined in Maestro like other jobs and include job name, user name, and recovery options. The following figure shows a Job Definition window for a job named ORAJOB2 on the Oracle Applications x-agent cpu ORA002. For information about using Maestro to define jobs, refer to the Tivoli Maestro User Guide. The Fields are: CPU Job Name Logon Description The Maestro name of the Oracle Applications x-agent cpu. The Maestro name of the Oracle Applications job. It can contain up to eight alphanumeric characters, including dashes and underscores, but must start with a letter. Embedded spaces are not allowed. This name is used to schedule the job in Maestro. The name will appear in Maestro displays. This name can be the same as the Oracle Applications job name, unless it would be invalid in Maestro. The user name used to run the job in Maestro. This must be a valid user on the Maestro host cpu. It is required to schedule the job in Maestro, and it will appear in Maestro displays. A description of the job. It can contain up to 40 alphanumeric characters. This field is optional. 2-4 Set Up and Operation (4/98)

19 Defining Oracle Applications Jobs in Maestro Script File Enter the specifications for the Oracle Applications job file. These are the parameters: -user appslogin -job jobspecs -prn printopts [-vn { value null :parameter}] -user appslogin Enter a valid Oracle Applications user (Apps login). For example: -user GLOBAL -job jobspecs Enter the Oracle Applications job attributes. There are four job attributes to be specified. They must be entered in the following order: name of the Applications module used to sign on to Oracle Applications (for example, FND) a valid responsibility for the Applications module (for example, "Application Developer"). This parameter must be enclosed in quotes. name of the application which registered the job (for example, PO) job name (for example, POXACR). The job name must be uppercase. For example: -job FND Application Developer PO POXACR -prn printopts Enter the two printer options for the job. They must be entered in the following order: printer name (optional). If omitted the default printer specified in the mcmoptions file is used. number of copies Below are two examples: -prn ps4 2 -prn 0 [-vn { value null :parameter}] Enter the job s parameters, if any. If no parameters are specified in Oracle Applications for the job, this string is optional. n is the parameter number (v1, v2, etc.) the Oracle x-agent software will automatically add all parameters that you do not specify in the definition with a value of null. enter an actual value (enclose value in single quotes if it contains special characters) enter the name of a Maestro :parameter. The parameter must be defined beforehand. See the Tivoli Maestro User Guide for more information about Maestro parameters. (4/98) Set Up and Operation 2-5

20 Command Line Example Below are two examples: -v4 abc -v15 :p1 Below is an example of an entire Script File field specification: -user GLOBAL -job FND Application Developer PO POXACR -prn ps4 2 -v1 abc Command Not used. For information on recovery options refer to the Tivoli Maestro User Guide. Command Line Example Jobs can also be defined at the composer command line. The following example documents a Maestro job named ORAJOB2 that runs on an Oracle Applications x-agent cpu named ORA002. It logs on to UNIX as ORAJOBS and launches a job under Oracle Applications. The Oracle Applications job is named POXACR and its owner is GLOBAL. If recovery is needed, Maestro will run job RECOV2 and then continue processing. ORA002#ORAJOB2 streamlogon orajobs scriptname "-user GLOBAL -job FND Application Developer PO POXACR -prn ps4 2 -v1 abc " description "Oracle Apps job #2" recovery continue after recov2 Scheduling Oracle Applications Jobs Oracle Applications jobs are scheduled in the same manner as other Maestro jobs and can include dependencies and other controls. The following figure shows a Composer Schedule Definition window for a schedule named MYSKED on the cpu ORA002, which includes the job MAINCPU#MYJOB and the Oracle Applications x-agent jobs ORAJOB1 and ORAJOB Set Up and Operation (4/98)

21 Scheduling Oracle Applications Jobs Note: Note: ORAJOB1 and ORAJOB2 are the Maestro names for the jobs, the Oracle Applications names for the jobs may be different. Opens Files dependencies are not supported for the Oracle x-agent. For information about using Composer to create schedules, refer to the Tivoli Maestro User Guide. (4/98) Set Up and Operation 2-7

22 Command Line Example Command Line Example Schedules can also be entered at the Composer command line. The following example shows a schedule called MYSKED on the Oracle Applications x-agent ORA002. schedule ora002#mysked on monthend at 1600 : maincpu#myjob ora002#orajob1 follows maincpu#myjob ora002#orajob2 follows ora002#orajob1 end For information about using the Composer command line to create schedules, refer to the Tivoli Maestro User Guide. Maestro and Oracle Applications Job States When an Oracle Applications job is launched by Maestro, you can monitor its progress with Maestro s console manager, Conman. The state transitions in Maestro and the corresponding Oracle Applications states are listed below. Oracle Concurrent Manager States Request Failure or Request not Found Inactive Pending Pending Normal Running Normal Completed Normal Completed Warning Completed Error Completed Terminated Completed Canceled Maestro States UT (unsupported task) SUSP WAIT ADD EXEC SUCC SUCC ABEND ABEND ABEND For more information about job management, refer to the Tivoli Maestro User Guide. 2-8 Set Up and Operation (4/98)

23 3 Options File Reference This section provides detailed reference information about the Oracle Applications x- agent options file, mcmoptions. The mcmoptions File The options file contains an entry for each instance of Oracle Applications that Maestro will run jobs on. The entries must be separated by one or more spaces. This file must exist in the directory maestrohome/methods. The mcmoptions file entries must be in the following format. All of the entries are required. Entry Syntax xagent oraclehome oracle_sid oraapptopdir fndtopdir path env userid password printername mintime maxtime where: xagent oraclehome oracle_sid oraapptopdir fndtopdir path env The Maestro cpu name of the extended agent for this instance of Oracle Applications. The UNIX directory where Oracle software is installed. The Oracle system identifier of the database instance you are connecting to. This corresponds to the value of the Oracle Applications $ORACLE_SID variable. The UNIX directory where Oracle Applications is installed. The FND top directory where the Application Object Library resides. The setting of the PATH variable, including, the existing path, the path to the bin directory of Oracle Applications, the path to the include directory under the FND Top directory, and others as needed. The environment file to execute. Each instance of Oracle Applications has its own environment file (APPLSYS.env or APPDEMO.env). The.env filename given here will be used to set the environment dynamically when Maestro runs jobs on the Oracle Applications x- agent. (4/98) Options File Reference 3-1

24 Example userid password printername mintime maxtime A database user id that has access to all the Modules in Oracle Applications. It must be able to launch, manage and terminate jobs in Oracle Applications. The password for the selected userid. The default printer id. The number of seconds to be added to the previous polling interval after which the job status check has to be carried out, expressed in seconds. When the polling interval reaches this limit, it will not incremented, thereby the polling interval remains constant, expressed in seconds. Example HP9000 /general/ora716 DEMO106 /apps106 $APPL_TOP/fnd/* $PATH:$ORACLE_HOME/bin:$FND_TOP/include $APPL_TOP/APPDEMO106.env APPS_US APPS_US PRINTER Encrypting Oracle Applications User Passwords When you make entries in the mcmoptions file, the password value is automatically encrypted before it is written to the file. If you modify the file with a text editor, you must run the enigma program to encrypt the password before writing it to the file. Run the enigma program as follows: enigma [password] You can include the password on the command line or enter it in the response to a prompt. The program returns an encrypted version that you can then enter in the mcmoptions file. 3-2 Options File Reference (4/98)

25 Index A agent fault-tolerant 1-1 standard 1-1 D defining jobs in Oracle Applications 2-3 defining Oracle Applications jobs command line example 2-6 in Maestro 2-4 defining the cpu 2-2 E encrypting user passwords 3-2 enigma 3-2 F features 1-1 I interface software 1-5 script file 2-5 Oracle Applications x-agent access method 2-3 cpu name 2-2 defining the cpu 2-2 defining the cpu, command line example 2-3 features 1-1 host cpu 2-3 setup and operation 2-1 P password encryption 3-2 S scheduling Oracle Applications jobs 2-6 setup and operation 2-1 software components 1-5 requirements 1-2 syntax, mcmoptions file 3-1 J job states Maestro and Oracle Applications 2-8 M MCMAGENT 1-5, 2-1, 2-3 mcmoptions overview 1-5 mcmoptions file entry syntax 3-1 example 3-2 overview 2-1, 3-1 O Oracle Applications jobs defining 2-3 scheduling 2-6 scheduling, command line example 2-8 (4/98) Index-1

26 Index-2 (4/98)