CM Agent Administrator Guide

CONTROL-M/Agent for Unix Administrator Guide
Version 6.0.01
September 16, 2001
BMC Software, Inc., Confidential and Proprietary Information
ii
CONTROL-M/Agent for Unix
Copyright 2001 BMC Software, Inc. All rights reserved. BMC Software, the BMC Software logos, and all other BMC Software product or service names are registered trademarks or trademarks of BMC Software, Inc. All other registered trademarks or trademarks belong to their respective companies. MM-6003G-A0109A-UNIXAgent
Restricted Rights Legend

U.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHEDRIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in FAR Section 52.227-14 Alt. III (g)(3), FAR Section 52.227-19, DFARS 252.227-7014 (b), or DFARS 227.7202, as amended from time to time. Send any contract notices to Contractor/Manufacturer: BMC Software, Inc. 2101 CityWest Blvd. Houston TX 77042-2827 USA
Contacting BMC Software

You can access the BMC Software Web site at http://www.bmc.com. From this Web site, you can obtain general information about the company, its products, special events, and career opportunities. For a complete list of all BMC Software offices and locations, go to http://www.bmc.com/corporate/offices.html.
USA and Canada

Address BMC Software, Inc. 2101 CityWest Blvd. Houston TX 77042-2827 713 918 8800 or 800 841 2031 713 918 8000
Outside USA and Canada

Telephone Fax (01) 713 918 8800 (01) 713 918 8000
Telephone Fax
Customer Support
You can obtain technical support by using Response Online (support from the Web) or Response On Demand. To expedite your inquiry, please see Before Contacting BMC Software, below.
Response Online
You can obtain technical support from BMC Software 24 hours a day, seven days a week by accessing the technical support Web site at http://www.bmc.com/support.html. From this site, you can read overviews about support services and programs that BMC Software offers find the most current information about BMC Software products search a database for problems similar to yours and possible solutions order or download product documentation report a problem or ask a question subscribe to receive e-mail notices when new product versions are released find worldwide BMC Software support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers
Response On Demand
In the USA and Canada, if you need technical support and do not have access to the Web, call 800 537 1813. Outside the USA and Canada, please contact your local support center or your local sales office for assistance.
Before Contacting BMC Software

Before you contact BMC Software, have the following information available so that a technical support analyst can begin working on your problem immediately: product information product name product version (release number) license number and password (trial or permanent)
operating-system and environment information machine type operating system type, version, and service pack or program temporary fix (PTF) system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or PTF
sequence of events leading to the problem commands and options that you used messages received (and the time and date that you received them) product error messages messages from the operating system, such as file system full messages from related software
iv
Contents
Contents
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Chapter 1 General Information
CONTROL-M/Agent Components . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Agent Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Special Utility Parameter Formats . . . . . . . . . . . . . . . . . . . . . . . 1-7
Chapter 2 Installation and Administration
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 Before Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Defining a CONTROL-M/Agent User . . . . . . . . . . . . . . . . . . . . 2-2 Creating an Entry in the Services Map for NIS . . . . . . . . . . . . . 2-2 LINUX SU Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Silent Installation of CONTROL-M/Agent . . . . . . . . . . . . . . . . 2-16 Uninstalling CONTROL-M/Agent . . . . . . . . . . . . . . . . . . . . . . . 2-20 Changes to System Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21 CONTROL-M/Agent Configuration Parameters . . . . . . . . . . . . 2-22 Starting/Stopping CONTROL-M/Agent . . . . . . . . . . . . . . . . . . . . . . 2-23 Maintaining CONTROL-M/Agent . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23 View or Modify Configuration Parameters . . . . . . . . . . . . . . . . . 2-24 Modify Mirror CONTROL-M/Server Host Names . . . . . . . . . . 2-26
Contents
View CONTROL-M/Agent Messages . . . . . . . . . . . . . . . . . . . .2-27 View CONTROL-M/Agent Logs . . . . . . . . . . . . . . . . . . . . . . . .2-28 Writing Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28 Specifying the Shell Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28 Support for REXX-Language Scripts . . . . . . . . . . . . . . . . . . . . .2-30 Run-Time Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30 Scripts and the On Statement/Code Parameter . . . . . . . . . . . . . .2-32 Utilization of Exit Codes by CONTROL-M . . . . . . . . . . . . . . . .2-33 Use of Reserved Variable $0 . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34
Appendix A Creating a Unix User for CONTROL-M/Agent
AIX Agent Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 HP-UX Agent Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4 Data General, NCR, NonStop-UX, Pyramid, Reliant UNIX, SINIX and Solaris Agent Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . A-6 Digital UNIX, Sequent and SunOS Agent Platforms . . . . . . . . A-7
vi
Figures
Figures
Figure 1-1 Figure 1-2 CONTROL-M Scheduling Solution . . . . . . . . . . . . . . . . . . . . . . 1-2 CONTROL-M/Server Utility Workflow . . . . . . . . . . . . . . . . . . . 1-5
Figures
vii
viii
Tables
Tables
Table 1-1 Table 1-2 Table 2-1 Table 2-2 Table 2-3 Table 2-4 Table 2-5 Table 2-6 Table 2-7 Table 2-8 Agent Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . CONTROL-M/Agent Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . Agent for Unix Software Requirements . . . . . . . . . . . . . . . . . . Custom Installation Parameters for the Unix Agent . . . . . . . . . Configuration CONTROL-M/Agent for Unix . . . . . . . . . . . . Service Definition CONTROL-M/Agent for Unix. . . . . . . . . Unix Agent Configuration Parameters . . . . . . . . . . . . . . . . . . Options of the CONTROL-M Agent Main Menu . . . . . . . . . . . Options of the Server Host Names Menu . . . . . . . . . . . . . . . . . Shell Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 1-5 2-1 2-13 2-21 2-21 2-22 2-24 2-27 2-29
Tables
ix
About . . .
About This Book

This book is a guide to installing, customizing, and maintaining CONTROL-M/Agent for Unix. This book describes CONTROL-M/Agent administration, and provides information about parameters and utilities that is useful for the administrator. This book contains:
Chapter 1 General Information Introduces key features and concepts of CONTROL-M/Agent. Describes parameters that must be customized. CONTROL-M/Agent for Unix Lists requirements for installation of CONTROL-M/Agent under various types of Unix systems. Describes the installation procedure and how to modify configuration parameters. Creating a Unix User for CONTROL-M/Agent Describes how to define the CONTROL-M/Agent for USS user account.
Chapter 2
Appendix A
Index
About This Book
xi
Related Publications
CONTROL-M/Server Administrator Guides describe setup, security, and utilities for CONTROL-M/Server on a specific platform (for example, Unix, OpenVMS, AS/400, or Microsoft Windows). CONTROL-M/Server Installation Guides describe how to install CONTROL-M/Server on a specific platform. CONTROL-M Quick Installation Guide describes a default Unix-based installation of CONTROL-M Business Integrated Scheduling solution. It is intended primarily for trial and proof-of-concept implementations. CONTROL-M Server/Agent Migration Guide describes the process of migrating to CONTROL-M Server/Agent Technology from CONTROL-M 2.1.x. Enterprise Controlstation User Guide describes all ENTERPRISE/CS concepts, features, facilities, and operating instructions. Enterprise Controlstation Administrator Guide describes administrator responsibilities, installation, customization, maintenance, and security of ENTERPRISE/CS. CONTROL-M/Desktop User Guide describes the components used to define and manage CONTROL-M/Server job processing definitions, Scheduling tables, and Calendars in Enterprise Controlstation.
xii
Notational Conventions
The following abbreviations are used in this guide:
Abbreviation ENTERPRISE/CS Description Enterprise Controlstation
The following conventions are used in this guide:

