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 LegendU.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHED–RIGHTS 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-2827USA

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 Outside USA and Canada

Address BMC Software, Inc.2101 CityWest Blvd.Houston TX 77042-2827

Telephone

Fax

(01) 713 918 8800

(01) 713 918 8000

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000

http://www.bmc.com

http://www.bmc.com/corporate/offices.html


iv CONTROL-M/Agent for Unix

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

http://www.bmc.com/support.html


Contents v

Contents

Contents

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiRelated Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Chapter 1 General InformationCONTROL-M/Agent Components . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Agent Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Special Utility Parameter Formats . . . . . . . . . . . . . . . . . . . . . . . 1-7

Chapter 2 Installation and AdministrationSystem Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Before Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Defining a CONTROL-M/Agent User . . . . . . . . . . . . . . . . . . . . 2-2Creating an Entry in the Services Map for NIS . . . . . . . . . . . . . 2-2LINUX SU Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Silent Installation of CONTROL-M/Agent . . . . . . . . . . . . . . . . 2-16Uninstalling CONTROL-M/Agent . . . . . . . . . . . . . . . . . . . . . . . 2-20Changes to System Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21CONTROL-M/Agent Configuration Parameters . . . . . . . . . . . . 2-22

Starting/Stopping CONTROL-M/Agent . . . . . . . . . . . . . . . . . . . . . . 2-23Maintaining CONTROL-M/Agent . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23

View or Modify Configuration Parameters . . . . . . . . . . . . . . . . . 2-24Modify Mirror CONTROL-M/Server Host Names . . . . . . . . . . 2-26


vi CONTROL-M/Agent for Unix

View CONTROL-M/Agent Messages . . . . . . . . . . . . . . . . . . . .2-27View CONTROL-M/Agent Logs . . . . . . . . . . . . . . . . . . . . . . . .2-28

Writing Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28Specifying the Shell Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28Support for REXX-Language Scripts . . . . . . . . . . . . . . . . . . . . .2-30Run-Time Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30Scripts and the On Statement/Code Parameter . . . . . . . . . . . . . .2-32Utilization of Exit Codes by CONTROL-M . . . . . . . . . . . . . . . .2-33Use of Reserved Variable $0 . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34

Appendix A Creating a Unix User for CONTROL-M/AgentAIX Agent Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1HP-UX Agent Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4Data General, NCR, NonStop-UX, Pyramid, Reliant UNIX, SINIX

and Solaris Agent Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . A-6Digital UNIX, Sequent and SunOS Agent Platforms . . . . . . . . A-7


Figures vii

Figures

Figures

Figure 1-1 CONTROL-M Scheduling Solution . . . . . . . . . . . . . . . . . . . . . . 1-2Figure 1-2 CONTROL-M/Server Utility Workflow . . . . . . . . . . . . . . . . . . . 1-5


viii CONTROL-M/Agent for Unix


Tables ix

Tables

Tables

Table 1-1 Agent Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . 1-3Table 1-2 CONTROL-M/Agent Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5Table 2-1 Agent for Unix Software Requirements . . . . . . . . . . . . . . . . . . 2-1Table 2-2 Custom Installation Parameters for the Unix Agent . . . . . . . . . 2-13Table 2-3 Configuration – CONTROL-M/Agent for Unix . . . . . . . . . . . . 2-21Table 2-4 Service Definition – CONTROL-M/Agent for Unix. . . . . . . . . 2-21Table 2-5 Unix Agent – Configuration Parameters . . . . . . . . . . . . . . . . . . 2-22Table 2-6 Options of the CONTROL-M Agent Main Menu . . . . . . . . . . . 2-24Table 2-7 Options of the Server Host Names Menu . . . . . . . . . . . . . . . . . 2-27Table 2-8 Shell Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29


x CONTROL-M/Agent for Unix


About This Book xi

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 InformationIntroduces key features and concepts of CONTROL-M/Agent. Describes parameters that must be customized.

Chapter 2 CONTROL-M/Agent for UnixLists requirements for installation of CONTROL-M/Agent under various types of Unix systems. Describes the installation procedure and how to modify configuration parameters.

Appendix A Creating a Unix User for CONTROL-M/AgentDescribes how to define the CONTROL-M/Agent for USS user account.

Index


xii CONTROL-M/Agent for Unix

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.


About This Book xiii

Notational Conventions

