CA Workload Automation

Agent for Databases

Implementation Guide
r11.3.4
This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to
as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This
Documentation is proprietary information of CA and may not be copied, transferred, reproduced, disclosed, modified or
duplicated, in whole or in part, without the prior written consent of CA.
If you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make
available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with
that software, provided that all CA copyright notices and legends are affixed to each reproduced copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable
license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to
certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY
KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE,
DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST
INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE
POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and such
license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is CA.
Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions
set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or
their successors.
Copyright © 2014 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to
their respective companies.
CA Technologies Product References
This document references the following CA Technologies products:
■ CA Process Automation
■ CA Workload Automation AE
■ CA Workload Automation Agent for Application Services (CA WA Agent for
Application Services)
■ CA Workload Automation Agent for Databases (CA WA Agent for Databases)
■ CA Workload Automation Agent for i5/OS (CA WA Agent for i5/OS)
■ CA Workload Automation Agent for Informatica (CA WA Agent for Informatica)
■ CA Workload Automation Agent for Linux (CA WA Agent for Linux)
■ CA Workload Automation Agent for Micro Focus (CA WA Agent for Micro Focus)
■ CA Workload Automation Agent for Microsoft SQL Server (CA WA Agent for
Microsoft SQL Server)
■ CA Workload Automation Agent for Oracle E-Business Suite (CA WA Agent for
Oracle E-Business Suite)
■ CA Workload Automation Agent for PeopleSoft (CA WA Agent for PeopleSoft)
■ CA Workload Automation Agent for Remote Execution (CA WA Agent for Remote
Execution)
■ CA Workload Automation Agent for SAP (CA WA Agent for SAP)
■ CA Workload Automation Agent for UNIX (CA WA Agent for UNIX)
■ CA Workload Automation Agent for Web Services (CA WA Agent for Web Services)
■ CA Workload Automation Agent for Windows (CA WA Agent for Windows)
■ CA Workload Automation CA 7 Edition
■ CA Workload Automation DE
■ CA Workload Automation Desktop Client (CA WA Desktop Client)
■ CA Workload Automation ESP Edition
■ CA Workload Control Center
Contact CA Technologies
Contact CA Support

For your convenience, CA Technologies provides one site where you can access the
information that you need for your Home Office, Small Business, and Enterprise CA
Technologies products. At http://ca.com/support, you can access the following
resources:
■ Online and telephone contact information for technical assistance and customer
services
■ Information about user communities and forums
■ Product and documentation downloads
■ CA Support policies and guidelines
■ Other helpful resources appropriate for your product

Providing Feedback About Product Documentation

If you have comments or questions about CA Technologies product documentation, you

can send a message to [email protected].

To provide feedback about CA Technologies product documentation, complete our

short customer survey which is available on the CA Support website at
http://ca.com/docs.
Contents
Chapter 1: Introduction 7
Intended Audience ....................................................................................................................................................... 7
Agents and Agent Plug-ins ........................................................................................................................................... 7
CA WA Agent for Databases ......................................................................................................................................... 8
Job Types Supported by CA WA Agent for Databases .................................................................................................. 9

Chapter 2: Implementation Checklist 11

How to Install and Configure CA WA Agent for Databases ........................................................................................ 11
Collecting Your Database Information ....................................................................................................................... 11
Deciding Whether to Create an Alias ......................................................................................................................... 12

Chapter 3: Installing the Agent Plug-in 13

CA WA Agent for Databases Installation Options ...................................................................................................... 13
Controlling the Agent Plug-in ..................................................................................................................................... 14
Install CA WA Agent for Databases ............................................................................................................................ 14
Download the jTDS JDBC Driver ................................................................................................................................. 16
Copy the JDBC Drivers for Sybase .............................................................................................................................. 16
How to Remove the Agent Plug-in ............................................................................................................................. 17
Disable CA WA Agent for Databases ................................................................................................................... 17
Remove the Agent Plug-in from the Scheduling Manager .................................................................................. 19

Chapter 4: Your Scheduling Manager and the Agent Plug-in 21

Configuring the Scheduling Manager to Work with the Agent Plug-in ...................................................................... 21
Running a Verification Test ........................................................................................................................................ 21

Chapter 5: Configuring the Agent Plug-in 23

How to Configure Agent Parameters ......................................................................................................................... 23
Configure Agent Parameters on the Agent ......................................................................................................... 24
Configure Agent Parameters on the Scheduling Manager.................................................................................. 24
CA WA Agent for Databases Parameters in the agentparm.txt File ........................................................................... 25
How to Set Up an Alias for the Agent Plug-in............................................................................................................. 30
Create an Alias for the Agent Plug-in .................................................................................................................. 31
Configuring an Alias on the Scheduling Manager ............................................................................................... 31
Change the JDBC Driver the Agent Plug-in Uses for your Database........................................................................... 31
Locating the JDBC Driver for your Database ....................................................................................................... 32

Contents 5
Change the Number of Simultaneously Open Database Connections ....................................................................... 33
Specify a Default Database URL ................................................................................................................................. 34
Connecting to Oracle Real Application Clusters (RAC) ........................................................................................ 35
How to Change the Default Database User ID and Password .................................................................................... 35
Encrypt the Password ......................................................................................................................................... 36
Change the Default Database User and Password .............................................................................................. 36
Specify a Default Oracle User Role for Database Jobs ............................................................................................... 37
Change the Frequency the Agent Plug-in Monitors for Changes to the Database .................................................... 37
Enable Automatic Spool File Cleanup......................................................................................................................... 37
Configure the Agent Plug-in to Retry Running a Stored Procedure ........................................................................... 38