Convention <key> Description When describing keystrokes, angle brackets are used to enclose the name of a key (e.g., <F1>). When two keys are joined with + as in <Shift>+<F1>, hold down <Shift> while pressing <F1>. This represents an option selection sequence. For example: Users and Groups => Groups => Add means that you first select Users and Groups from the menu bar; then select the Groups option from the sub-menu. Finally, select the Add option from the Groups sub-menu. The vertical bar is used to separate choices. For example, when used as part of a parameter, {AND|OR} means that you specify either AND or OR. Square brackets are used to enclose parameters that are optional. In commands and parameters, angle brackets are used to enclose variable information. For example, the command: cd <controlm_path> means that you specify cd followed by the path of CONTROL-M. An italic font is used for the name of publications.
Menu => Option
{Option A|Option B}
[Parameter] <variable>
italic
About This Book
xiii
xiv
General Information
CONTROL-M/Agent is a component of CONTROL-M for Business Integrated Scheduling. This family of products handles production control and schedules, submits and tracks jobs across your network. CONTROL-M/Agent processes job-handling requests from CONTROL-M/Server. CONTROL-M/Agent submits jobs for execution on the Agent platform, monitors the jobs, and performs post-processing analysis of sysout files. The completion status of jobs and the results of post-processing analysis are transmitted back to CONTROL-M/Server. This guide describes concepts and tools required by the administrator to set up and manage CONTROL-M/Agent on Unix. This chapter provides general information about the installation and administration of CONTROL-M/Agent. An overall description of concepts relating to ENTERPRISE/CS and CONTROL-M/Server is provided in the Enterprise Controlstation User Guide.
General Information
1-1
Figure 1-1
CONTROL-M Scheduling Solution
CONTROL-M/Server can submit and track jobs on multiple Agent platforms in a network. Job handling requests managed by CONTROL-M/Agent can consist of any of the following: Instructions to submit a job on the Agent platform. Requests for information about jobs on the Agent platform that have been submitted, are currently executing, or have recently completed. Requests to view or edit job script statements. Requests to view job sysout or job documentation.
In addition, CONTROL-M/Agent can handle job sysout and issue Shout messages according to job processing parameters supplied with a job submission request.
1-2
CONTROL-M/Agent Components
The following components are described: Agent Configuration File Utilities
Agent Configuration File

The Agent Configuration file contains parameters used by CONTROL-M/Agent to communicate with CONTROL-M/Server, and pointers to files used by CONTROL-M/Agent. The CONTROL-M/Agent installation procedure creates a unique Agent Configuration file for each platform on which it is installed. The parameters in this file are assigned values during the installation procedure. Most parameters can be modified after installation. Table 1-1 describes Agent Configuration parameters in the file.
Table 1-1 Agent Configuration Parameters (Part 1 of 2) Location of the CONTROL-M/Agent program. Location of files used by CONTROL-M/Agent. Hostname of the computer where the primary CONTROL-M/Server is installed. Hostname of the computer on which a backup CONTROL-M/Server has been authorized to handle the workload of the primary CONTROL-M/Server if a hardware or software failure occurs. This parameter specifies the port used in the Server platform for receiving data from the Agent platform. The value assigned to this parameter must match the value assigned to the Agent-to-Server Port Number parameter on the Server platform. Default: 7005 The second port is specified using parameter Server-to-Agent Port Number (see below).
Product Directory Agent Directory CONTROL-M/Server Host Name Mirror CONTROL-M/Server Host Name Agent-to-Server Port Number
General Information
1-3
Table 1-1
Agent Configuration Parameters (Part 2 of 2) Agent platform Port number for communication with the Server platform. Default: 7006 The value specified must match the value assigned to the Server-to-Agent Port Number parameter for this platforms node ID in the Server platform. Verify that the specified port number is not used for any other purpose in the Agent platform. The value for this parameter must be a number between 1024 and 65533 inclusive. Default printer to which job sysout is directed. Protocol used to communicate with CONTROL-M/Server (TCP/IP). Maximum number of retries to send messages to CONTROL-M/Server. Default: 12 Communication timeout (in seconds). Default: 120 Time to wait between retries when a timeout occurs (in seconds). Default: 0 Diagnostic level of CONTROL-M/Agent (for use by Technical Support). Determines types of diagnostics messages generated. This parameter is normally set to zero (that is, no diagnostics). Default: 0
Server-to-Agent Port Number
Default Printer Communication Protocol Maximum Retries Timeout Time Between Retries Diagnostic Level
Utilities
Certain CONTROL-M/Server utilities can be invoked from an Agent platform, either by the user or by a batch job running on the platform. When a utility is invoked, a request is sent to the CONTROL-M/Server. The utility is executed in CONTROL-M/Server. Output, if any, is sent back to the Agent platform.
1-4
Figure 1-2
CONTROL-M/Server Utility Workflow
The utilities described in the table below can be invoked on an Agent platform.
Table 1-2 CONTROL-M/Agent Utilities
Utility
ag_ping ctmcreate
Description
Verifies that CONTROL-M/Server is active on the Server platform that is connected to the Agent platform. Creates a job in the Active Jobs file. This utility executes in CONTROL-M/Server. Detects the successful completion of a file transfer activity. Updates a Quantitative resource in the Resources table. This utility executes in CONTROL-M/Server. Issues a shout message to an indicated destination. This utility executes in CONTROL-M/Server. Performs operations on the Prerequisite Conditions table. This utility executes in CONTROL-M/Server. Lists the status of each Control resource in the Resources table. This utility executes in CONTROL-M/Server. Performs operations on quantitative resources in the Resources table. This utility executes in CONTROL-M/Server.
ctmfw ctmloadset ctmshout ctmcontb ecactltb ecaqrtab
General Information
1-5
Most of these utilities are described in the utility chapter of the CONTROL-M/Server Administrator Guide for the appropriate platform. The ag_ping utility (called the ctmagping utility on some platforms) is described below. Some of the utilities require special formatting for transmission to the Server platform. See Special Utility Parameter Formats on page 1-7.
Note
Unlike the equivalent utilities in CONTROL-M/Server, some of these utilities are not interactive when invoked from the Agent platform. They must be executed in batch mode with all the required parameters.
Example ctmloadset TOTAL CPU@diana 80% ag_ping
This utility verifies that CONTROL-M/Server is active on the Server platform connected to the Agent platform. From the operating system prompt, specify the appropriate command:
ag_ping
The utility attempts to communicate with CONTROL-M/Server and indicates whether the attempt succeeded or failed.
1-6
Special Utility Parameter Formats

[UNIX] Commands that are invoked from Unix Agent platforms are embedded in double quotes when sent to the Server platform. As a result, certain symbols in a command may not be interpreted as you intended. To ensure that a symbol is translated correctly, it must be preceded by a backslash (\). Example
ctmcreate ...-cmdline ls -l \$HOME
Example (Unix)
ctmcreate -tasktype command -cmdline \d:\program files\bmc software\control-m agent\util\_sleep\ 200 ctmshout -o 1234 -user ECS -message \File not found \ -severity v
Directing Output From Utilities
Some utilities generate reports that can be directed to a file. These utilities have <Output parameters>. If output parameters are specified, the utility output is directed to a file on the Server platform. If output parameters are not specified, the output is routed to the default output device. [UNIX] Output can be redirected to the Agent platform by specifying a full path name of the file after the redirection (>) character.
General Information
1-7
1-8
Installation and Administration
This chapter contains information that is specific for the CONTROL-M/ Agent for Unix. For general information about CONTROL-M Agents, see Chapter 1, General Information.
System Requirements
System requirements for operating CONTROL-M/Agent under Unix are described in Table 2-1.
Table 2-1 Agent for Unix Software Requirements One of the following Unix operating systems (or binary compatible version): Solaris 2.6, 2.7, and 2.8 AIX 4.3.2 and 4.3.3 (with 64-bit support) HP-UX 9000 10.20, 11.0, and 11.11 Digital Unix (OSF) 4.0f, 5.0a, 5.0b, and 5.1 Data General 4.2 (Intel Processor) Reliant Unix (Pyramid DC-OSx 1.1-94c079 or Siemens SINIX) 5.43, 5.44, and 5.45 Linux Red Hat version 5.2 and 6.2 Sequent (DYNIX) 4.4.5, 4.4.6, 4.4.7, and 4.4.8 NCR 3.02 IRIX (Silicon Graphics) 6.5 SCO UnixWare 7.1.0 5 MB free disk space in the CONTROL-M/Agent home directory. Additional disk space is required for job sysouts.
Software Requirements
Disk Space
2-1
Table 2-1 Media Drive
Agent for Unix Software Requirements CD-ROM drive. It is recommended that you use a CD-ROM drive on the same platform type as the target installation machine.
Before Installing
Before installing CONTROL-M/Agent for the first time on each Agent platform, the following preliminary procedures must be performed: Define a CONTROL-M/Agent user. If NIS is used at your site, create an entry for CONTROL-M/Agent in the NIS Services map. This is only required the first time a CONTROL-M/Agent is installed on any platform at your site.
Defining a CONTROL-M/Agent User