The following abbreviations are used in this guide:

The following conventions are used in this guide:

Abbreviation Description

ENTERPRISE/CS Enterprise Controlstation

Convention Description

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

Menu => Option 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.

{Option A|Option B} 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.

[Parameter] Square brackets are used to enclose parameters that are optional.

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

italic An italic font is used for the name of publications.


xiv CONTROL-M/Agent for Unix


General Information 1-1

1

General Information 1

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.


1-2 CONTROL-M/Agent for Unix

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.



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)

Product Directory Location of the CONTROL-M/Agent program.

Agent Directory Location of files used by CONTROL-M/Agent.

CONTROL-M/Server Host Name

Hostname of the computer where the primary CONTROL-M/Server is installed.

Mirror CONTROL-M/Server Host Name

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.

Agent-to-ServerPort Number

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: 7005The second port is specified using parameter Server-to-Agent Port Number (see below).



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.

Server-to-Agent Port Number

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 platform’s 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 Default printer to which job sysout is directed.

Communication Protocol

Protocol used to communicate with CONTROL-M/Server (TCP/IP).

Maximum Retries Maximum number of retries to send messages to CONTROL-M/Server. Default: 12

Timeout Communication timeout (in seconds). Default: 120

Time Between Retries

Time to wait between retries when a timeout occurs (in seconds). Default: 0

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

Table 1-1 Agent Configuration Parameters (Part 2 of 2)



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 Description

ag_ping Verifies that CONTROL-M/Server is active on the Server platform that is connected to the Agent platform.

ctmcreate Creates a job in the Active Jobs file. This utility executes in CONTROL-M/Server.

ctmfw Detects the successful completion of a file transfer activity.

ctmloadset Updates a Quantitative resource in the Resources table. This utility executes in CONTROL-M/Server.

ctmshout Issues a shout message to an indicated destination. This utility executes in CONTROL-M/Server.

ctmcontb Performs operations on the Prerequisite Conditions table. This utility executes in CONTROL-M/Server.

ecactltb Lists the status of each Control resource in the Resources table. This utility executes in CONTROL-M/Server.

ecaqrtab Performs operations on quantitative resources in the Resources table. This utility executes in CONTROL-M/Server.



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.

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



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 (\).

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


Installation and Administration 2-1

2

Installation and Administration 2

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

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

Disk Space 5 MB free disk space in the CONTROL-M/Agent home directory. Additional disk space is required for job sysouts.



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.

NoteFor 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

Media Drive CD-ROM drive. It is recommended that you use a CD-ROM drive on the same platform type as the target installation machine.

Table 2-1 Agent for Unix Software Requirements



Request that your NIS administrator create the following entry in the Services map:

<service_name> <port_number>/<protocol> #CONTROL-M/Agent

where:

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.

<service_name> Recommended value ctmagent.

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



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 6Expecting Return Code = 6: 0 returnedChange 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 drive2. Loading the installation media3. Customizing the installation

Customizing the installation can be performed either interactively or as a batch procedure. A separate description is provided for each method.

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



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 Log in as user root.

Step 2 Create an empty directory for mounting the CD-ROM drive.

Step 3 Connect the CD-ROM drive to the mount directory using the mount command.

NoteThe 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 Log in to the Agent platform as root.

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



Step 4 Specify the following command to begin the installation procedure from the CD-ROM:

/<cd_path>/cd_inst

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

Step 8 The following menu is displayed:

+---------------------------------+| CONTROL-M/Agent Installation |+---------------------------------+

N - New installation of CONTROL-M/AgentU - Upgrade from previous version of CONTROL-M/AgentQ - Quit

Select the required option:



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.

NoteIf you are planning to customize the installation using the non-interactive procedure, enter Q to exit the installation script. Continue with “Non-Interactive 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 in700+0 records outLoad completed successfully or Upgrade completed successfully

Executing ctm/scripts/ag_custom...

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



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/AgentU - Upgrade from previous version of CONTROL-M/AgentQ - 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)



Step 6 Verify that the displayed information is correct, then type y and press <Enter>.

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



Enter the CONTROL-M/Server Host Name: Enter the Backup CONTROL-M/Server Host Name:Enter the Agent-to-Server Port Number: [7005]Enter the Maximum Retries: [5]Enter the Timeout: [60]Enter the Time Between Retries: [0]Enter the Default Printer: [printer]

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



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.