Chapter 6: Troubleshooting the Agent Plug-in 39

Problem Connecting to Oracle Real Application Clusters (RAC) ................................................................................ 39

Chapter 7: Related Documentation 41

CA Workload Automation AE Documentation ........................................................................................................... 41
CA Workload Automation DE Documentation ........................................................................................................... 42
CA Workload Automation ESP Edition Documentation ............................................................................................. 42
CA Workload Automation CA 7 Edition Documentation ............................................................................................ 43

Index 45

6 Implementation Guide
Chapter 1: Introduction
This section contains the following topics:
Intended Audience (see page 7)
Agents and Agent Plug-ins (see page 7)
CA WA Agent for Databases (see page 8)
Job Types Supported by CA WA Agent for Databases (see page 9)

Intended Audience
This document is for system administrators who are responsible for upgrading,
installing, and configuring agents.

You require knowledge of the operating system where the agent is installed and any
third-party products or software technology that the agent uses.

Notes:
■ The term Windows refers to any Microsoft Windows operating system supported by
the agent.
■ The UNIX instructions in this document also apply to Linux systems unless otherwise
noted.

Agents and Agent Plug-ins

Agents are the key integration components of CA Technologies workload automation
products. Agents let you automate, monitor, and manage workload on all major
platforms, applications, and databases. To run workload on a particular system, you
install an agent on that system. If your workload must run on a UNIX computer, for
example, you can install and configure the CA WA Agent for UNIX. The agent can run
UNIX scripts, execute UNIX commands, transfer files using FTP, monitor file activity on
the agent computer, and perform many other tasks.

You can extend the functionality of the agent by installing one or more agent plug-ins in
the agent installation directory. If you have a relational database such as Oracle, you can
install a database agent plug-in to query and monitor the database. Other agent plug-ins
are also available. For more information about agent plug-ins, see the Implementation
Guide for the appropriate agent plug-in.

Note: The agent plug-ins are only available for UNIX, Linux, and Windows operating
environments.

Chapter 1: Introduction 7
CA WA Agent for Databases

Example: Workload with Different Types of Jobs

The following workload contains z/OS jobs, a UNIX job, an SAP job, and a Windows job,
running on different computers, in different locations, and at different times:

CA WA Agent for Databases

The CA WA Agent for Databases lets a user perform the following tasks:
■ Execute SQL queries against a relational database
■ Run stored procedures that are contained in a relational database
■ Monitor a relational database for changes to a table

Note: You can schedule jobs for Oracle, Microsoft SQL Server, IBM DB2, and Sybase
databases.

8 Implementation Guide
 Job Types Supported by CA WA Agent for Databases

Job Types Supported by CA WA Agent for Databases

With the CA WA Agent for Databases, you can define and run the following types of
jobs:
SQL
Lets you execute an SQL statement.
Database Stored Procedure
Lets you run a stored procedure.
Database Trigger
Lets you monitor for added, deleted, and updated rows in a database table.
Database Monitor
Lets you monitor for an increase or decrease in the number of rows in a database
table.

Chapter 1: Introduction 9
Chapter 2: Implementation Checklist
This section contains the following topics:
How to Install and Configure CA WA Agent for Databases (see page 11)
Collecting Your Database Information (see page 11)
Deciding Whether to Create an Alias (see page 12)

How to Install and Configure CA WA Agent for Databases

CA WA Agent for Databases is an agent plug-in that installs into the CA WA Agent for
UNIX, Linux, or Windows installation directory.

Note: Before you install the agent plug-in, install and configure the agent.

To install and configure the agent plug-in, follow these steps:

1. Review the system requirements in the CA Workload Automation Agent for
Databases Release Notes.
2. Collect your database information (see page 11).
3. Decide whether to create an alias (see page 12).
4. Review the agent plug-in installation options (see page 13).
5. Install the agent plug-in (see page 14).
6. (Microsoft SQL Server only) Download the jTDS JDBC driver (see page 16).
7. (Sybase only) Copy the JDBC drivers (see page 16).
8. Configure the scheduling manager to work with the agent plug-in (see page 21).
9. (Optional) Run a verification test (see page 21).
10. (Optional) Configure the agent plug-in (see page 23).

Collecting Your Database Information

During the agent plug-in installation, you are prompted for information about your
database. Speak to your database administrator and collect the following information:

Information Your Value

Type of database you are using (Oracle,

SQL Server, DB2, or Sybase)

Chapter 2: Implementation Checklist 11

Deciding Whether to Create an Alias

Information Your Value

Address of the computer where your

database is installed
Database listener port
System identifier (SID) for an Oracle
database or database name for an SQL
Server, DB2, or Sybase database
User ID and password of a user who has
access to the database

Deciding Whether to Create an Alias

You install an agent plug-in into the agent installation directory to extend the core
functionality of the agent. By default, the agent plug-in operates under the same agent
name that is assigned to the agent. An alias lets you create a unique agent name for an
agent plug-in, which is useful for controlling agent security or for setting up clustered
environments. The installation program generates the alias by adding a suffix to the
agent name.

Note: If you are installing the agent plug-in to work with CA Workload Automation DE,
you must set up an alias. Setting up an alias for use with other scheduling managers is
optional.

Suppose you have installed an agent named AGT10 on a Linux computer. Users who
have access to that agent through their security permissions specify AGT10 as the agent
name in their job definitions. Now suppose that you install an agent plug-in into the
installation directory for AGT10. You can create an alias for the agent plug-in, for
example, AGT10_DB. You can then restrict access to that alias to only those users that
run Database workload. Those specific users then must specify AGT10_DB as the agent
name in their job definitions.