The procedure for defining a user varies according to the type of Unix system running on the Agent platform. Procedures for various types of Unix systems are detailed in Appendix A, Creating a Unix User for CONTROL-M/Agent .
Creating an Entry in the Services Map for NIS

If NIS is used at your site, it is necessary to create an entry in the Services map for CONTROL-M/Agent before proceeding with the installation. This entry is created only once for all Agent platforms.
Note
For Solaris and AIX platforms: Whether or not an entry should be created in the Services map depends on the search path for the services file. For more information, see Determining the Search Path (Solaris and AIX Only) on page 2-3
2-2
Request that your NIS administrator create the following entry in the Services map:
<service_name> <port_number>/<protocol> #CONTROL-M/Agent
where:
<service_name> <port_number> Recommended value ctmagent. Value of CONTROL-M/Agent configuration parameter Server-to-Agent Port Number (the default value for this parameter in CONTROL-M/Server is 7006). Protocol used for communication with CONTROL-M/ Server (udp or tcp). The protocol specified here must be the same as that specified for customization parameter Communication Protocol on the Server platform.
<protocol>
Example ctmagent 7006/tcp #CONTROL-M/Agent
Determining the Search Path (Solaris and AIX Only)
For Solaris and AIX platforms, the search path for the services file is used to determine whether you should create an entry in the Services map for CONTROL-M/Agent. File /etc/nsswitch.nis contains an entry that determines the precedence of the search path for the services file. A sample entry in the nsswitch file is:
services: files nis
If the services entry in the nsswitch file contains the keyword files, regardless of the order of the keywords, the system will look for CONTROL-M/Agent on the local file system. Therefore, do not create an entry in the Services map for CONTROL-M/Agent.
2-3
LINUX SU Command
In the Linux operating system, the standard Unix command su may not return the correct value. During installation of CONTROL-M/Agent, a test is performed which checks the su command. If the test fails, messages similar to the following are displayed:
su test failed: su - ctmagent -c exit 6 Expecting Return Code = 6: 0 returned Change CTM_SU_PATH variable in ag_config.dat file to: ctmagent_owner/ctm/exe_Linux/su
To enable CONTROL-M/Agent to use a supplied version of the su command, instead of the operating system version, make the following modification to the ~ctmagent_owner/ctm/data/agconfig.dat file after installation is completed:
CTM_SU_PATH <full agent path>/ctm/exe_Linux/su
Installation
Installation of CONTROL-M/Agent consists of the following procedures: 1. Configuring the CD-ROM drive 2. Loading the installation media 3. Customizing the installation Customizing the installation can be performed either interactively or as a batch procedure. A separate description is provided for each method.
Note
CONTROL-M/Agent can also be installed using a silent installation that is driven by an input file will all the necessary installation parameter. For more information, see Silent Installation of CONTROL-M/Agent on page 2-16.
2-4
Configuring the CD-ROM Drive
The CONTROL-M installation CD can be loaded either from a local drive on the target platform, or from a remote drive on the same or different type of platform. Depending on whether or not the CD-ROM drive is local, certain steps (described below) will be necessary to ensure that the drive is mounted and accessed correctly. If the CD-ROM drive is connected to a Solaris machine, no special actions need to be taken. Otherwise, perform the following steps:
Step 1 Step 2 Step 3
Log in as user root. Create an empty directory for mounting the CD-ROM drive. Connect the CD-ROM drive to the mount directory using the mount command.
Note
The mount command is different for each platform. It is recommended to use the ISO-9660 option (where available) when using this command. Consult your system administrator about the exact usage of mount.
Loading the Installation CD-ROM Step 1 Step 2
Log in to the Agent platform as root. If NIS is used at your site, specify the following command to verify that NIS is running:
ypwhich
If the system responds with the host name of a platform (the NIS server), then NIS is running.
Step 3
Go to the home directory of CONTROL-M/Agent user account using the following command:
cd <user_home_dir>
2-5
Step 4
Specify the following command to begin the installation procedure from the CD-ROM:
/<cd_path>/cd_inst Note
For HP-UX use CD_INST (all uppercase). A screen similar to the following is displayed:
+----------------------------------+ | Products Available On this Media | +----------------------------------+ 1) FDXXXX CONTROL-M/Server for Solaris,AIX,HP-UX... 2) FDXXXX CONTROL-M/Agent for Solaris,AIX,HP-UX... q) Quit Select the product to install:
Step 5
Specify 2 for CONTROL-M/Agent. The following prompt is displayed:

Enter destination directory (default: /home/ctmagent):
Step 6
Specify the directory where you wish to install the CONTROL-M/Agent, or press <Enter> to accept the default. The following prompt is displayed:
Enter CONTROL-M/Agent UNIX username [ctmagent]:
Step 7
Specify the Unix user name of the CONTROL-M/Agent user account, or press <Enter> to accept the default. The following menu is displayed:
+---------------------------------+ | CONTROL-M/Agent Installation | +---------------------------------+ N - New installation of CONTROL-M/Agent U - Upgrade from previous version of CONTROL-M/Agent Q - Quit Select the required option:
Step 8
2-6
Step 9
Specify N for a new installation, U for an upgrade from a previous release, or Q to exit the CONTROL-M/Agent installation script.
Note
If you are planning to customize the installation using the non-interactive procedure, enter Q to exit the installation script. Continue with NonInteractive Procedure on page 2-11. Progress messages similar to the following are displayed:
CONTROL-M/Agent for AIX will be installed in "/home/ctmagent1" directory. Loading files. Please wait ...
The CONTROL-M/Agent files are extracted from the media. This process requires several minutes. After all required files have been loaded, messages similar to the following are displayed (the numbers displayed can vary from those appearing below):
34+1 records in 700+0 records out Load completed successfully or Upgrade completed successfully Executing ctm/scripts/ag_custom...
Note
The interactive customization procedure starts automatically at this point. Continue with Step 2 of Interactive Procedure on page 2-7.
Customizing the Installation
Customization can be performed as an interactive or as a non-interactive procedure. The non-interactive procedure is suitable for customizing a large number of platforms as a batch process.
Interactive Procedure
The following procedure can be used to customize the installation. This procedure prompts you to supply all required configuration parameters.
2-7
Step 1
If you are not performing this procedure immediately after loading the installation media, verify that you are logged in as root and that you are performing the procedure in the CONTROL-M/Agent user home directory. Specify the following command:
./ctm/scripts/ag_custom
Step 2
The following prompt is displayed:

Enter CONTROL-M/Agent UNIX username [<default_user>]:
where <default_user> is the owner of the current directory. Specify the Unix username of the CONTROL-M/Agent user account, or press <Enter> to accept the default.
Step 3
The following menu is displayed:

+---------------------------------+ | CONTROL-M/Agent Customization | +---------------------------------+ N - Customization of a newly installed CONTROL-M/Agent U - Upgrade from previous version of CONTROL-M/Agent Q - Quit Select the required option:
Step 4
Specify N for a new installation or U for an upgrade from a previous release. Press Enter. For an upgrade, the installation continues without any prompts. For a new installation, continue with the following steps.
Step 5
A prompt similar to the following is displayed:

This procedure will install CONTROL-M/Agent for <platform> in directory /home/ctmagent1. Do you wish to proceed? (y/n)
2-8
Step 6
Verify that the displayed information is correct, then type y and press <Enter>.
Note
Note for Solaris: All /etc files must be symbolic links to the /etc/inetd directory. If one of the two system files that are modified during the installation procedure (see Changes to System Files later in this chapter) is not a symbolic link, the following prompt will appear:
File: <file1> is not symbolic-link to <file2>. Confirm to continue (y/n):
Specify n to interrupt this procedure and make the symbolic link manually. If you specify y to continue, a message similar to the following will appear:
Notice: File $_SERVICES_FILE will be changed.
Step 7
Messages similar to the following are now displayed:

This procedure may modify certain system files. The original /etc/services file is saved in /etc/services.21822. The original /etc/inetd.conf file is saved in /etc/inetd.conf.21822. Enter the Agent service-name: [ctmagent]
Step 8
Specify the service-name to be recorded in the /etc/inetd.conf file, and press <Enter>. If NIS is used at your site, the value specified should be the service-name recorded in the NIS services map (see Before Installing on page 2-2).
Step 9
For each remaining parameter, the appropriate prompt from the list below is displayed. In each instance, specify a value for the parameter or just press <Enter> to accept the default value displayed. These parameters are described in Chapter 1, General Information.
2-9
Enter Enter Enter Enter Enter Enter Enter Step 10
the the the the the the the
CONTROL-M/Server Host Name: Backup CONTROL-M/Server Host Name: Agent-to-Server Port Number: [7005] Maximum Retries: [5] Timeout: [60] Time Between Retries: [0] Default Printer: [printer]
The next prompt depends on whether NIS is used at your site. If NIS is not used at your site the following prompts are displayed:
Enter the Server-to-Agent Port Number: [7006] Enter the Communication Protocol: [UDP]
Specify a value for each parameter or press <Enter> to accept the default value displayed If NIS is used at your site, these parameters are read from the Services file. The values assigned are displayed at this point.
Step 11
The following message is displayed:

CONTROL-M/Agent installation procedure completed successfully.
This marks the completion of the installation/customization procedure.
2-10
Non-Interactive Procedure
The following procedure can be used to customize the installation using a partially or completely non-interactive process. A typical installation is prepared on one Agent using the interactive customization procedure. This installation is used as the basis for subsequent installations. On subsequent Agent platforms, installation consists of two steps: 1. The files and directory structure of the typical installation are copied into place as a block using the Unix tar command 2. Parameters are customized from the command line interface. Each parameter is configured with the default setting or a new value using an optional flag on the customization command. If all required parameters are specified in the command line, the procedure executes with no user interaction. This mode of operation allows you to customize the installation using a script file that can be run as a batch procedure. This method can be especially useful for installing CONTROL-M/Agent on a large number of platforms. If one or more parameters are not specified in the command line, you are prompted to specify values for the missing parameters.
Step 1
To create a tar file containing the typical installation: Perform the installation and interactive customization procedures as described in Loading the Installation CD-ROM on page 2-5 and Interactive Procedure on page 2-7.
Step 2
If you are not performing this procedure immediately after loading the installation media, verify that you are logged in as root to the CONTROL-M/Agent user home directory. Create a tar file in the home directory using the following command:
tar cvf ctmagnt.tar .
Step 3
2-11
Step 4
To copy and customize the typical installation on another computer: Create the CONTROL-M/Agent user home directory on the computer as described in Defining a CONTROL-M/Agent User on page 2-2. Copy the tar file you created in Step 3 to the CONTROL-M/Agent home directory on the target computer.
Step 5
Load the installation media as described in Step 1 through Step 4 of Loading the Installation CD-ROM on page 2-5. Specify Q to exit the CONTROL-M/Agent Installation Menu. Log in the Agent platform as root and go to the home directory of the CONTROL-M/Agent. Extract the tar file using the following command:
tar xvf ctmagnt.tar
Step 6
Step 7
Step 8
Specify the following command:

ctm/scripts/ag_custom [-A (Automatic installation)] -i <Installation type {N-new|U-Upgrade}> -u <UNIX Agent username> [-n <Agent service name> ] [-c <CONTROL-M/Server Host Name> ] [-b <Backup CONTROL-M/Server Host Name> ] [-a <Agent-to-Server Port Number> ] [-s <Server-to-Agent Port Number> ] [-p <Protocol> ] [-m <Maximum retries> ] [-t <Timeout interval> ] [-r <Time Between Retries> ] [-d <Default Printer> ] [-K (Kill the inetd process)] [-h (display a list of valid parameters)]
2-12
This command allows you to change parameter values without interactive prompts.
Note
If a parameter flag is omitted, an interactive prompt is diplayed for that parameter. To create a batch process with no interactive prompts, you must specify values for all the parameters, or use the -A flag to accept defaults from the standard installation. Even when you use the -A flag, you must specify the installation type and Unix username for each Agent platform with the -i and -u flags. If you omit these flags, interactive prompts are displayed for these parameters. The optional flags controlling custom parameters are described in Table 2-2.
Table 2-2 Custom Installation Parameters for the Unix Agent
Parm -A -i -u -n
Description
Perform the installation using default parameter values. Mandatory parameter flags -i and -u are must still be specified. Valid values: N for a new installation, U for an upgrade. This flag is mandatory. Unix username for the account in which to install CONTROL-M/ Agent. This flag is mandatory. Agent service name to be recorded in the /etc/inetd.conf file. If NIS is used at your site, the value specified should be the service name recorded in the NIS services map. See Before Installing on page 2-2. Host name of the CONTROL-M Server. This parameter is described in Chapter 1, General Information. Host name of the backup CONTROL-M/Server. This parameter is described in Chapter 1, General Information. Specify none if you do not want to provide a value for this parameter.
-c -b
2-13
Table 2-2
Custom Installation Parameters for the Unix Agent Agent-to-Server Port Number Maximum Retries Agent Unix Username Agent Service Name Timeout Time Between Retries Default Printer These parameters are described in Chapter 1, General Information. Specify a value for any or all these parameters. Server-to-Agent Port Number Protocol If NIS is not used at your site, specify a value for one or both of these parameters. If NIS is used, these parameters are read from the Services file and should not be specified in the command line. Kill process inetd during the installation procedure, instead of refreshing (default). We recommend using the default by not specifying -K. Specify -h to display a list of valid parameters.
-a -m -u -n -t -r -d
-s -p
-K
-h Step 9
A prompt similar to the following is displayed:

This procedure will install CONTROL-M/Agent for AIX in directory /home/ctmagent1. Do you wish to proceed? (y/n)
2-14
Step 10
Verify that the displayed information is correct; then specify Y.

Note
Note for Solaris: All /etc files must be symbolic links to the /etc/inetd directory. If one of the two system files that are modified during the installation procedure (see Changes to System Files later in this chapter) is not a symbolic link, the following prompt will appear:
File: <file1> is not symbolic-link to <file2>. Confirm to continue (y/n):
Specify n to interrupt this procedure and make the symbolic link manually. If you specify y to continue, a message similar to the following will appear:
Notice: File $_SERVICES_FILE will be changed.
Step 11
Messages similar to the following are displayed:

This procedure may modify certain system files. It saves the original /etc/services file in /etc/ services.25384 and the /etc/inetd.conf file in /etc/ inetd.conf.25384
Step 12
If no CONTROL-M/Agent service-name was specified in the command line, the following prompt is displayed:
Enter the Agent service-name: [ctmagent]
Specify the service-name to be recorded in the /etc/inetd.conf file. If NIS is used at your site, the value specified should be the service-name recorded in the NIS services map (see Before Installing on page 2-2).
Step 13
For each remaining parameter not specified in the command line, the appropriate prompt from the list below is displayed. In each instance, specify a value for the parameter or press <Enter> to accept the
2-15
displayed default value. These parameters are described in Chapter 1, General Information.
Note
During installation of CONTROL-M/Agent on the CONTROL-M/Server platform, the value for the Host Name parameter is supplied automatically, and the corresponding prompt is not displayed.
Step 14
The following prompts may be displayed only if NIS is not used at your site. If NIS is used, these parameters are read from the Services file.
Enter the Server-to-Agent Port Number: [7006] Enter the Communication Protocol: [UDP]
Step 15
The following message is displayed:

CONTROL-M/Agent installation procedure completed successfully.
This marks the completion of the installation procedure.
Silent Installation of CONTROL-M/Agent

Silent installation is an alternate method of installation. This method uses a special input file to determine the values of installation parameters. This same file can then be copied as many times as necessary to different computers on which the CONTROL-M/Agent is to be installed. Before performing the steps shown below, use the procedure described above to configure the installation CD. (See Configuring the CD-ROM Drive on page 2-5.)
2-16
Specifying Installation Parameters
The primary input for the silent installation is a special installation parameter file. Prepare this file before continuing with the installation steps below. The table on the following page describes the parameters in the installation parameters file:
Notes:
The first two lines of this file, must contain the following text: : fd_value=FDnnnn Where nnnn is the FD number of the CONTROL-M/Agent. All parameters in this file must be in UPPERCASE and must not include blanks before or after the equal sign (=).
Description
Type of installation: For a new installation, specify n. For an upgrade from a previous version of CONTROL-M/Agent specify u. Name of the CONTROL-M/Agent user account. Unix service name of the Server to Agent port. If you have NIS installed on your network, use the following command to check the service name: ypcat services | grep <port_number> If you do not have NIS installed, use the following command: cat /etc/services | grep <port_number> Hostname of the computer where the primary CONTROL-M/Server is installed. Hostname of the computer on which a backup CONTROL-M/Server has been authorized to handle the workload of the primary CONTROL-M/Server if a hardware or software failure occurs.
Parameter
AGENT_INST=
AGENT_USER= AGENT_SERVICE=
AGENT_SRV_HOST= AGENT_SRV_BCKP_HOST=
2-17
Parameter
AGENT_AS_PORT=
Description
This parameter specifies the port used in the Server platform for receiving data from the Agent platform. The value assigned to this parameter must match the value assigned to the Agent-to-Server Port Number parameter on the Server platform. Default: 7005 The second port is specified using parameter Server-to-Agent Port Number (see below). Agent platform Port number for communication with the Server platform. Default: 7006 The value specified must match the value assigned to the Serverto-Agent Port Number parameter for this platforms node ID in the Server platform. Verify that the specified port number is not used for any other purpose in the Agent platform. The value for this parameter must be a number between 1024 and 65533 inclusive. Communication protocol. (TCP is the only valid value for this parameter.) Communication timeout (in seconds). Default: 120 Time (in seconds) to wait between retries when a timeout occurs for communication between the CONTROL-M/Agent and CONTROL-M/Server. Minimum: 0 (you cannot specify a negative number for this parameter). Maximum number of retries to send messages to CONTROL-M/ Server. Default: 12 Name of the default printer. Full path name of the log file for messages that are produced by the silent installation.
AGENT_SA_PORT=
AGENT_COMM_PROT=TCP AGENT_TIMEOUT= AGENT_TIME_BTW_RETR=
AGENT_MAX_RETR=12 AGENT_DEFLT_PRNT= ICE_ERROR_LOG=
2-18
Sample Input File
The following is a sample input file with the necessary installation parameter:
: fd_value=FD4001
#### n - new, u - upgrade AGENT_INST=n #### owner of controlm agent AGENT_USER=ctm6test #### from /etc/services AGENT_SERVICE=ctm_agtcp3 #### remote server host name AGENT_SRV_HOST=fire #### remote backup server host AGENT_SRV_BCKP_HOST=fire #### Agent => Server port AGENT_AS_PORT=5056 #### Server => Agent port AGENT_SA_PORT=7513 #### Communication protocol TCP AGENT_COMM_PROT=TCP #### Maximum retries AGENT_MAX_RETR=12 #### Timeout AGENT_TIMEOUT=120 #### Time between retries AGENT_TIME_BTW_RETR=0 #### Default printer
2-19
AGENT_DEFLT_PRNT=lpr # definitions for working in silent mode # log file for messages in silent mode ICE_ERROR_LOG=/tmp/silent_error.log
Running the Silent Installation
Use the following steps to run the silent installation of CONTROL-M/ Agent on each computer: 1. Log in to the Unix account of the CONTROL-M/Agent 2. Copy the installation parameters file that you already prepared to the home directory of the CONTROL-M/Agent user. 3. Use the following command to give READ access for the installation parameters file to the installation procedure chmod 755 <parm_file_name> 4. Use the following command to run the silent installation procedure: <CD_path>/cd_inst -f <parm_file_path> Where <parm_file_path> is the full path of the prepared installation parameters file. 5. This completes the silent installation procedure.
Uninstalling CONTROL-M/Agent
Utility ag_uninstall can be used to uninstall CONTROL-M/Agent for Unix. This utility removes all files from the CONTROL-M/Agent home directory.
2-20
Before performing ag_uninstall, verify that no jobs are running on the Agent and no Agent utilities are executing on the Server.
Changes to System Files

The installation procedure modifies system files as follows: 1. The following line is added to file /etc/inetd.conf:
<service> <socket_type> <protocol> wait root <agent_exe> p_ctmag -e <agent_home>/ctm
Table 2-3 describes the variables in this line.

Table 2-3 <service> <socket_type> <protocol> <agent_exe> <agent_home> Configuration CONTROL-M/Agent for Unix Agent service-name specified during installation. Default: ctmagent. Socket type used for the service (dgram for udp; stream for tcp). Protocol used for communication between the Server platform and the Agent platform (udp or tcp). Path of CONTROL-M/Agent executable files. Path of CONTROL-M/Agent user home directory.
2. If NIS is not used at your site, the following line is added to file /etc/ services:
<service> <port_number>/<protocol> #CONTROL-M Agent
Table 2-4 describes the variables in this line.

Table 2-4 <service> Service Definition CONTROL-M/Agent for Unix Agent service-name specified during installation. Default: ctmagent.
2-21
Table 2-4 <protocol>
Service Definition CONTROL-M/Agent for Unix Protocol used for communication between the Server platform and the Agent platform (udp or tcp). Value specified for parameter Server-toAgent Port Number.
<port_number>
3.
[AIX]:
The following lines are added to file /etc/rc.nfs:
#Refresh the inetd process refresh -s inetd #End refresh the inetd process
CONTROL-M/Agent Configuration Parameters

Table 2-5 describes configuration parameters that are relevant to the CONTROL-M/Agent for Unix. These parameters are defined in the agconfig.dat file.
Table 2-5 Unix Agent Configuration Parameters
Parameter
CTM_SU_PATH
Description
Specifies an alternative path that CONTROL-M/ Agent will use to look for the su command. By default, CONTROL-M looks for this command at /usr/bin.
CTM_PARM_ENC
Specifies a character to be used to enclose job processing parameters to be passed to jobs by CONTROL-M/Agent. Any character or string can be specified for this parameter. A blank space (in single or double quotes) is also a valid value.
2-22
Starting/Stopping CONTROL-M/Agent
An instance of CONTROL-M/Agent is started automatically each time the inetd listener process detects a request from CONTROL-M/Server at the Agent port. The instance of CONTROL-M/Agent remains active while the request is handled; after handling of the request is completed, the instance terminates. Several instances of CONTROL-M/Agent can be active concurrently on the Agent platform. No user action is required to start or stop instances of CONTROL-M/ Agent.
Maintaining CONTROL-M/Agent
CONTROL-M/Agent is supplied with a maintenance program that can be used to view or modify configuration parameters.
To start the CONTROL-M/Agent Maintenance program: Step 1
Log into the Agent platform as the CONTROL-M/Agent owner (e.g., user ctmagent). Specify command: ag_menu The following menu is displayed:
Step 2
2-23
CONTROL-M/Agent Main Menu ------------------------Select one of the following options: 1 - Configuration Parameters 2 - Communication Diagnostic Report q - Quit Enter option number ---> Step 3
Specify the appropriate number or letter to select an option from the menu. The options available from this menu are described in Table 2-6.
Table 2-6 Options of the CONTROL-M Agent Main Menu View or modify CONTROL-M/Agent configuration parameters (described below). Check parameters and environmental conditions relevant to communication between the Agent platform and the Server platform. This option is typically used at the request of Technical Support to determine the cause of a communication problem. When this option is selected, a diagnostic program is executed and a report listing the findings is generated. Exit to the shell prompt.
Configuration Parameters Communication Diagnostic Report
Quit
View or Modify Configuration Parameters