Step 3 Create a tar file in the home directory using the following command:

tar cvf ctmagnt.tar .



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.

Step 6 Log in the Agent platform as root and go to the home directory of the CONTROL-M/Agent.

Step 7 Extract the tar file using the following command:

tar xvf ctmagnt.tar

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



This command allows you to change parameter values without interactive prompts.

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

-A Perform the installation using default parameter values. Mandatory parameter flags -i and -u are must still be specified.

-i Valid values: N for a new installation, U for an upgrade. This flag is mandatory.

-u Unix username for the account in which to install CONTROL-M/Agent. This flag is mandatory.

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

-c Host name of the CONTROL-M Server. This parameter is described in Chapter 1, “General Information”.

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



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)

-a-m-u-n-t-r-d

Agent-to-Server Port NumberMaximum RetriesAgent Unix UsernameAgent Service NameTimeoutTime Between RetriesDefault PrinterThese parameters are described in Chapter 1, “General Information”. Specify a value for any or all these parameters.

-s-p

Server-to-Agent Port NumberProtocolIf 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.

-K Kill process inetd during the installation procedure, instead of refreshing (default). We recommend using the default by not specifying -K.

-h Specify -h to display a list of valid parameters.

Table 2-2 Custom Installation Parameters for the Unix Agent



Step 10 Verify that the displayed information is correct; then specify Y.

NoteNote 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



displayed default value. These parameters are described in Chapter 1, “General Information”.

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



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=FDnnnnWhere 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 (=).

Parameter Description

AGENT_INST= Type of installation:• For a new installation, specify n.• For an upgrade from a previous version of CONTROL-M/Agent

specify u.

AGENT_USER= Name of the CONTROL-M/Agent user account.

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

AGENT_SRV_HOST= Hostname of the computer where the primary CONTROL-M/Server is installed.

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



AGENT_AS_PORT= 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: 7005The second port is specified using parameter Server-to-Agent Port Number (see below).

AGENT_SA_PORT= 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 platform’s 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.

AGENT_COMM_PROT=TCP Communication protocol. (TCP is the only valid value for this parameter.)

AGENT_TIMEOUT= Communication timeout (in seconds).Default: 120

AGENT_TIME_BTW_RETR= 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).

AGENT_MAX_RETR=12 Maximum number of retries to send messages to CONTROL-M/Server. Default: 12

AGENT_DEFLT_PRNT= Name of the default printer.

ICE_ERROR_LOG= Full path name of the log file for messages that are produced by the silent installation.




Sample Input File

The following is a sample input file with the necessary installation parameter:

:fd_value=FD4001

#### n - new, u - upgradeAGENT_INST=n

#### owner of controlm agentAGENT_USER=ctm6test

#### from /etc/servicesAGENT_SERVICE=ctm_agtcp3

#### remote server host nameAGENT_SRV_HOST=fire

#### remote backup server hostAGENT_SRV_BCKP_HOST=fire

#### Agent => Server portAGENT_AS_PORT=5056

#### Server => Agent portAGENT_SA_PORT=7513

#### Communication protocol TCPAGENT_COMM_PROT=TCP

#### Maximum retriesAGENT_MAX_RETR=12

#### TimeoutAGENT_TIMEOUT=120

#### Time between retriesAGENT_TIME_BTW_RETR=0

#### Default printer



AGENT_DEFLT_PRNT=lpr

# definitions for working in silent mode

# log file for messages in silent modeICE_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.



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.

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-3 Configuration – CONTROL-M/Agent for Unix

<service> Agent service-name specified during installation. Default: ctmagent .

<socket_type> Socket type used for the service (dgram for udp; stream for tcp).

<protocol> Protocol used for communication between the Server platform and the Agent platform (udp or tcp ).

<agent_exe> Path of CONTROL-M/Agent executable files.

<agent_home> Path of CONTROL-M/Agent user home directory.

Table 2-4 Service Definition – CONTROL-M/Agent for Unix

<service> Agent service-name specified during installation. Default: ctmagent .



3. [AIX]: The following lines are added to file /etc/rc.nfs:

#Refresh the inetd processrefresh -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.

<protocol> Protocol used for communication between the Server platform and the Agent platform (udp or tcp).

<port_number> Value specified for parameter Server-to-Agent Port Number.