Each agent plug-in has a default alias that you can enable during installation. For
example, the agent plug-in for CA WA Agent for Databases has the default alias
agentname_DB. You can enable or change the default alias name after installation. To
work, you must also configure the alias on the scheduling manager.

Note: To configure agent aliasing for clustered environments, see the CA Workload
Automation Agent for UNIX, Linux, or Windows Implementation Guide.

12 Implementation Guide
Chapter 3: Installing the Agent Plug-in
This section contains the following topics:
CA WA Agent for Databases Installation Options (see page 13)
Controlling the Agent Plug-in (see page 14)
Install CA WA Agent for Databases (see page 14)
Download the jTDS JDBC Driver (see page 16)
Copy the JDBC Drivers for Sybase (see page 16)
How to Remove the Agent Plug-in (see page 17)

CA WA Agent for Databases Installation Options

The CA WA Agent for Databases interactive installation program prompts you for the
following information:
Database type
Specifies the type of database you want to use with the agent plug-in. Choose from
one of the following types:
■ Oracle
■ SQL Server
■ DB2
■ Sybase
Database host
Specifies the address of the computer where your database is installed.
Database port
Specifies the database listener port.
Database SID (applies to Oracle)
Specifies the system identifier (SID) of the Oracle instance.
Database name (applies to DB2, SQL Server, and Sybase)
Specifies the name of the database.

Default database user ID

Specifies the user who has access to the database.
Default database user password
Specifies the password corresponding to the default database user ID.

Chapter 3: Installing the Agent Plug-in 13

Controlling the Agent Plug-in

Do you want to set up the alias?

Sets whether the default alias is enabled for the agent plug-in.
Y
Enables the default alias.
N
Disables the default alias.
Default: Y
Note: The default alias for CA WA Agent for Databases is agentname_DB.

Controlling the Agent Plug-in

You control the agent plug-in using the agent where the plug-in is installed. Depending
on your operating system, you have several options for starting or stopping the agent.
On UNIX, issue a command to run a start or stop script. On Windows, start or stop the
agent as a Windows service.

Note: For more information about starting and stopping the agent, see the CA Workload
Automation Agent for UNIX, Linux, or Windows Implementation Guide.

Install CA WA Agent for Databases

You can install the agent plug-in using an interactive program that prompts you for the
required information.

Follow these steps:

Copy the database.pak file into the agent installation directory. You can copy this file
from the product DVD or you can download a zip file that contains the file from the CA
Support Online website (http://ca.com/support).
1. Change to the agent installation directory. For example, type the following
command:
■ On UNIX:
cd opt/CA/WA_Agent_R11_3

■ On Windows:
cd C:\Program Files\CA\WA Agent R11.3

14 Implementation Guide
 Install CA WA Agent for Databases

2. Stop the agent using one of the following commands:

■ On UNIX:
./cybAgent -s

■ On Windows:
cybAgent -s

3. Start the installation program using one of the following commands:

■ On UNIX:
./PluginInstaller database.pak install_dir

■ On Windows:
PluginInstaller.exe database.pak install_dir

install_dir
Specifies the agent installation directory.
4. Enter the information the installation program prompts you for.
The installation program displays a message and closes automatically upon a
successful installation.
5. Start the agent using one of the following commands:
■ On UNIX:
./cybAgent &

■ On Windows:
cybAgent -a

Note: The installation program backs up all modified and replaced files. The backup files
are compressed into a file that is named backup_timestamp.zip, located in the backups
subdirectory of the agent installation directory. You can use Winzip or other similar
utilities to open the backup file. A backup copy of the agentparm.txt file is stored in the
zip file.

Chapter 3: Installing the Agent Plug-in 15

Download the jTDS JDBC Driver

Download the jTDS JDBC Driver

Due to a license restriction, manually download the jTDS JDBC driver and copy it into the
agent installation directory before you can complete the installation.

Note: This procedure applies only to Microsoft SQL Server databases.

Follow these steps:

1. Open your browser and go to the following web page:
http://sourceforge.net/projects/jtds/files/jtds/1.2.6/jtds-1.2.6-dist.zip/dow
nload

2. Download and unzip the jtds-1.2.6-dist.zip file to the agent computer.

3. Copy the jtds-1.2.6.jar file into the following location:
install_dir\jars\ext

install_dir
Specifies the agent installation directory.
4. Start the agent using the following command:
cybAgent -a

Copy the JDBC Drivers for Sybase

To complete the installation for Sybase, manually copy the JDBC drivers to the agent
installation directory.

Follow these steps:

1. Locate the JDBC drivers in the Sybase database installation directory, for example:
■ On UNIX:
database_install_dir/jConnect-version/devclasses

■ On Windows:
C:\database_install_dir\jConnect-version\devclasses

The agent was tested with the jconn3d.jar and jTDS3d.jar drivers.
2. Copy the JDBC drivers for your database to the jars/ext subdirectory of the agent
installation directory.
3. Change to the agent installation directory.

16 Implementation Guide
 How to Remove the Agent Plug-in

4. Stop the agent using one of the following commands:

■ On UNIX:
./cybAgent -s

■ On Windows:
cybAgent -s

5. Open the agentparm.txt file that is located in the agent installation directory.
6. Edit the following parameter if the driver class name for your database driver is
different:
jdbc.drivers
Specifies the driver class name for the JDBC driver. Separate multiple drivers
with a colon (:).
Example: sun.jdbc.odbc.JdbcOdbcDriver:com.sybase.jdbc3.jdbc.SybDriver
7. Save and close the agentparm.txt file.
8. Start the agent using one of the following commands:
■ On UNIX:
./cybAgent &

■ On Windows:
cybAgent -a

How to Remove the Agent Plug-in

You can remove an agent plug-in when you no longer require it.

To remove the agent plug-in, follow these steps:

1. Disable the agent plug-in (see page 17).
2. (Optional) Remove the agent plug-in from the scheduling manager (see page 19).

Disable CA WA Agent for Databases

Use this procedure when you want to remove CA WA Agent for Databases from your
system.

Follow these steps:

1. Verify that all workload is complete.
2. Stop the agent.

Chapter 3: Installing the Agent Plug-in 17

How to Remove the Agent Plug-in

3. Open the agentparm.txt file that is located in the agent installation directory.
4. Comment out the plugins.start_internal_n parameter, and renumber any
subsequent plugins.start_internal_n parameters.
Note: Renumber all other agent plug-ins that are assigned a greater number than
the agent plug-in you are uninstalling.
5. Comment out the communication.alias parameter if you created an alias during the
agent plug-in installation.
Note: Renumber any subsequent communication.alias_n parameters.
6. Save and close the agentparm.txt file.
7. Remove the database.jar file from the JARs subdirectory of the agent installation
directory.
8. Start the agent.

Example: Renumber the plugins.start_internal_n Parameter

Suppose that you have the following agent plug-ins set in the agentparm.txt file:

plugins.start_internal_1=runner
plugins.start_internal_2=database
plugins.start_internal_3=ftp
plugins.start_internal_4=microfocus

To disable the agent plug-in for CA WA Agent for Databases, you would modify the
agentparm.txt file as follows:

plugins.start_internal_1=runner
#plugins.start_internal_2=database
plugins.start_internal_2=ftp
plugins.start_internal_3=microfocus

Example: Renumber the communication.alias_n Parameter

Suppose that you have two alias agent plug-ins. The agentparm.txt file has the following
parameters:

communication.alias_1=AGENTNAME_DB
communication.alias_2=AGENTNAME_MF

To disable the agent plug-in for CA WA Agent for Databases, modify the agentparm.txt
file as follows:

#communication.alias_1=AGENTNAME_DB
communication.alias_1=AGENTNAME_MF

18 Implementation Guide
 How to Remove the Agent Plug-in

Remove the Agent Plug-in from the Scheduling Manager

In addition to disabling the agent plug-in, you can remove it from the configuration on
the scheduling manager.

Note: For detailed instructions to remove the agent from the scheduling manager, see
the documentation for your scheduling manager.

Chapter 3: Installing the Agent Plug-in 19

Chapter 4: Your Scheduling Manager and
the Agent Plug-in
This section contains the following topics:
Configuring the Scheduling Manager to Work with the Agent Plug-in (see page 21)
Running a Verification Test (see page 21)

Configuring the Scheduling Manager to Work with the Agent

Plug-in
If you have defined the following items for the agent plug-in, configure the items on the
scheduling manager:
■ An alias
■ A user

For detailed configuration instructions, see the documentation for your scheduling
manager.

Running a Verification Test

For your verification test, you define and run an SQL job. To define the job, you require
the following information:
Agent name
Specifies the name of your agent or the alias for the agent plug-in if you created an
alias.
SQL
Specifies the SQL statement to run.

Chapter 4: Your Scheduling Manager and the Agent Plug-in 21

Running a Verification Test

Output file
Specifies the valid path to a file where you want the agent to store the query
results.
User
Specifies the user ID to run the job under.
Note: You do not need to include the USER statement if a default user ID is
specified in the agentparm.txt file.

For more information about defining an SQL job, see the documentation for your
scheduling manager.

22 Implementation Guide
Chapter 5: Configuring the Agent Plug-in
This section contains the following topics:
How to Configure Agent Parameters (see page 23)
CA WA Agent for Databases Parameters in the agentparm.txt File (see page 25)
How to Set Up an Alias for the Agent Plug-in (see page 30)
Change the JDBC Driver the Agent Plug-in Uses for your Database (see page 31)
Change the Number of Simultaneously Open Database Connections (see page 33)
Specify a Default Database URL (see page 34)
How to Change the Default Database User ID and Password (see page 35)
Specify a Default Oracle User Role for Database Jobs (see page 37)
Change the Frequency the Agent Plug-in Monitors for Changes to the Database (see
page 37)
Enable Automatic Spool File Cleanup (see page 37)
Configure the Agent Plug-in to Retry Running a Stored Procedure (see page 38)

How to Configure Agent Parameters

You configure agent parameters by editing the agentparm.txt file, which is located in the
agent installation directory. When you install the agent, the installation program adds
frequently configured agent parameters to the file. Other agent parameters exist, which
you must manually add to the agentparm.txt file to configure the agent. For any
configuration changes to take effect, always stop and restart the agent. For some agent
parameters, such as the agent name and communication parameters, also configure the
parameters on the scheduling manager.

To configure agent parameters, do the following steps:

1. Configure agent parameters on the agent (see page 24).
2. Configure agent parameters on the scheduling manager (see page 24).

Chapter 5: Configuring the Agent Plug-in 23

How to Configure Agent Parameters

Configure Agent Parameters on the Agent

Configure agent parameters on CA WA Agent for UNIX, Linux, or Windows using the
following procedure.

Follow these steps:

1. Change to the agent installation directory.
2. Stop the agent using one of the following commands:
■ On UNIX:
./cybAgent -s

■ On Windows:
cybAgent -s

3. Open the agentparm.txt file that is located in the agent installation directory.
4. Make the required changes to the agent parameters.
5. Save and close the agentparm.txt file.
6. Start the agent using one of the following commands:
■ On UNIX:
./cybAgent &

■ On Windows:
cybAgent -a

Configure Agent Parameters on the Scheduling Manager

When you change an agent parameter in the agentparm.txt file that is also defined on
the scheduling manager, such as the agent name, configure the agent parameter on the
scheduling manager.

Note: For detailed instructions to configure agent parameters on the scheduling

manager, see the documentation for your scheduling manager.

24 Implementation Guide
 CA WA Agent for Databases Parameters in the agentparm.txt File

CA WA Agent for Databases Parameters in the agentparm.txt

File
You can configure the following parameters in the agentparm.txt file. The file is located
in the agent installation directory. You can open the agentparm.txt file in any standard
text editor.
agent.spool.success.autocleanup
Sets whether the agent automatically clears spool files.
true
Enables automatic spool file cleanup.
false
Disables automatic spool file cleanup.
Default: false
communication.alias_n
Defines the alias name for the agent. The n suffix increments sequentially for each
alias agent.
Note: To enable an alias on the agent, verify that the comment character (#) is
removed from the parameter line.
Default: agentname_DB
db.conn.timeOut.sec
Specifies the maximum number of seconds that a driver waits while attempting to
connect to a database. If the driver cannot make a connection to the database
during the timeout period, the job fails. The purpose of the parameter is to prevent
unnecessary delays for the subsequent jobs in the queue trying to connect to other
databases.
Default: 30 seconds
db.connect.separateThread
Specifies whether the agent connects to the database on a separate thread.
true
Connects to the database on a separate thread. If you use DB2 with an HP-UX
agent, this setting is required. If you use another database with an HP-UX
agent, this setting is recommended.
false
Does not connect to the database on a separate thread.
Default: false

Chapter 5: Configuring the Agent Plug-in 25

CA WA Agent for Databases Parameters in the agentparm.txt File

db.connect.setTrace
Specifies whether the agent turns on tracing for the database driver.
true
Turns on tracing for the database driver. With this setting, the agent generates
the jdbc.log file.
false
Does not turn on tracing for the database driver.
Default: false
db.connectionPool.maxSize
Specifies the maximum number of simultaneously open connections in a database
pool.
Limits: 0-20
Default: 5
Note: If you set it to zero, the agent does not use a connection pool.
db.dbproc.retryOnFailure
Specifies whether the agent continues to resend a stored procedure when an error
occurs between the agent and the database. The error is logged in the agent log
file.
true
Indicates that the agent retries running a stored procedure when an error
occurs.
false
Indicates that the agent attempts to run a stored procedure only once.
Default: false
db.dbproc.trimValues
Specifies whether the agent trims string values that a stored procedure returns.
true
Removes surrounding spaces from strings that a stored procedure returns. For
example, you can use this setting to trim string values in DB2 that are padded
with spaces.
false
Does not remove surrounding spaces from strings that a stored procedure
returns.
Default: false

26 Implementation Guide
 CA WA Agent for Databases Parameters in the agentparm.txt File

db.default.password
Specifies the encrypted password for the default database user ID.
Note: This parameter does not apply to CA Workload Automation AE.
db.default.url
Specifies the default database URL, which includes the database host name and
port. When you specify the default location, you use a unique URL format for each
database type. Default database URL specifications are formatted as follows:
■ Oracle database:
jdbc:oracle:thin:@host:port:dbname

Example: jdbc:oracle:thin:@gemini:1527:cyb
■ Oracle Real Application Clusters (RAC)
Example: jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)
(ADDRESS=(PROTOCOL=TCP)(HOST=host1) (PORT=1521))
(ADDRESS=(PROTOCOL=TCP)(HOST=host2) (PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=service)))
■ Microsoft SQL Server database:
db.default.url=jdbc:sqlserver://host:port;DatabaseName=dbname