The option CONTROL-M/Agent Main Menu Configuration Parameters is used to view or modify CONTROL-M/Agent configuration parameters. When you select this option, the following menu is displayed (the parameter values that appear can differ from those below):
Configuration Parameters -----------------------Agent Directory: /home/ctmag/ctm
2-24
1) CONTROL-M/Server Host Name: brigit 2) Agent-to-Server Port Number: 7005 Server-to-Agent Port Number: 7503 Communication Protocol: TCP 3) Mirror CONTROL-M/Server Host Names: aristo diana 4) Default Printer: lpr 5) Maximum Retries: 10 6) Timeout: 70 7) Time Between Retries: 5 8) Diagnostic Level (0-4): 0 9) Communication Trace 0 Q) Quit Enter item number you wish to change:
For each parameter, the current value is displayed. These parameters are described in Chapter 1, General Information. To modify a parameter, specify the appropriate number. Parameters that cannot be changed do not have number. You are prompted to supply a new value for the parameter. CONTROL-M/Server Host Name The CONTROL-M/Server host name contains the host name of the current active server. When CONTROL-M is started the current active Server host name is the name of the primary environment host. If the primary environment fails and a Failover occurs, the mirror environment CONTROL-M/Server is activated and becomes the current active Server. The mirror environment CONTROL-M/Server then sends a control message to the agent identifying itself as the current active Server, and
2-25
the host name of the mirror environment is authenticated against the list of authorized servers. From now on all jobs that are still active will communicate with the new current active Server, and send it their job status information. Note that only one Server can be active at any one time.
Note
To modify the Communication Protocol parameter or the Server to Agent Port number, you must re-customize the CONTROL-M/Agent installation. See Customizing the Installation on page 2-7. If you select the parameter Mirror Environment CONTROL-M/ Server Host Name, the menu described below is displayed.
Modify Mirror CONTROL-M/Server Host Names

The option Configuration parameters => Mirror CONTROL-M/ Server Host Name is used to add host names to or delete host names from the Mirror CONTROL-M/Servers file. When you select this option, the following menu is displayed (the parameter values that appear may differ from those below).
Note
The primary host name must be included in the list of authorized host names.
Authorized Mirror CONTROL-M/Server Host Name ---------------------------------1) 2) Q) Add new Host Name: Delete Host Name: Quit
[brigit diana]
Enter item number you wish to change:
The options available from this menu are described in Table 2-7.
2-26
Table 2-7
Options of the Server Host Names Menu Add a backup CONTROL-M/Server host name to the Mirror CONTROL-M/Server file. Delete a backup CONTROL-M/Server host name from the Mirror CONTROL-M/Server file. All host names contained in the file (excluding the current CONTROL-M/Server host name) are listed next to this menu option. Exit to the Configuration Parameters menu.
Add new Host Name Delete Host Name
Quit
To add or delete a host name, specify the appropriate option from the menu. You are prompted to supply the host name to add or delete.
View CONTROL-M/Agent Messages

You can view messages issued by CONTROL-M/Agent for diagnostic purposes. These messages are contained in files TRACE, AGC and AG, and are found in the PROCLOG subdirectories under the Agent directory (e.g., /home/ctmag/ctm/proclog/). For CONTROL-M/Agent to generate program and communication diagnostic messages in the TRACE file, the Diagnostic Level must be assigned a value in the range 1 to 4. Diagnostic messages are suppressed by changing the Diagnostic Level to 0. The Diagnostic Level can be modified by accessing the Configuration Parameters menu from the CONTROL-M/Agent Main menu (see View or Modify Configuration Parameters on page 2-24). To turn on communication trace messages, set the Communication Trace variable to 1 in the CONTROL-M/Agent Main menu (see View or Modify Configuration Parameters on page 2-24).
Note
After generating messages for diagnosis, the value of the Diagnostic Level parameter should be reset to 0.
2-27
View CONTROL-M/Agent Logs

CONTROL-M/Agent writes an entry to a log file for each job it submits. A new log file is created each day in the ctm/data/ directory. The name of the log file is ctmag_<date>.log, where <date> is the date the jobs were submitted. CONTROL-M/Agent keeps the log files for the number of days specified in the system parameter Maximum Days to Retain Sysout Files. (For more information see Chapter 5, Customization Parameters in the CONTROL-M/Server for Unix Admnistrator Guide).
Writing Scripts
When writing a shell script to be run as a CONTROL-M job on an Agent platform, the following factors must be considered to conform with CONTROL-Ms analysis of the script: Specification of the shell type under which the script will run. Run-time environmental factors affecting execution of the script. Usage of the job processing parameter On Statement/Code with regard to shell script statements and the script exit code.
These factors and other considerations are discussed in this section. It is recommended that you run each script manually to validate the scripts syntax before running the script under CONTROL-M.
Note
Command type jobs must be in Bourne shell syntax only.
Specifying the Shell Type

To enable CONTROL-M to recognize the scripts shell type, specify the first line of the script as follows:
2-28
#! <shell path>
where <shell path> is taken from Table 2-8.

Table 2-8 Shell Type Bourne csh tush Korn Shell Paths Shell Path /bin/sh /bin/csh /bin/tcsh /bin/ksh Default Switch -x -v -v -x -v Other Switches -v
Note
Arguments specified after the shell name are discarded by CONTROL-M, with the following exception: -x is supported when running a script under the Bourne shell or Korn shell.
Example
The following is the first line of a script that runs under the C shell:
#! /bin/csh -x
Note that in this example, argument -x is not supported.

Note
For Korn shells: To change the default switch from -x to -v add the following line to the ag_config.dat file: CTM_PRM_KSH_FLAGS -v. For Bourne shells: To change the default switch from -x to -v add the following line to the ag_config.dat file: CTM_PRM_SH_FLAGS -v. You can specify additional switches for CTM_PRM_SH_FLAGS, but you must include -x or -v. If -x switch is not used, CONTROL-M parses the original script and saves it in a temporary file before running the job.
2-29
Support for REXX-Language Scripts

On certain types of Unix platforms, job scripts to be run under CONTROL-M can be written using the REXX shell language. REXX is supported on the following types of Agent platforms: AIX, SunOS, Solaris and Solaris X86. To activate a REXX script, the REXX product must first be installed on the Agent platform. The first line of the REXX script must specify the full path under which REXX is installed.
Example #!/usr/local/bin/rxx
Run-Time Environment
CONTROL-M runs a job script under the environment specified for the jobs owner (i.e., the user specified in the jobs Owner parameter). This environment affects the following factors in the execution of the script: User login process Shell script startup process Working directory
Each of these factors is described below.