Table 2-5 Unix Agent – Configuration Parameters


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

Table 2-4 Service Definition – CONTROL-M/Agent for Unix



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

Step 2 Specify command: ag_menu

The following menu is displayed:



CONTROL-M/Agent Main Menu-------------------------Select one of the following options:

1 - Configuration Parameters2 - 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.

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

Table 2-6 Options of the CONTROL-M Agent Main Menu

Configuration Parameters

View or modify CONTROL-M/Agent configuration parameters (described below).

Communication Diagnostic Report

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.

Quit Exit to the shell prompt.



1) CONTROL-M/Server Host Name:brigit2) Agent-to-Server Port Number: 7005Server-to-Agent Port Number: 7503Communication Protocol: TCP3) Mirror CONTROL-M/Server Host Names:aristo diana4) Default Printer: lpr5) Maximum Retries: 106) Timeout: 707) Time Between Retries: 58) Diagnostic Level (0-4): 09) Communication Trace 0Q) 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



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.

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

NoteThe primary host name must be included in the list of authorized host names.

Authorized Mirror CONTROL-M/Server Host Name----------------------------------

1) Add new Host Name:2) Delete Host Name: [brigit diana]

Q) Quit

Enter item number you wish to change:

The options available from this menu are described in Table 2-7.



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

NoteAfter generating messages for diagnosis, the value of the Diagnostic Level parameter should be reset to 0.

Table 2-7 Options of the Server Host Names Menu

Add new Host Name

Add a backup CONTROL-M/Server host name to the Mirror CONTROL-M/Server file.

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

Quit Exit to the Configuration Parameters menu.



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-M’s 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 script’s syntax before running the script under CONTROL-M.

NoteCommand type jobs must be in Bourne shell syntax only.

Specifying the Shell Type

To enable CONTROL-M to recognize the script’s shell type, specify the first line of the script as follows:



#! <shell path>

where <shell path> is taken from Table 2-8.

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

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

Table 2-8 Shell Paths

Shell Type Shell Path Default Switch Other Switches

Bourne /bin/sh -x -v

csh /bin/csh -v

tush /bin/tcsh -v