Example: jdbc:sqlserver://qatest04:1433;DatabaseName=JAT50
■ IBM DB2 database:
db.default.url=jdbc:db2://host:port/dbname

Example: jdbc:db2://sapent:50000/SAMPLE
■ Sybase database:
db.default.url=jdbc:sybase:Tds:host:port/dbname

Example: jdbc:sybase:Tds:dbhost:5000/tsdata
Note: The URL specified in a job definition overrides this value.
db.default.user
Specifies the default database user ID that is used to monitor the table. Specify the
encrypted password for this user ID using the db.default.password parameter.
Notes:
■ If another user ID is specified in the job definition, the user ID in the job
definition overrides this default user ID.
■ This parameter does not apply to CA Workload Automation AE.

Chapter 5: Configuring the Agent Plug-in 27

CA WA Agent for Databases Parameters in the agentparm.txt File

db.default.userType
Specifies the role of the Oracle user to log in as. The user role must be defined in
the Oracle database.
Example: as sysdba
db.error.connectionErrorMessage
Specifies the SQLException that the agent uses to determine whether a connection
failure has occurred. On a connection failure, the agent retries running the job.
Default: java.sql.SQLException: Io exception
db.mon.disable
Specifies whether the agent disables the Database Monitor feature.
true
Disables the Database Monitor feature. If you do not use Database Monitor
jobs, use this setting to reduce resource usage, setup, and potential error
messages.
false
Enables the Database Monitor feature.
Default: false
db.out.format.paramSeparator
Specifies the separator that the agent uses between key value pairs in the return
strings.
Default: |
db.out.format.valueSeparator
Specifies the separator that the agent uses between keys and values in the return
strings.
Default: =