User Login Process
As jobs are submitted for execution, CONTROL-M logs in the user and executes the job (the shell script) using the following command:
su - <owner> -c <script name>
2-30
During the login process, the user environment is set according to the shell type specified in /etc/passwd.
Shell Script Startup Process
The startup process for running the script depends upon the type of shell under which the script will run. When a csh or tcsh script is run, the .cshrc file of the jobs owner is executed as part of the startup process for the script. For all other shell types, the .profile file of the jobs owner is executed as part of the startup process for the script.
.login file is not executed as part of the startup process. CONTROL-M executes scripts in background so there is no terminal associated with the job. Therefore, do not use commands in a script that query terminal characteristics or take input from a terminal. The shell script startup process sets the environment variables that will be available when the script is run. The #! statement, in the first line of the script, (described above) is used to indicate to CONTROL-M under which shell the script is intended to run.
Working Directory
The working directory at the time the script runs is initially set to the home directory of the jobs owner (the home directory for each user is set by the Unix administrator in /etc/passwd). When writing scripts that access files, the path for the file name in the script should be specified either as an absolute path (i.e., full path) or a path relative to the home directory of the jobs owner.
2-31
Scripts and the On Statement/Code Parameter

The following factors relate to the manner in which the job processing parameter On Statement/Code interprets script lines. These factors should be understood when writing scripts in order to obtain the desired results. job processing parameters are described in Chapter 5 in the Enterprise Controlstation User Guide. Type of Script Statement Depending on the shell used, CONTROL-M does not process certain types of script statements for comparison to the text specified in the Stmt subparameter of the On Statement/Code parameter. Therefore, text contained in these script statements should not be specified in the Stmt subparameter: For a Bourne shell, text in if, for, while, and case statements. For a csh shell, text in if statements.
Example
No part of the following script line should be used in the Stmt subparameter of the On Statement/Code parameter:
if [ baseline - eq 0 ]; then
Continuation Lines CONTROL-M does not process continuations lines for comparison to the text specified in the Stmt subparameter of the On Statement/ Code parameter. Therefore, text appearing on a continuation line in a script should not be specified in the Stmt subparameter. Length of Script Statement CONTROL-M only processes the first 132 characters of a script statement for comparison with the text specified in the Stmt subparameter of the On Statement/Code parameter. Therefore, text appearing beyond the first 132 characters of a script statement should not be specified in the Stmt subparameter.
2-32
HERE Documents The term HERE documents refers to lines of text (appearing inside a script) that are passed to a command as input, but are not passed to the shell. The current version of CONTROL-M does not support the job processing parameter On Statement/Code for HERE documents. Example In the following script, line 1 and line 2 make up a HERE document, passed to the following cat command:
cat > /tmp/junk << EOF_EOF line 1 line 2 EOF_EOF echo "DONE"
Utilization of Exit Codes by CONTROL-M

You can cause CONTROL-M to distinguish between different exit codes by using the following expression in the Code subparameter of the On Statement/Code job processing parameter:
COMPSTAT=<value>
where <value> is the exit code of the script.

Example
Assuming that a script exits with an exit code of 5 as follows:

exit 5
This condition can be detected by defining the following On Statement/ Code parameters:
Stmt: * Code: COMPSTAT=5
2-33
Use of Reserved Variable $0

The reserved variable $0 can be used in a script to retrieve information regarding the scripts path. This variable is automatically replaced by a file name before the script is run. This functionality can be disabled by setting the TRANSLATE_$0 configuration parameter to N in the ~ctmagent/ctm/data/agconfig.dat file on the CONTROL-M/Agent. (See Chapter 5, Customization Parameters in the CONTROL-M/Server for Unix Administrator Guide.) Note that CONTROL-M does not support the use of $0 in a sub-script when the -x switch is not used. Instead, CONTROL-M reserves the variable $CTM0 to provide the same information that would be provided by $0.
Example
The following (script a and sub-script b) demonstrates valid usage of variables $0 and $CTM0 in scripts running under CONTROL-M:
Script a #! /bin/sh echo $0 . b Sub-script b memname=basename $CTM0 memlib=dirname $CTM0 ...
2-34
Creating a Unix User for CONTROL-M/Agent
Before installing CONTROL-M/Agent on a Unix platform, you must define the Unix user account under which CONTROL-M/Agent will be installed and will operate. This appendix describes how to define the required user account under the following operating systems: AIX Data General Digital UNIX HP-UX NCR NonStop-UX Pyramid Reliant UNIX Sequent SINIX Solaris SunOS
AIX Agent Platform

The instructions below are based on the assumption that you are working in the X Window environment.
A-1
To define a new user account for CONTROL-M/Agent: Step 1
Log in to the Agent platform as user root. Use smit to define both the group controlm and the user <agent_user> from the Security & Users menu as follows:
Step 2
Specify the command:

cd /etc smit
Step 3
Select Groups => Add a Group. Assign values as follows:

Group NAME controlm
All other parameters can remain with their default values, or can be modified so that they comply with your site standards.
Step 4 Step 5
Select the OK button and wait for the operation to complete. Return to the Security & Users menu. The amount of free disk space required to install CONTROL-M/Agent is stated under System Requirements on page 2-1.
Step 6
Determine the amount of free disk space in the system by opening a new window and specifying the command:
df
A list similar to the following is displayed:

Filesystem Total KB free %used iused %iused Mounted on /dev/hd4 8192 3748 54% 798 38% / /dev/hd2 208896 5316 97% 16598 31% /usr /dev/hd9var 8192 7124 13% 107 5% /var /dev/hd3 8192 7784 4% 39 1% /tmp /dev/hd1 8192 7668 6% 76 3% /home /dev/1v00 61440 4804 92% 167 1% /usr/lpp/info diana: /prod 1962592 131488 93% /prod
A-2
The free column indicates the amount of free space on each file system.
Step 7
Examine the display to locate a file system containing the required amount of free space. In the window in which smit is running, select the Users => Add a User. Set values for the parameters as follows:
User NAME <agent_user> PRIMARY group controlm HOME directory <agent_path> Initial PROGRAM /bin/csh or /bin/tcsh
Step 8
where:
<agent_user>
UNIX user account under which CONTROL-M/Agent is being installed (maximum 8 characters).
<agent_path>
Full path of the directory to be created for the CONTROL-M/Agent user account.
Step 9 Step 10
Click the OK button and wait for the operation to complete. Select the Exit smit option from the pull-down menu.
Note
For security reasons, it is recommended that you assign a password to the CONTROL-M/Agent user account, using the passwd command. For more information on defining user passwords, refer to your AIX Administration Guide.
A-3
HP-UX Agent Platform

To define a new user account for CONTROL-M/Agent: Step 1
Log in as user root. The amount of free disk space required to install CONTROL-M/Agent is stated under System Requirements on page 2-1.
Step 2
Determine the amount of free disk space in the system by specifying the following command:
bdf

Filesystem kbytes used avail capacity Mounted on /dev/vg00/lvol1 104299 51716 42153 55% / /dev/vg00/lvol5 128603 339 115403 0% /tmp /dev/vg00/lvol4 1410747 798985 470687 63% /users /dev/vg00/lvol3 136523 104753 18117 85% /usr host1:/ 926640 778035 55941 93% /hp/home host2:/prod 1962592 1607804 158529 91% /prod
The avail column indicates the amount of free space on each disk.
Step 3
Examine the display for a file system containing the required amount of free space. Use sam to define both the group controlm and the CONTROL-M/Agent user as follows:
4.A
Step 4
Select Users and Groups => Groups => Actions => Add from the menu. Set the Group Name parameter as follows:
Group NAME controlm
4.B
4.C
Click OK and wait for the operation to complete.

A-4
4.D 4.E
Select File Exit to return to the Users and Groups menu. Select Users => Actions => Add. Set values for the parameters as follows:
Login Name <agent_user> User Identification (UID) (accept default value) HOME directory <agent_path> Primary Group Name... controlm Startup Program /bin/csh or /bin/tsch
where: <agent_user> UNIX user account under which CONTROL-M/Agent is being installed (maximum 8 characters). <agent_path> Full path of the directory to be created for the CONTROL-M/Agent user account.
4.F 4.G 4.H
Click OK and wait for the operation to complete. Select File => Exit. Select Previous Level to go back to the main menu.
Note
For security reasons, it is recommended that you assign a password to the CONTROL-M/Agent user account, using the passwd command. For more information on defining user passwords, refer to your HP-UX administration guide.
A-5
Data General, NCR, NonStop-UX, Pyramid, Reliant UNIX, SINIX and Solaris Agent Platforms
To define a new user account for CONTROL-M/Agent: Step 1 Step 2
Log in as user root. Specify the following command to create the group controlm:
groupadd controlm Note
Specify commands exactly as shown, modifying only information between <triangular brackets>. The amount of free disk space required to install CONTROL-M/Agent is stated under System Requirements in Chapter 4, CONTROL-M/Agent for UNIX.
Step 3
Determine the amount of free disk space in the system by specifying the following command:
df -k