Korn /bin/ksh -x -v



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 job’s owner (i.e., the user specified in the job’s 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>



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 job’s owner is executed as part of the startup process for the script.

• For all other shell types, the .profile file of the job’s 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 job’s 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 job’s owner.



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 StatementDepending 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 LinesCONTROL-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 StatementCONTROL-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.



• HERE DocumentsThe 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_EOFline 1line 2EOF_EOFecho "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.

ExampleAssuming 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



Use of Reserved Variable $0

The reserved variable $0 can be used in a script to retrieve information regarding the script’s 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.

ExampleThe following (script a and sub-script b) demonstrates valid usage of variables $0 and $CTM0 in scripts running under CONTROL-M:

Script a#! /bin/shecho $0. b

Sub-script bmemname=‘basename $CTM0‘memlib=‘dirname $CTM0‘...


Creating a Unix User for CONTROL-M/Agent A-1

A

Creating a Unix User for CONTROL-M/Agent A

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-2 CONTROL-M/Agent for Unix

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

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 Select the OK button and wait for the operation to complete.

Step 5 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/infodiana: /prod 1962592 131488 93% — — /prod



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.

Step 8 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 controlmHOME directory <agent_path>Initial PROGRAM /bin/csh or /bin/tcsh

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 Click the OK button and wait for the operation to complete.

Step 10 Select the Exit smit option from the pull-down menu.

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



HP-UX Agent Platform



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% /usrhost1:/ 926640 778035 55941 93% /hp/homehost2:/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.

Step 4 Use sam to define both the group controlm and the CONTROL-M/Agent user as follows:

4.A Select Users and Groups => Groups => Actions => Add from the menu.

4.B Set the Group Name parameter as follows:

Group NAME controlm

4.C Click OK and wait for the operation to complete.



4.D Select File Exit to return to the Users and Groups menu.

4.E 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... controlmStartup Program /bin/csh or /bin/tsch

where:



4.F Click OK and wait for the operation to complete.

4.G Select File => Exit.

4.H Select Previous Level to go back to the main menu.

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



Data General, NCR, NonStop-UX, Pyramid, Reliant UNIX, SINIX and Solaris Agent Platforms



Step 2 Specify the following command to create the group controlm:

groupadd controlm

NoteSpecify 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% /usrhost2:/prod 1962592 1607804 158529 91% /prod

The avail column indicates the amount of free space on each file system.


Step 5 Specify the following command to create the CONTROL-M/Agent user:



useradd -g controlm -s /bin/csh -d <agent_path> <agent_user>

where:



NoteFor 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



Step 2 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:



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% /usrhost2:/prod 1962592 1607804 158529 91% /prod

The avail column indicates the amount of free space on each file system.


Step 4 Edit the password file using the following command:

vi /etc/passwd

Step 5 Add the following line to define the CONTROL-M/Agent user:

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





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

Step 7 Specify the following commands to create the directory <agent_path>:

mkdir <agent_path>chown <agent_user> <agent_path>


Index 1

Index

Index

AAgent configuration file

description 1-3Agent directory

Agent configuration parameter 1-3description 1-3

Agent-to-Server port numberdescription 1-3

AIX user accountCONTROLM/Agent A-1

Bbackslash

utility parameters 1-7backup

CONTROL-M/Server host name 1-3

Ccommunication

Agent-to-Server port number 1-3Communication Diagnostic Report

description 2-24components

CONTROL-M/Agent 1-3configuration

description 1-3file 1-3

Configuration parametersdescription 1-3modifying 2-24

CONTROL-M/Agentdescription 1-1functions 1-2stopping 2-23Unix user account A-1

CONTROL-M/Agentstarting 2-23uninstall utility 2-20

CTM_SU_PATH 2-22CTMAGPING utility

summary 1-5CTMCONTB utility 1-5CTMCREATE utility

summary 1-5CTMFW utility

summary 1-5CTMLOADSET utility

summary 1-5CTMSHOUT utility

summary 1-5


2 CONTROL-M/Agent for Unix

Ddiagnostic level

description 1-4setting 2-27

Digital Unix user accountCONTROLM/Agent A-7

EECACTLTB utility

summary 1-5ECAQRTAB utility 1-5Exit codes

CONTROLM scripts 2-33

Ffunctions

CONTROL-M/Agent 1-2

HHERE documents

CONTROL-M scripts 2-33HP-UX user account

CONTROL-M/Agent A-4

Iinstallation

batch procedure 2-11interactive procedure 2-7

Mmirror host name

CONTROL-M/Server 1-3

NNCR user account

CONTROLM/Agent A-6NonStop-UX user account

CONTROLM/Agent A-6

OOn Statement/Code parameter

scripts 2-32output parameters 1-7

Pparameters

Agent configuration 1-3output 1-7

product directorydescription 1-3

Pyramid user accountCONTROLM/Agent A-6

RReliant Unix user account

CONTROLM/Agent A-6REXX shell language

CONTROL-M scripts 2-30Run-time environment 2-30


Index 3

Sscripts

exit codes 2-33HERE documents 2-33login process 2-30On Statement/Code parameter 2-32running under CONTROLM 2-28run-time environment 2-30startup process 2-31working directory 2-31

Sequent user accountCONTROL-M/Agent A-7

Server-to-Agent port numberdescription 1-4, 2-18

Shell typeCONTROL-M scripts 2-28

SINIX user accountCONTROL-M/Agent A-6

Solaris user accountCONTROL-M/Agent A-6

startingCONTROL-M scripts 2-31CONTROL-M/Agent 2-23

stoppingCONTROL-M/Agent 2-23

SunOS user accountCONTROLM/Agent A-7

Ttime between retries 1-4

UUNIX user account

AIX A-1Digital Unix A-7

HP-UX A-4NCR A-6NonStop-UX A-6Pyramid A-6Reliant Unix A-6Sequent A-7SINIX A-6Solaris A-6SunOS A-7

utilitiesSee also individual utilities by nameCTMAGPING 1-5CTMCONTB 1-5CTMCREATE 1-5CTMFW 1-5CTMLOADSET 1-5, 1-6CTMSHOUT 1-5directing output 1-7ECACTLTB 1-5ECAQRTAB 1-5invoking from Agent platform 1-4output parameter 1-7special formats 1-7workflow 1-5

Wworkflow

utility 1-5Working directory

CONTROLM scripts 2-31


4 CONTROL-M/Agent for Unix

*100039503**100039503**100039503**100039503*

*100039503*