db.sql.retryOnFailure
Specifies whether the agent retries the SQL execution when failure occurs.
true
Indicates that the agent retries the SQL execution once when failure occurs.
false
Indicates that the agent attempts the SQL execution only once.
Default: false

28 Implementation Guide
 CA WA Agent for Databases Parameters in the agentparm.txt File

db.trig.disable
Specifies whether the agent disables the Database Trigger feature.
true
Disables the Database Trigger feature. If you do not use Database Trigger jobs,
use this setting to reduce resource usage, setup, and potential error messages.
false
Enables the Database Trigger feature.
Default: false
db.trig.log.table
Specifies the name of the log table.
Default: CYB_TRIG_LOG
db.trig.namePrefix
Specifies the prefix name for database triggers.
Default: CYB_
db.trig.pollingInterval.ms
Specifies how often (in milliseconds) the agent plug-in monitors for changes to the
CYB_TRIG_LOG table and any other table for Database Trigger jobs.
Default: 10000 (10 seconds)
db.trig.processMissingTriggers
Specifies whether to generate STATE COMPLETE messages for Database Trigger jobs
and jobs that are no longer tracked.
Default: false (STATE COMPLETE messages are not generated)
db.trig.propfile
Sets the properties file that stores database templates for a particular database
type as follows:
■ dbtrigOracle sets the file to dbtrigOracle.properties
■ dbtrigSqlServer sets the file to dbtrigSqlServer.properties
■ dbtrigDb2 sets the file to dbtrigDb2.properties
■ dbtrigSybase sets the file to dbtrigSybase.properties
The properties files are located in the agent installation directory.

Chapter 5: Configuring the Agent Plug-in 29

How to Set Up an Alias for the Agent Plug-in

db.use.default.outFile
Indicates whether to force the agent to store the results of the SQL query in the
spool file on the agent computer.
true
Forces the agent to store the results of the SQL query in the spool file. If an
output file is specified in the SQL job definition, the agent ignores it.
false
Does not force the agent to store the results of the SQL query in the spool file.
If an output file is specified in the SQL job definition, the results are stored in
the output file.
Note: If the agent runs as root, the owner of the output file is also root. As a
result, the output file can overwrite existing files.
jdbc.drivers
Specifies the driver class name for the JDBC driver. Separate multiple drivers with a
colon (:).
Example:
oracle.jdbc.driver.OracleDriver:com.microsoft.sqlserver.jdbc.SQLServerDriver
plugins.start_internal_n
Specifies the agent plug-in to start by the core Java agent.
n
Denotes an integer that is assigned to the agent plug-in, starting at 1. The n
suffix must increase sequentially for each agent plug-in.

How to Set Up an Alias for the Agent Plug-in

During the agent plug-in installation, you are prompted to create a default alias, which
you can change after installation. If you enable an alias on the agent plug-in, also
configure the alias on the scheduling manager.

To set up an alias for the agent plug-in, follow these steps:

1. Create an alias for the agent plug-in (see page 31).
2. Configure the alias on the scheduling manager (see page 31).

30 Implementation Guide
 Change the JDBC Driver the Agent Plug-in Uses for your Database

Create an Alias for the Agent Plug-in

An alias lets you create a unique agent name for an agent plug-in. Each agent plug-in has
a default alias, which you can enable or change.

To create an alias for the agent, configure the following parameter on the agent:
communication.alias_n
Defines the alias name for the agent. The n suffix increments sequentially for each
alias agent.
Note: To enable an alias on the agent, verify that the comment character (#) is
removed from the parameter line.

Configuring an Alias on the Scheduling Manager

When you create an alias for an agent plug-in, also configure the alias on the scheduling
manager. Define the alias on the scheduling manager with the same address, port
number, and encryption key as the agent where the agent plug-in is installed.

Note: For detailed instructions to configure an alias on the scheduling manager, see the
documentation for your scheduling manager.

Change the JDBC Driver the Agent Plug-in Uses for your
Database
When you install CA WA Agent for Databases, the installation program installs a default
JDBC driver for the database type you chose.

Note: For IBM DB2 on z/OS, copy your own driver.

Follow these steps:

1. Copy the JDBC driver for your database to the jars/ext subdirectory of the agent
installation directory.
Note: If you are using a DB2 database, also copy the license file:
db2jcc_license_cu.jar (UNIX or Windows) or db2jcc_license_cisuz.jar (z/OS)
2. Remove the old JDBC driver if it has a different name to the one you copied.
3. Change to the agent installation directory.

Chapter 5: Configuring the Agent Plug-in 31

Change the JDBC Driver the Agent Plug-in Uses for your Database

4. Stop the agent using one of the following commands:

■ On UNIX:
./cybAgent -s

■ On Windows:
cybAgent -s

5. Open the agentparm.txt file that is ocated in the agent installation directory.
6. Edit the following parameter if the driver class name for your database driver is
different:
jdbc.drivers
Specifies the driver class name for the JDBC driver. Separate multiple drivers
with a colon (:).
Example:
oracle.jdbc.driver.OracleDriver:com.microsoft.sqlserver.jdbc.SQLServerDriver
7. Save and close the agentparm.txt file.
8. Start the agent using one of the following commands:
■ On UNIX:
./cybAgent &

■ On Windows:
cybAgent -a

Locating the JDBC Driver for your Database

To locate the JDBC driver (and license file for DB2) for your database, see the location in
the following table:

Database JDBC Driver Location

IBM DB2 C:\database_install_dir\SQLLIB\java (Windows)
database_install_dir/SQLLIB/java (UNIX)
Microsoft SQL Server C:\database_install_dir\sqljdbc_version\language
Oracle %ORACLE_HOME%\jdbc\lib (Windows)
$ORACLE_HOME/jdbc/lib (UNIX)
Sybase C:\database_install_dir\jConnect-version\devclasses
(Windows)
database_install_dir/jConnect-version/devclasses (UNIX)

32 Implementation Guide
 Change the Number of Simultaneously Open Database Connections

Change the Number of Simultaneously Open Database

Connections
CA WA Agent for Databases maintains simultaneously open database connections. By
default, the agent plug-in allows five simultaneous open connections.

To change the number of simultaneously open database connections, configure the

following parameter on the agent:
db.connectionPool.maxSize
Specifies the maximum number of simultaneously open connections in a database
pool.
Limits: 0-20
Default: 5
Note: If you set it to zero, the agent does not use a connection pool.

Notes:
■ Specify a number greater than five if you run many stored procedures or SQL
queries on the database at one time.
■ Specifying a greater number of open connections to the database requires more
resources. Do not specify a number greater than 20.
■ If you specify zero, connections are not reused. A new database connection opens
each time that you run a database job.

Chapter 5: Configuring the Agent Plug-in 33

Specify a Default Database URL

Specify a Default Database URL

You can specify a default database URL for database jobs. You can override the default
database URL in the job definition.

Note: The scheduling manager uses JDBC to connect to the database.

To specify a default database URL, configure the following parameter on the agent:
db.default.url
Specifies the default database URL, which includes the database host name and
port. When you specify the default location, you use a unique URL format for each
database type. Default database URL specifications are formatted as follows:
■ Oracle database:
jdbc:oracle:thin:@host:port:dbname

Example: jdbc:oracle:thin:@gemini:1527:cyb
■ Oracle Real Application Clusters (RAC)
Example: jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)
(ADDRESS=(PROTOCOL=TCP)(HOST=host1) (PORT=1521))
(ADDRESS=(PROTOCOL=TCP)(HOST=host2) (PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=service)))
■ Microsoft SQL Server database:
db.default.url=jdbc:sqlserver://host:port;DatabaseName=dbname