Filesystem kbytes used avail capacity Mounted on /dev/dsk/c0t1d0s0 104299 51716 42153 55% / /dev/dsk/c0t1d0s6 1410747 798985 470687 63% /users /dev/dsk/c0t1d0s5 136523 104753 18117 85% /usr host2:/prod 1962592 1607804 158529 91% /prod
The avail column indicates the amount of free space on each file system.
Step 4
Examine the display for a file system containing the required amount of free space. Specify the following command to create the CONTROL-M/Agent user:
Step 5
A-6
useradd -g controlm -s /bin/csh -d <agent_path> <agent_user>
where:
<agent_user>
<agent_path>
Note
For security reasons, it is recommended that you assign a password to the CONTROL-M/Agent user account, using the passwd command. For more information on defining user passwords, refer to your operating system administration guide.
Step 6
Specify the following commands to create the directory <agent_path>:

mkdir <agent_path> chown <agent_user> <agent_path>
Digital UNIX, Sequent and SunOS Agent Platforms

To define a new user account for CONTROL-M/Agent: Step 1 Step 2
Log in as user root. Define the group controlm in file /etc/group. The amount of free disk space required to install CONTROL-M/Agent is stated under System Requirements in Chapter 4, CONTROL-M/Agent for UNIX. Determine the amount of free disk space in the system by specifying the following command:
A-7
df

Filesystem kbytes used avail capacity Mounted on /dev/sd0a 104299 51716 42153 55% / /dev/sd0g 1410747 798985 470687 63% /users /dev/sd0h 136523 104753 18117 85% /usr host2:/prod 1962592 1607804 158529 91% /prod
The avail column indicates the amount of free space on each file system.
Step 3
Examine the display for a file system containing the required amount of free space. Edit the password file using the following command:
vi /etc/passwd
Step 4
Step 5
Add the following line to define the CONTROL-M/Agent user:

Note
Specify commands exactly as shown below. Modify only information between <triangular brackets>.
<agent_user>::<user_id>:<group_id>:CONTROL-M user:<agent_path>:/bin/csh
where:
<agent_user>
A-8
<agent_path>
Note
For security reasons, it is recommended that you assign a password to the CONTROL-M/Agent user account, using the passwd command. For more information on defining user passwords, refer to your operating system administration guide.
Step 6
(Digital UNIX & Sequent) Check if file /etc/shadow exists. If the file exists, add the same line that was added in Step 5. Specify the following commands to create the directory <agent_path>:
mkdir <agent_path> chown <agent_user> <agent_path>
Step 7
A-9
A-10
Index
Index
A
Agent configuration file description 1-3 Agent directory Agent configuration parameter 1-3 description 1-3 Agent-to-Server port number description 1-3 AIX user account CONTROLM/Agent A-1 CONTROL-M/Agent 1-3 configuration description 1-3 file 1-3 Configuration parameters description 1-3 modifying 2-24 CONTROL-M/Agent description 1-1 functions 1-2 stopping 2-23 Unix user account A-1 CONTROL-M/Agent starting 2-23 uninstall utility 2-20 CTM_SU_PATH 2-22 CTMAGPING utility summary 1-5 CTMCONTB utility 1-5 CTMCREATE utility summary 1-5 CTMFW utility summary 1-5 CTMLOADSET utility summary 1-5 CTMSHOUT utility summary 1-5
B
backslash utility parameters 1-7 backup CONTROL-M/Server host name 1-3
C
communication Agent-to-Server port number 1-3 Communication Diagnostic Report description 2-24 components
Index
D
diagnostic level description 1-4 setting 2-27 Digital Unix user account CONTROLM/Agent A-7
M
mirror host name CONTROL-M/Server 1-3
N
NCR user account CONTROLM/Agent A-6 NonStop-UX user account CONTROLM/Agent A-6
E
ECACTLTB utility summary 1-5 ECAQRTAB utility 1-5 Exit codes CONTROLM scripts 2-33
O
On Statement/Code parameter scripts 2-32 output parameters 1-7
F
functions CONTROL-M/Agent 1-2
P
parameters Agent configuration 1-3 output 1-7 product directory description 1-3 Pyramid user account CONTROLM/Agent A-6
H
HERE documents CONTROL-M scripts 2-33 HP-UX user account CONTROL-M/Agent A-4
I
installation batch procedure 2-11 interactive procedure 2-7
R
Reliant Unix user account CONTROLM/Agent A-6 REXX shell language CONTROL-M scripts 2-30 Run-time environment 2-30
S
scripts exit codes 2-33 HERE documents 2-33 login process 2-30 On Statement/Code parameter 2-32 running under CONTROLM 2-28 run-time environment 2-30 startup process 2-31 working directory 2-31 Sequent user account CONTROL-M/Agent A-7 Server-to-Agent port number description 1-4, 2-18 Shell type CONTROL-M scripts 2-28 SINIX user account CONTROL-M/Agent A-6 Solaris user account CONTROL-M/Agent A-6 starting CONTROL-M scripts 2-31 CONTROL-M/Agent 2-23 stopping CONTROL-M/Agent 2-23 SunOS user account CONTROLM/Agent A-7
HP-UX A-4 NCR A-6 NonStop-UX A-6 Pyramid A-6 Reliant Unix A-6 Sequent A-7 SINIX A-6 Solaris A-6 SunOS A-7 utilities See also individual utilities by name CTMAGPING 1-5 CTMCONTB 1-5 CTMCREATE 1-5 CTMFW 1-5 CTMLOADSET 1-5, 1-6 CTMSHOUT 1-5 directing output 1-7 ECACTLTB 1-5 ECAQRTAB 1-5 invoking from Agent platform 1-4 output parameter 1-7 special formats 1-7 workflow 1-5
W
workflow utility 1-5 Working directory CONTROLM scripts 2-31
T
time between retries 1-4
U
UNIX user account AIX A-1 Digital Unix A-7
Index
Notes
*100039503* *100039503* *100039503* *100039503*

*100039503*

CM Agent Administrator Guide

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

CM Agent Administrator Guide

Caricato da

Copyright:

Formati disponibili

CONTROL-M/Agent for Unix Administrator Guide

September 16, 2001

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

Restricted Rights Legend

Contacting BMC Software

USA and Canada

Outside USA and Canada

Before Contacting BMC Software

CONTROL-M/Agent for Unix

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

About This Book

BMC Software, Inc., Confidential and Proprietary Information

About This Book

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

The following conventions are used in this guide:

Menu => Option

BMC Software, Inc., Confidential and Proprietary Information

About This Book

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M Scheduling Solution

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

Agent Configuration File

BMC Software, Inc., Confidential and Proprietary Information

Server-to-Agent Port Number

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

CONTROL-M/Server Utility Workflow

ctmfw ctmloadset ctmshout ctmcontb ecactltb ecaqrtab

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

Special Utility Parameter Formats

Directing Output From Utilities

BMC Software, Inc., Confidential and Proprietary Information

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

Installation and Administration

BMC Software, Inc., Confidential and Proprietary Information

Installation and Administration

Table 2-1 Media Drive

Defining a CONTROL-M/Agent User

Creating an Entry in the Services Map for NIS

BMC Software, Inc., Confidential and Proprietary Information

CONTROL-M/Agent for Unix

Example ctmagent 7006/tcp #CONTROL-M/Agent

Determining the Search Path (Solaris and AIX Only)

BMC Software, Inc., Confidential and Proprietary Information

Installation and Administration

BMC Software, Inc., Confidential and Proprietary Information