Example: jdbc:sqlserver://qatest04:1433;DatabaseName=JAT50
■ IBM DB2 database:
db.default.url=jdbc:db2://host:port/dbname

Example: jdbc:db2://sapent:50000/SAMPLE
■ Sybase database:
db.default.url=jdbc:sybase:Tds:host:port/dbname

Example: jdbc:sybase:Tds:dbhost:5000/tsdata
Note: The URL specified in a job definition overrides this value.

34 Implementation Guide
 How to Change the Default Database User ID and Password

Connecting to Oracle Real Application Clusters (RAC)

Connecting to an Oracle RAC system is similar to connecting to a single instance of an
Oracle database. When connecting to a single Oracle database instance, you specify the
SID of the instance to which you want to connect in the JDBC URL. In a RAC
environment, multiple Oracle instances share physical data. List all of them in the JDBC
URL as in the following example:

jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)
(ADDRESS=(PROTOCOL=TCP)(HOST=host1) (PORT=1521))
(ADDRESS=(PROTOCOL=TCP)(HOST=host2) (PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=service)))

In the example, the agent accesses the database through host1 or host2.

Note: If a host that the agent uses to access the database fails or failover occurs,
database jobs fail and must be resubmitted.

How to Change the Default Database User ID and Password

The agent plug-in installation program prompts you for a default database user ID and
password. You can change the default database user ID and password after the
installation.

To change the default database user ID and password, follow these steps:
1. Encrypt the password (see page 36).
2. Change the default database user ID and password (see page 36).

Chapter 5: Configuring the Agent Plug-in 35

How to Change the Default Database User ID and Password

Encrypt the Password

To encrypt a password, run the password utility that is provided with the agent.

Follow these steps:

1. Change to the agent installation directory.
2. Run the password utility using the following command:
■ On UNIX:
password

■ On Windows:
password.bat

3. Enter your password when prompted.

The program responds with your encrypted password.
4. Copy the encrypted string.

Change the Default Database User and Password

After you encrypt the password for the default database user, change that user and
password.

To change the default database user and password, configure the following agent
parameters on the agent:
db.default.user
Specifies the default database user ID that is used to monitor the table. Specify the
encrypted password for this user ID using the db.default.password parameter.
Notes:
■ If another user ID is specified in the job definition, the user ID in the job
definition overrides this default user ID.
■ This parameter does not apply to CA Workload Automation AE.
db.default.password
Specifies the encrypted password for the default database user ID.
Note: This parameter does not apply to CA Workload Automation AE.

36 Implementation Guide
 Specify a Default Oracle User Role for Database Jobs

Specify a Default Oracle User Role for Database Jobs

You can specify a default Oracle database user role that applies globally to all database
jobs. You can override the default in the job definition.

To specify a default Oracle database user role, configure the following parameter on the
agent:
db.default.userType
Specifies the role of the Oracle user to log in as. The user role must be defined in
the Oracle database.
Example: as sysdba

Change the Frequency the Agent Plug-in Monitors for Changes

to the Database
Database Trigger jobs monitor for changes to the database every 10 seconds by default.

To change the frequency the CA WA Agent for Databases monitors for changes to the
database, configure the following parameter on the agent:
db.trig.pollingInterval.ms
Specifies how often (in milliseconds) the agent plug-in monitors for changes to the
CYB_TRIG_LOG table and any other table for Database Trigger jobs.
Default: 10000 (10 seconds)

Enable Automatic Spool File Cleanup

You can configure the agent plug-in to automatically clear spool files of successfully
completed SQL and Stored Procedure jobs.

To enable automatic spool file cleanup, configure the following parameter on the agent:
agent.spool.success.autocleanup
Sets whether the agent automatically clears spool files.
true
Enables automatic spool file cleanup.
false
Disables automatic spool file cleanup.
Default: false

Chapter 5: Configuring the Agent Plug-in 37

Configure the Agent Plug-in to Retry Running a Stored Procedure

Configure the Agent Plug-in to Retry Running a Stored

Procedure
By default, the agent sends only one message to the database to run a stored
procedure. If your system encounters problems with connectivity, for example, you can
have the agent continue resending messages until the stored procedure runs.

To control whether the agent retries running a stored procedure, configure the
following parameter on the agent:
db.dbproc.retryOnFailure
Specifies whether the agent continues to resend a stored procedure when an error
occurs between the agent and the database. The error is logged in the agent log
file.
true
Indicates that the agent retries running a stored procedure when an error
occurs.
false
Indicates that the agent attempts to run a stored procedure only once.
Default: false

38 Implementation Guide
Chapter 6: Troubleshooting the Agent
Plug-in
This section contains the following topics:
Problem Connecting to Oracle Real Application Clusters (RAC) (see page 39)

Problem Connecting to Oracle Real Application Clusters (RAC)

Valid on Windows, UNIX, and Linux

Symptom:
When I run a Database job that connects to an Oracle RAC system, the job goes into a
SUBERROR state with the following error message:

Problem connecting to DB: Listener refused the connection with the following error:
ORA-12505, TNS:listener does not currently know of SID given in connect descriptor.

Solution:

In an Oracle RAC environment, multiple Oracle instances share physical data. List all
Oracle instances in the JDBC URL.

To correct this problem

Use the following example to specify the db.default.url parameter in the agentparm.txt
file or the JDBC URL in the job definition:

Example: JDBC URL for Oracle RAC

jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)
(ADDRESS=(PROTOCOL=TCP)(HOST=host1) (PORT=1521))
(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=service)))

Chapter 6: Troubleshooting the Agent Plug-in 39

Chapter 7: Related Documentation
Documentation for the agent and scheduling managers is available in HTML and PDF
format at http://ca.com/support.

Note: To view PDF files, download and install the Adobe Reader from the Adobe website
if it is not already installed on your computer.

This section contains the following topics:

CA Workload Automation AE Documentation (see page 41)
CA Workload Automation DE Documentation (see page 42)
CA Workload Automation ESP Edition Documentation (see page 42)
CA Workload Automation CA 7 Edition Documentation (see page 43)

CA Workload Automation AE Documentation

To work with the agent and CA Workload Automation AE, see the following
documentation:

Task Documentation
Configure the scheduling CA Workload Automation AE UNIX Implementation
manager to work with the agent Guide
CA Workload Automation AE Windows
Implementation Guide
Define, monitor, and control CA Workload Automation AE Reference Guide
jobs CA Workload Automation AE User Guide
CA Workload Control Center Workload Scheduling
Guide

Chapter 7: Related Documentation 41

CA Workload Automation DE Documentation

CA Workload Automation DE Documentation

To work with the agent and CA Workload Automation DE, see the following
documentation:

Task Documentation

Configure the scheduling manager to CA Workload Automation DE Admin

work with the agent Perspective Help

Define jobs CA Workload Automation DE Define

Perspective Help
Monitor and control jobs CA Workload Automation DE Monitor
Perspective Help

Note: The online help is available in HTML and PDF formats.

CA Workload Automation ESP Edition Documentation

To work with the agent and CA Workload Automation ESP Edition, see the following
documentation:

Task Documentation

Configure the scheduling CA Workload Automation ESP Edition Installation

manager to work with the agent and Configuration Guide

Define jobs CA ESP Workload Automation Database Agent

Guide to Scheduling Workload
CA Workload Automation ESP Edition Command
Reference Guide
Monitor and control jobs CA Workload Automation Agent for UNIX, Linux, or
Windows User Guide
CA Workload Automation ESP Edition Operator's
Guide

42 Implementation Guide
 CA Workload Automation CA 7 Edition Documentation

CA Workload Automation CA 7 Edition Documentation

To work with the agent and CA Workload Automation CA 7 Edition, see the following
documentation:

Task Documentation

Configure the scheduling CA Integrated Agent Services Implementation Guide

manager to work with the agent CA Workload Automation CA 7 Edition Interface
Reference Guide
CA Workload Automation CA 7 Edition Systems
Programming Guide

Define, monitor, and control CA Integrated Agent Services User Guide

jobs CA Workload Automation CA 7 Edition Interface
Reference Guide
CA Workload Automation CA 7 Edition Database
Maintenance Guide
CA Workload Automation CA 7 Edition Command
Reference Guide

Chapter 7: Related Documentation 43

Index
A starting and stopping, agent plug-in • 14
stored procedure, rerunning • 38
agent plug-in
configuring • 24 T
controlling • 14
troubleshooting, agent plug-in • 39
description • 7
installing (UNIX, Windows) • 14 V
uninstall process • 17
alias verification test, agent plug-in installation • 21
setup process • 30
W
C workload example, different jobs • 7
configuration process, agent plug-in • 23

D
database
default user ID and password • 35, 36
encrypting a password • 36
database connections, simulataneous number open
• 33
documentation, scheduling manager • 41

I
installation
instructions • 14
removing the plug-in • 17
verification test • 21

J
job types, supported • 9

N
name, agent plug-in • 31

P
password, encrypting • 36

S
scheduling manager
configuration for the agent plug-in • 21
configuring agent parameters • 24
configuring an alias • 31
documentation • 41
spool file cleanup, automatic • 37

Index 45