CA Workload Automation Agent for Microsoft SQL Server Workload Automation... · CA Workload...

CLI User Guide r11.3.1

CA Workload Automation Agent for Microsoft SQL Server

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 may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and CA.

Notwithstanding the foregoing, 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 © 2013 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 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.

http://www.ca.com/support

mailto:[email protected]

http://www.ca.com/docs

http://www.ca.com/docs

Contents 5

Contents

Chapter 1: Overview 7

About This Guide .......................................................................................................................................................... 7

Using the Command Line Interface .............................................................................................................................. 8

Memory Limitations ..................................................................................................................................................... 8

Chapter 2: Integrating with SQL Server Agent 9

Microsoft SQL Server Command Line Interface ........................................................................................................... 9

Invoking the Microsoft SQL Server CLI ....................................................................................................................... 10

mssql_call Script—Integrate with SQL Server Agent .................................................................................................. 10

Example: List Jobs Defined in SQL Server Agent ................................................................................................. 20

Example: Display the Details of a Job .................................................................................................................. 20

Example: Display Details of All Job Steps ............................................................................................................ 20

Example: Display Details of a Job Step ................................................................................................................ 21

Example: List Target Servers that a Job Can Run on ........................................................................................... 21

Example: Run a Predefined Job ........................................................................................................................... 22

Example: Retrieve the Status of a Job ................................................................................................................. 22

Example: Display the Execution Log of a Job ...................................................................................................... 23

Example: Display the Job Step Log ...................................................................................................................... 23

Example: Cancel a Running Job ........................................................................................................................... 23

Available Fields in Spool File Output by Operation .................................................................................................... 24

Chapter 3: Running the CLI Using Your Scheduling Manager 33

Integration with CA Workload Automation DE .......................................................................................................... 33

Example: Identify SQL Server Agent Job Using a Windows Job .......................................................................... 34

Example: Run SQL Server Agent Job Using a Windows Job ................................................................................ 35

Example: Identify the Reason a SQL Server Agent Job Failed Using a Windows Job .......................................... 36

Integration with CA Workload Automation AE .......................................................................................................... 37

Example: Identify SQL Server Agent Job Using a Command Job ......................................................................... 37

Example: Run SQL Server Agent Job Using a Command Job ............................................................................... 39

Example: Identify the Reason a SQL Server Agent Job Failed Using a Command Job......................................... 40

Integration with CA Workload Automation ESP Edition ............................................................................................ 41




Integration with CA Workload Automation CA 7 Edition ........................................................................................... 45


6 CLI User Guide



Chapter 1: Overview 7

Chapter 1: Overview

This section provides an overview of the Command Line Interface (CLI).

This section contains the following topics:

About This Guide (see page 7) Using the Command Line Interface (see page 8) Memory Limitations (see page 8)

About This Guide

This guide describes how to use the Command Line Interface (CLI) to integrate with SQL Server Agent, a component of Microsoft SQL Server. The guide is intended for scheduling developers and testers.

The CLI lets you invoke agent workload that your scheduling manager does not currently support. For example, if your scheduling manager does not support SQL Server Agent jobs, you can use the CLI to run this workload as Windows (command) jobs. In a future release of your scheduling manager, a SQL Server Agent job type will be added to support this workload. At that time, you can upgrade your scheduling manager to take advantage of the new job type or continue to use the CLI.

Note: For information about running agent workload using the supported job types, see the documentation for your scheduling manager.

Using the Command Line Interface

8 CLI User Guide

Using the Command Line Interface

The CLI is a standalone utility that is shipped with the agent as a batch script. To use the CLI, you define a Windows (command) job in your scheduling manager. In the job definition, you specify the name of the batch script and pass the necessary arguments.

The CLI writes all of the output data to standard output (stdout). When run as a Windows (command) job, the agent captures the output into the job's spool file.

For example, to run a SQL Server Agent job, you pass the target database, job name or job ID, and the database or Windows domain authentication information. When the job is submitted, the batch script runs on the agent and executes a stored procedure to run the SQL Server Agent job. The response is stored in the job's spool file.

The following diagram shows how to use the CLI to run a SQL Server Agent job:

Memory Limitations

When using the CLI, the number of jobs that you can submit and monitor simultaneously is limited to the available free memory. For every CLI job, the agent launches a separate JVM, which results in extra overhead when compared to a dedicated job type supported on a scheduling manager. Generally, each CLI job consumes and occupies about 40 MB of memory until it finishes execution. For example, if a CLI job runs for 2 hours and is tracked to completion, the job occupies 40 MB of memory for the full 2 hours.

When the number of concurrent jobs that is submitted through the CLI consumes all the physical memory on the agent computer, the operating system is forced to swap memory to the hard drive. As a result, the latency between the time the job is submitted to the agent and the time the job starts to run increases. For example, the latency can increase from 1 second to more than 1 minute.


Chapter 2: Integrating with SQL Server Agent

CA WA Agent for Microsoft SQL Server supports integration with SQL Server Agent, a component of Microsoft SQL Server. SQL Server Agent is a Windows service that executes scheduled jobs to automate administrative tasks. Using the agent, you can submit and monitor the status of predefined SQL Server Agent jobs including Transact-SQL scripts, SQL Server Integration Services (SSIS) packages, or Replication tasks. You can also retrieve a list of jobs on a given SQL Server Agent, cancel a running job, read the job log to diagnose errors, or get the spool output for a given job or job step.


Microsoft SQL Server Command Line Interface (see page 9) Invoking the Microsoft SQL Server CLI (see page 10) mssql_call Script—Integrate with SQL Server Agent (see page 10) Available Fields in Spool File Output by Operation (see page 24)

Microsoft SQL Server Command Line Interface

The Microsoft SQL Server CLI is a standalone utility that is shipped with the agent. You can use the CLI to run SQL Server Agent jobs that your scheduling manager does not currently support.

The Microsoft SQL Server CLI is a batch script that you can schedule to run using your scheduling manager, similar to other batch scripts. For example, you can define a Windows (command) job to run a predefined SQL Server Agent job using the CLI.

Invoking the Microsoft SQL Server CLI

10 CLI User Guide

Invoking the Microsoft SQL Server CLI

The Microsoft SQL Server CLI (mssql_call.bat) is located in the following directory:

install_dir\wrappers

install_dir

Specifies the agent installation directory.

To invoke the CLI, specify the following command:

wrappers\mssql_call.bat --argument ...

--argument

Specifies a CLI argument. Prefix each argument with two dashes (--).

Notes:

■ By default, install_dir is the working directory. Do not change the working directory when invoking the Microsoft SQL Server CLI.

■ You cannot invoke the Microsoft SQL Server CLI on the command line.

Example: Display the Online Help

The following example displays the online help:

wrappers\mssql_call.bat --help

mssql_call Script—Integrate with SQL Server Agent

The mssql_call.bat script provides integration with the SQL Server Agent service.

The script has the following format:

wrappers\mssql_call.bat --operation=operation [--TargetDB=target_database]

[--UserName=user_name] [--Password=password] [--Domain=domain_name]

[--Trace=Y|N] --keyword=value ...

--operation=operation

Specifies the operation. Options are as follows:

GetJobList

Lists jobs defined in SQL Server Agent that match specified filtering criteria.

Note: By default, the rows displayed in the spool file are sorted by job ID, followed by name. The agent administrator can configure a properties file to change the sort order. For more information about configuring the properties files, see the Implementation Guide.



GetJobDetail

Displays the details of a job defined in SQL Server Agent.

GetJobStep

Displays job step details of a job defined in SQL Server Agent.

GetJobTargetServer

Lists target servers that a SQL Server Agent job can run on.

RunJob

Runs a predefined SQL Server Agent job. The job can be defined using Microsoft SQL Server Management Studio.

Note: Due to a Microsoft SQL Server restriction, the agent cannot run multiple SQL Server Agent jobs with the same name simultaneously. If a SQL Server Agent job is running, you cannot rerun the job until its previous execution finishes.

GetJobStatus

Retrieves the status of a job defined in SQL Server Agent.

GetJobHistory

Displays the execution log of a job defined in SQL Server Agent.

GetStepLog

Displays the job step log of a job defined in SQL Server Agent.

Notes:

To retrieve the job step log, the Log to table option button must be selected in the Job Step Properties dialog of Microsoft SQL Server Management Studio. If the Log to table option button is not selected, the job step log will not be available.


12 CLI User Guide

■ To retrieve the job step log for previous job executions, the Append output to existing entry in table option button must also be selected in the same dialog. If the Append output to existing entry in table option button is not selected, only the most recent job step log will be available.

■ When the Append output to existing entry in table option button is selected, the log generated from every execution of the job step will be appended. As a result, it can cause a large amount of log data to be kept in the database.

CancelJob

Cancels a running SQL Server Agent job. b

--TargetDB=target_database

(Optional) Specifies the target server database. The agent retrieves the JDBC connection information from the corresponding property file (target_database.properties) stored in the install_dir\config\sql directory.

Notes:

■ If this argument is not specified, the agent uses the default value specified in the mssql.default.TargetDB parameter in the agentparm.txt file.

■ If the target server database is not specified in either the job definition or the mssql.default.TargetDB parameter, the agent reports an error.

--UserName=user_name

(Optional) Specifies the user that the agent uses to create a JDBC connection to the database. The user can be a Windows domain user for Windows domain authentication or a SQL Server user for SQL Server authentication.

Note: If you specify the UserName argument, also specify the Password argument and, optionally, the Domain argument for Windows domain authentication.

--Password=password

(Optional) Specifies the password for the user name.

Important! To avoid specifying passwords in job definitions, omit the UserName, Password, and Domain arguments and use the default user settings specified in the target_database.properties file. We recommend that you secure and restrict access to any job definitions that contain encrypted passwords.

Note: The password must be encrypted. To encrypt a password, use the Password utility that is provided with the agent. For more information about the Password utility, see the CA Workload Automation Agent for UNIX, Linux, or Windows Implementation Guide.



--Domain=domain_name

(Optional) Specifies the Windows domain name for Windows authentication.

Notes:

■ If the UserName, Password, and Domain arguments are specified, the agent assumes that the UserName argument contains the Windows domain user. In this case, Windows domain authentication is used.

■ If the UserName and Password arguments are specified without the Domain argument, the agent assumes that the UserName argument contains the SQL Server user. In this case, SQL Server authentication is used.

■ If none of the UserName, Password, and Domain arguments are specified, the agent uses the default user settings specified in the target_database.properties file.

--Trace=Y|N

(Optional) Indicates whether the agent writes debug information into the spool file.

Y

Writes debug information into the spool file.

N

Does not write debug information into the spool file.

Default: N

--keyword=value

Specifies keywords for the operation.

The GetJobList operation contains the following keywords:

--JobType=job_type

(Optional) Specifies the job type to filter on. Options are LOCAL and MULTI-SERVER. The default is to return all jobs regardless of job type.

--OwnerLoginName=login_name

(Optional) Specifies the login name of the owner of the job to filter on. The default is to return all jobs regardless of the owner login name.

--Subsystem=subsystem

(Optional) Specifies the name of the subsystem to filter on. Options are as follows:

■ TSQL

■ ActiveScripting

■ CmdExec

■ Snapshot


14 CLI User Guide

■ LogReader

■ Distribution

■ Merge

■ QueueReader

■ AnalysisQuery

■ AnalysisCommand

■ SSIS

■ PowerShell

Note: When this argument is specified, only jobs with job steps that belong to the specified subsystem are listed. The default is to return all jobs regardless of subsystem.

--CategoryName=category_name

(Optional) Specifies the category name to filter on. The default is to return all jobs regardless of category.

--Enabled=Y|N

(Optional) Indicates whether to list only enabled or disabled jobs.

Y

Lists only enabled jobs.

N

Lists only disabled jobs.

The default is to return enabled and disabled jobs.

--ExecutionStatus=0|1|2|3|4|5|7

(Optional) Specifies the execution status to filter on. Options are as follows:

0

Lists only jobs that are not idle or suspended.

1

Lists only jobs that are executing.

2

Lists only jobs that are waiting for a thread.

3

Lists only jobs that are between retries.

4

Lists only jobs that are idle.



5

Lists only jobs that are suspended.

7

Lists only jobs that are performing completion options.

The default is to return all jobs regardless of execution status.

--DateComparator=<|>

(Optional) Specifies the date comparator. DateComparator must be used with the DateCreated or DateLastModified arguments to filter the jobs listed.

Note: Since the date comparator is a special character, enclose the value in double quotes and escape the double quotes, for example, \">\".

--DateCreated=date_created

(Optional) Specifies the date that the job was created in the format YYYY-MM-DD HH:MM:SS. DateCreated must be used with the DateComparator argument to filter the jobs listed.

--DateLastModified=date_last_modified

(Optional) Specifies the date that the job was last modified in the format YYYY-MM-DD HH:MM:SS. DateLastModified must be used with the DateComparator argument to filter the jobs listed.

--Description=job_description

(Optional) Specifies the job description to filter on. The Description argument can include standard SQL wildcard characters such as %, _, ^, and [] for pattern matching. The default is to return all jobs regardless of description.

Note: When using wildcards, enclose the value in double quotes and escape the double quotes. For example, Description=\"this%\" returns all jobs with a job description that starts with "this". Description=\"Test[1-2]\" returns all jobs with a job description of Test1 or Test2.

The GetJobDetail operation contains the following keywords:

--JobId=job_id

Specifies the internal job identification number. Specify the JobId argument or the JobName argument, but not both.

--JobName=job_name

Specifies the job name. Specify the JobId argument or the JobName argument, but not both.

Note: The agent does not support double quotes in the job name. If the job name includes double quotes, remove the double quotes from the job definition using Microsoft SQL Server Management Studio.


16 CLI User Guide

The GetJobStep operation contains the following keywords:

--JobId=job_id


--JobName=job_name



--StepId=job_step_id

(Optional) Specifies the job step identification number. Specify the StepId argument or the StepName argument, but not both. When the StepId or StepName argument is specified, the agent returns only the job and specified job step details. The default is to include all steps for the specified job in the output.

--StepName=job_step_name

(Optional) Specifies the job step name. Specify the StepId argument or the StepName argument, but not both. When the StepId or StepName argument is specified, the agent returns only the job and specified job step details. The default is to include all steps for the specified job in the output.

The GetJobTargetServer operation contains the following keywords:

--JobId=job_id


--JobName=job_name



The RunJob operation contains the following keywords:

--JobId=job_id




--JobName=job_name



--StepName=job_step_name

(Optional) Specifies the name of the job step to start the job from. The default is to start the job from the first step.

--ServerName=target_server

(Optional) Specifies the target server to start the job on.

--Track=Y|N

(Optional) Indicates whether to track the job to completion.

Y

Tracks the job to completion. The CLI call returns when the job completes, whether successfully or not. The job and job step execution status is written to the spool file. The completion code of the CLI call indicates whether the job failed or succeeded. If the job was submitted successfully and the job completed successfully, 0 is returned. If job submission failed or the job failed during monitoring, 1 is returned.

Note: Since the agent launches one JVM for every CLI call, the JVM overhead can be substantial when too many CLI calls are running concurrently. If the job takes a considerable amount of time to finish, system resources can be impacted.

N

Does not track the job to completion. The agent exits the JVM immediately after the job is submitted instead of waiting for the job completion. To retrieve the job running status, you can use the GetJobStatus operation. The completion code of the CLI call indicates only whether the job submission succeeded or failed. If the job was submitted successfully, 0 is returned. If job submission failed, 1 is returned. The spool file indicates the reason for the job submission error, such as a JDBC connection failure.

Default: Y

The GetJobStatus operation contains the following keywords:

--JobId=job_id



18 CLI User Guide

--JobName=job_name



The GetJobHistory operation contains the following keywords:

--JobId=job_id


--JobName=job_name




(Optional) Specifies the identification number of the job step to return a log for. The default is to include all steps for the specified job in the output.

--LastHours=hours

(Optional) Specifies the job runs that were started in the last number of hours (hours). The LastHours, LastDays, and StartDateTime arguments are mutually exclusive. When none of the arguments are specified, the agent returns the log of the latest job run.

Limits: Up to 99 hours

--LastDays=days

(Optional) Specifies the job runs that were started in the last number of days (days). The LastHours, LastDays, and StartDateTime arguments are mutually exclusive. When none of the arguments are specified, the agent returns the log of the latest job run.

Limits: Up to 99 days

--StartDateTime=job_started_time

(Optional) Specifies the job runs that were started on and after a specified time in the format YYYY-MM-DD HH:MM:SS. The agent retrieves the job history using the SQL Server time. The LastHours, LastDays, and StartDateTime arguments are mutually exclusive. When none of the arguments are specified, the agent returns the log of the latest job run.

Example: "2010-02-03 14:53:00"



The GetStepLog operation contains the following keywords:

--JobId=job_id


--JobName=job_name




(Optional) Specifies the identification number of the job step to return a log for. The default is to include all steps for the specified job in the output.

The CancelJob operation contains the following keywords:

--JobId=job_id

Specifies the internal identification number of the job to cancel. Specify only one of the JobId, JobName, and OriginatingServer arguments.

--JobName=job_name

Specifies the name of the job to cancel. Specify only one of the JobId, JobName, and OriginatingServer arguments.


--OriginatingServer=master_server

Specifies the name of a master server. If this argument is specified, all multiserver jobs are stopped with a default of NULL. Specify this argument only when using the CancelJob operation against a target server. Specify only one of the JobId, JobName, and OriginatingServer arguments.

Note: This keyword only applies to canceling multiserver jobs. If a multiserver job is not running, an exception ("job is not currently running") occurs.

--ServerName=target_server_name

(Optional) Specifies the name of a target server to stop a multiserver job on with a default of NULL. Specify this argument only when using the CancelJob operation against a master server for a multiserver job.


20 CLI User Guide

Example: List Jobs Defined in SQL Server Agent

This example lists the jobs defined in SQL Server Agent with a job description that contains "this". Since the Domain argument is specified, Windows authentication is used.

wrappers\mssql_call.bat --operation=GetJobList --TargetDB=localdb --UserName=AUSER

--Password=3B38CA1614D55535 --Domain=OURDOMAIN --Description=\"%this%\"

The spool file output lists two matching jobs:

[job_id] [name] [description]

[AD9AFEA6-9F6F-4BD1-B3EF-42C814416209] [Test job monitoring] [this is a test job]

[6EB57D23-6C95-4D6E-9463-FF19AB44EB4D] [2stepsjob(1. exec os cmd 2. exec tsql)] [this

is a backup job]

Example: Display the Details of a Job

This example displays the details of a job named "Test job monitoring":

wrappers\mssql_call.bat --operation=GetJobDetail --UserName=AUSER

--Password=3B38CA1614D55535 --TargetDB=localdb --JobName="Test job monitoring”

--Domain=OURDOMAIN

The spool file output is similar to the following:

[job_id] [originating_server] [name] [enabled] [description] [category] [owner]

[date_modified]

[AD9AFEA6-9F6F-4BD1-B3EF-42C814416209] [SERVER1] [Test job monitoring] [1] [this is

a test job] [[Uncategorized (Local)]]

[domain\userid] [2012-03-08 16:14:14.723]

Example: Display Details of All Job Steps

This example displays details of all job steps for a job named "Test job monitoring":

wrappers\mssql_call.bat --operation=GetJobStep --TargetDB=localdb --UserName=AUSER

--Password=3B38CA1614D55535 --Domain=OURDOMAIN --JobName="Test job monitoring"


[step_id] [step_name] [subsystem] [command]

[1] [step 1] [CmdExec] [c:\user\work\wait.bat 20]

[2] [step 2] [CmdExec] [c:\user\work\unknown.bat]





Example: Display Details of a Job Step

This example displays details of a job step named "Step 2" for a job named "Test job monitoring":

wrappers\mssql_call.bat --operation=GetJobStep --TargetDB=localdb --UserName=AUSER


--StepName="Step 2"


[step_id] [step_name] [subsystem] [command]

[2] [step 2] [CmdExec] [c:\user\work\unknown.bat]

Example: List Target Servers that a Job Can Run on

This example lists the target servers that a job named "Test job monitoring" can run on:

wrappers\mssql_call.bat --operation=GetJobTargetServer --TargetDB=localdb

--JobName="Test job monitoring" --Domain=OURDOMAIN --UserName=AUSER

--Password=3B38CA1614D55535


[server_id] [server_name] [enlist_date]

[0] [SERVER1] [1998-11-13 00:00:00.0]


22 CLI User Guide

Example: Run a Predefined Job

This example runs a predefined job named "Test job monitoring". Since the Track argument is set to Y, the job is tracked to completion.

wrappers\mssql_call.bat --operation=RunJob --TargetDB=localdb --UserName=AUSER


--Track=Y

When the job completes, the spool file output is similar to the following:

job (jobName=Test job monitoring) has been submitted successfully

step 1 In-progress; status of job with jobname(Test job monitoring ) is executing

step 1 Succeeded; step 2 Failed; step 3 In-progress; status of job with jobname(Test

job monitoring ) is executing

step 3 Succeeded; step 4 Succeeded; completed with completioncode 1

This example runs the same job, but this time the job is not tracked to completion:

wrappers\mssql_call.bat --operation=RunJob --TargetDB=localdb --UserName=AUSER


--Track=N


job (jobName=Test job monitoring) has been submitted successfully

To retrieve the job running status, you can use the GetJobStatus operation.

Example: Retrieve the Status of a Job

This example retrieves the status of a job named "Test job monitoring":

wrappers\mssql_call.bat --operation=GetJobStatus –UserName=AUSER

–Password=3B38CA1614D55535 --Domain=OURDOMAIN --TargetDB=localdb --JobName="Test

job monitoring"


[job_id] [originating_server] [name] [last_run_date] [last_run_time]

[last_run_outcome] [current_execution_status] [current_execution_step]

[current_retry_attempt] [type]

[AD9AFEA6-9F6F-4BD1-B3EF-42C814416209] [SERVER1] [Test job monitoring] [20120301]

[140257] [1] [4] [0 (unknown)] [0] [1]



Example: Display the Execution Log of a Job

This example displays the execution log of a job named "Test job monitoring":

wrappers\mssql_call.bat --operation=GetJobHistory –UserName=AUSER


job monitoring"


[step_id] [step_name] [sql_message_id] [sql_severity] [message] [run_status]

[run_date] [run_time] [run_duration]

[0] [(Job outcome)] [0] [0] [The job succeeded. The Job was invoked by User

domain\userid. The last step to run was step 4 (step 4).] [1] [20120430] [113749]

[44]

Example: Display the Job Step Log

This example display the job step log of a job named "Test job monitoring":

wrappers\mssql_call.bat --operation=GetStepLog –UserName=AUSER


job monitoring"


[job_id] [job_name] [step_id] [step_name] [step_uid] [date_created] [date_modified]

[log_size] [log]

[AD9AFEA6-9F6F-4BD1-B3EF-42C814416209] [Test job monitoring] [1] [step 1]

[EEB58783-2A32-4359-9A44-02C11F9D1222] [2012-04-30 11:50:51.833] [2012-04-30

11:51:05.817] [2184] [Pinging 127.0.0.1 with 32 bytes of data:]

Example: Cancel a Running Job

This example cancels a running job named "Test job monitoring":

wrappers\mssql_call.bat --operation=CancelJob –UserName=AUSER


job monitoring"


job (jobName=Test job monitoring) has been cancelled successfully

Available Fields in Spool File Output by Operation

24 CLI User Guide


The following sections describe the available fields that can be displayed in the spool file for each operation. Not all of the available fields are included in the output by default.

Note: The agent administrator can configure the system properties file to change the fields that are displayed for each operation on all target databases. Alternatively, they can configure a target server database properties file to change the fields that are displayed for each operation on a particular target database. For more information about configuring the system and target server database properties files, see the Implementation Guide.

The GetJobList operation can display the following fields:

job_id

Specifies the unique ID for the job.

originating_server

Specifies the name of the server the job belongs to.

name

Specifies the name of the job.

enabled

Indicates whether the job is enabled to be executed.

description

Specifies the job description.

category

Specifies the job category.

owner

Specifies the job owner.

date_modified

Specifies the date that the job was last modified.

Note: By default, the job_id, name, and description fields are included in the output.

The GetJobDetail operation can display the following fields:

job_id


originating_server




name


enabled

Indicates whether the job is enabled to be executed.

description

Specifies the job description.

category

Specifies the job category.

owner

Specifies the job owner.

date_modified

Specifies the date that the job was last modified.

Note: By default, all the available fields are included in the output.

The GetJobStep operation can display the following fields:

step_id

Specifies the job step ID.

step_name

Specifies the name of the step.

subsystem

Specifies the name of the subsystem where the step command executes.

command

Specifies the name of the command to execute.

flags

Specifies a bitmask of values that control step behavior.

cmdexec_success_code

(CmdExec steps only) Specifies the process exit code of a successful command.


26 CLI User Guide

on_success_action

Specifies the action to take if the step succeeds. Options are as follows:

1

Quits with success.

2

Quits with failure.

3

Goes to the next step.

4

Goes to the step indicated by the on_success_step_id field.

on_success_step_id

Indicates the next step to execute when the on_success_action field is set to 4.

on_fail_action

Specifies the action to take if the step fails. Options are as follows:

1

Quits with success.

2

Quits with failure.

3

Goes to the next step.

4

Goes to the step indicated by the on_fail_step_id field.

on_fail_step_id

Indicates the next step to execute when the on_fail_action field is set to 4.

server

Reserved.

database_name

(Transact-SQL steps only) Specifies the database where the command executes.

database_user_name

(Transact-SQL steps only) Specifies the database user context where the command executes.



retry_attempts

Specifies the maximum number of times that the command is retried (if it is unsuccessful) before the step is deemed to have failed.

retry_interval

Specifies the interval in minutes between retry attempts.

os_run_priority

Reserved.

output_file_name

(Transact-SQL and CmdExec steps only) Specifies the file that the command output is written to.

last_run_outcome

Specifies the outcome of the step the last time it ran. Options are as follows:

0

Indicates the step failed.

1

Indicates the step succeeded.

3

Indicates the step was canceled.

5

Indicates the status was unknown.

last_run_duration

Specifies the duration in seconds of the step the last time it ran.

last_run_retries

Specifies the number of times the command was retried the last time that the step ran.

last_run_date

Specifies the date when the step last started execution.

last_run_time

Specifies the time when the step last started execution.

proxy_id

Specifies the proxy for the job step.

Note: By default, the step_id, step_name, subsystem, and command fields are included in the output.


28 CLI User Guide

The GetJobTargetServer operation can display the following fields:

server_id

Specifies the identifier of the target server.

server_name

Specifies the computer name of the target server.

enlistdate

Specifies the date that the target server was enlisted into the master server.


The GetJobStatus operation can display the following fields:

job_id


originating_server


name


LastRunDateTime

Specifies the last time the job ran in the format YYYY-MM-DD HH:MM:SS.

LastRunOutcome

Specifies the outcome of the job the last time it ran. Options are as follows:

0

Indicates the job failed.

1

Indicates the job succeeded.

3

Indicates the job was canceled.

5

Indicates the status was unknown.



CurrentExecutionStatus

Indicates the current execution status of the job. Options are as follows:

1

Indicates that the job is executing.

2

Indicates that the job is waiting for a thread.

3

Indicates that the job is between retries.

4

Indicates that the job is idle.

5

Indicates that the job is suspended.

7

Indicates that the job is performing completion actions.

CurrentExecutionStep

Specifies the step that is currently running.

CurrentRetryAttempt

Specifies the current retry attempt if the job is running and the step has been retried.

Type

Species the type of job. Options are as follows:

0

Indicates that the job has no target servers.

1

Indicates a local job.

2

Indicates a multiserver job.


The GetJobHistory operation can display the following fields:

instance_id

Specifies the history entry identification number.


30 CLI User Guide

job_id


job_name


step_id


step_name


sql_message_id

(Transact-SQL steps only) Specifies the most recent Transact-SQL error number encountered while running the command.

sql_severity

(Transact-SQL steps only) Specifies the highest Transact-SQL error severity encountered while running the command.

message

Specifies the job or step history message.

run_status

Specifies the outcome of the job or step.

run_date

Specifies the date the job or step began executing.

run_time

Specifies the time the job or step began executing.

run_duration

Specifies the elapsed time in the execution of the job or step in the format HHMMSS.

operator_emailed

Specifies the operator who was emailed regarding this job (is NULL for step history).

operator_netsent

Specifies the operator who was sent a network message regarding this job (is NULL for step history).

operator_paged

Specifies the operator who was paged regarding this job (is NULL for step history).



retries_attempted

Specifies the number of times the step was retried (always 0 for job history).

server

Specifies the server the step or job executes on. Is always (local).

Note: By default, the step_id, step_name, sql_message_id, sql_severity, message, run_status, run_date, run_time, and run_duration fields are included in the output.

The GetStepLog operation can display the following fields:

job_name


step_id


step_name


step_uid

Specifies the unique identifier of the step (system-generated) in the job.

date_created

Specifies the date that the step was created.

date_modified

Specifies the date that the step was last modified.

log_size

Specifies the size of the job step log in megabytes (MB).

Log

Specifies the job step log output.



Chapter 3: Running the CLI Using Your Scheduling Manager

You can run the mssql_call script using any CA scheduling manager product including CA Workload Automation DE, CA Workload Automation AE, CA Workload Automation ESP Edition, and CA Workload Automation CA 7 Edition. You can then track the job to completion using the standard product features for monitoring.

Note: For more information about using one of these CA scheduling manager products, see the appropriate CA documentation.


Integration with CA Workload Automation DE (see page 33) Integration with CA Workload Automation AE (see page 37) Integration with CA Workload Automation ESP Edition (see page 41) Integration with CA Workload Automation CA 7 Edition (see page 45)

Integration with CA Workload Automation DE

To run the mssql_call script using CA Workload Automation DE, you define a Windows job in CA WA Desktop Client that runs the script. The job is defined as part of an Application and runs on a Windows agent.

Note: For more information about defining Windows jobs using CA Workload Automation DE, see the CA Workload Automation DE Define Perspective Help.


34 CLI User Guide

Example: Identify SQL Server Agent Job Using a Windows Job

To run a job that is already defined in SQL Server Agent, you require the job name or job ID. If you do not know the job name or job ID, you can use the GetJobList operation to help you identify the job.

This example lists the jobs defined in SQL Server Agent using a Windows job. The following CLI arguments are passed to the batch script:

■ Name of the operation (GetJobList)

■ Target server database (MYDATABASE)

■ User name (AUSER), password (3B38CA1614D55535), and domain (OURDOMAIN)

To list the jobs defined in SQL Server Agent

1. Create a Windows job in the Application.

2. Enter the following information in the Basic page of the job definition:

■ Name—get_job_list

■ Agent—WINAGENT

■ Command to run—wrappers\mssql_call.bat

■ Arguments to pass—--operation=GetJobList --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN

3. Click OK.

After the job completes, you can retrieve the list of jobs from the spool file. You can then use the GetJobDetail operation to get details about a particular job. For example, you can display the details of a job named MYJOB using another Windows job.

To display the details of a job



■ Name—get_job_detail



■ Arguments to pass—--operation=GetJobDetail --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=MYDOMAIN --JobName=MYJOB

3. Click OK.

After the job completes, you can retrieve the job details from the spool file.



Example: Run SQL Server Agent Job Using a Windows Job

After you identify the job, you can run it immediately using the RunJob operation.

This example runs a predefined job named MYJOB using a Windows job. The following CLI arguments are passed to the batch script:

■ Name of the operation (RunJob)

■ Name of the SQL Server Agent job (MYJOB)



■ Option to track the job to completion

To run a predefined job



■ Name—run_job



■ Arguments to pass—--operation=RunJob --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN --Track=Y

3. Click OK.

When the job completes successfully, it indicates that MYJOB has completed successfully on SQL Server Agent.


36 CLI User Guide

Example: Identify the Reason a SQL Server Agent Job Failed Using a Windows Job

If the job fails during execution, you can use the GetJobHistory operation to find out the reason for the failure.

This example displays the execution log of a job named MYJOB using a Windows job. The following CLI arguments are passed to the batch script:

■ Name of the operation (GetJobHistory)




■ The time the job started running (2010-02-03 14:53:00)

You can retrieve the job's start time from the spool file of the job that failed.

To display the execution log of a job



■ Name—get_job_history



■ Arguments to pass—--operation=GetJobHistory --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN --StartDateTime="2010-02-03 14:53:00"

3. Click OK.

After the job completes, you can retrieve the execution log from the spool file. You can then use the GetStepLog operation to display the job step log. For example, you can display the job step log of the MYJOB job using another Windows job.

To display the job step log



■ Name—get_step_log



■ Arguments to pass—--operation=GetStepLog --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN

Integration with CA Workload Automation AE


3. Click OK.

After the job completes, you can retrieve job step log from the spool file.


To run the mssql_call script using CA Workload Automation AE, you define a command job in JIL or CA Workload Control Center that runs the script. The job runs on a Windows agent.

Notes:

■ You cannot insert a job if the value specified in the command exceeds 512 bytes. To avoid this limitation, embed the entire CLI command in a batch script and specify the full path to the script as the command.

■ For more information about defining command jobs using CA Workload Automation AE, see the CA Workload Automation AE User Guide and the CA Workload Automation AE Reference Guide.

■ For more information about defining command jobs using CA Workload Control Center, see the CA Workload Control Center Workload Scheduling Guide.

Example: Identify SQL Server Agent Job Using a Command Job


This example lists the jobs defined in SQL Server Agent using a command job. The following CLI arguments are passed to the batch script:




To define the command job in JIL

Insert a job and specify the following attributes in the definition:

insert_job: get_job_list

job_type: CMD

machine: winagent

command: wrappers\mssql_call.bat --operation=GetJobList --TargetDB=MYDATABASE

--UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN


38 CLI User Guide

To define the command job in CA Workload Control Center

1. Create a Command job.

2. Enter the following properties:

■ Name—get_job_list

■ Send to machine—WINAGENT

■ Command—wrappers\mssql_call.bat --operation=GetJobList --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN

3. Commit the job.

After the job completes, you can retrieve the list of jobs from the spool file. You can then use the GetJobDetail operation to get details about a particular job. For example, you can display the details of a job named MYJOB using another command job.



insert_job: get_job_detail

job_type: CMD

machine: winagent

command: wrappers\mssql_call.bat --operation=GetJobDetail --TargetDB=MYDATABASE

--UserName=AUSER --Password=3B38CA1614D55535 --Domain=MYDOMAIN --JobName=MYJOB




■ Name—get_job_detail


■ Command—wrappers\mssql_call.bat --operation=GetJobDetail --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=MYDOMAIN --JobName=MYJOB

3. Commit the job.




Example: Run SQL Server Agent Job Using a Command Job


This example runs a predefined job named MYJOB using a command job. The following CLI arguments are passed to the batch script:








insert_job: run_job

job_type: CMD

machine: winagent

command: wrappers\mssql_call.bat --operation=RunJob --JobName=MYJOB

--TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535

--Domain=OURDOMAIN --Track=Y




■ Name—run_job


■ Command—wrappers\mssql_call.bat --operation=RunJob --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN --Track=Y

3. Commit the job.



40 CLI User Guide

Example: Identify the Reason a SQL Server Agent Job Failed Using a Command Job


This example displays the execution log of job named MYJOB using a command job. The following CLI arguments are passed to the batch script:









insert_job: get_job_history

job_type: CMD

machine: winagent

command: wrappers\mssql_call.bat --operation=GetJobHistory --JobName=MYJOB


--Domain=OURDOMAIN --StartDateTime="2010-02-03 14:53:00"




■ Name—get_job_history


■ Command—wrappers\mssql_call.bat --operation=GetJobHistory --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN --StartDateTime="2010-02-03 14:53:00"

3. Commit the job.

Integration with CA Workload Automation ESP Edition


After the job completes, you can retrieve the execution log from the spool file. You can then use the GetStepLog operation to display the job step log. For example, you can display the job step log of the MYJOB job using another command job.



insert_job: get_step_log

job_type: CMD

machine: winagent

command: wrappers\mssql_call.bat --operation=GetStepLog --JobName=MYJOB


--Domain=OURDOMAIN




■ Name—get_step_log


■ Command—wrappers\mssql_call.bat --operation=GetStepLog --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN

3. Commit the job.



To run the mssql_call script using CA Workload Automation ESP Edition, you define a Windows job that runs the script. The job is defined as part of an Application and runs on a Windows agent.

Note: For more information about defining Windows jobs using CA Workload Automation ESP Edition, see the CA Workload Automation Agent for UNIX, Linux, or Windows User Guide.


42 CLI User Guide







The following job definition lists the jobs defined in SQL Server Agent using a Windows job:

NT_JOB GET_JOB_LIST

AGENT WINAGENT

CMDNAME wrappers\mssql_call.bat

ARGS --operation=GetJobList --TargetDB=MYDATABASE +


RUN DAILY

ENDJOB

After the job completes, you can retrieve the list of jobs from the spool file. You can then use the GetJobDetail operation to get details about a particular job.

The following job definition displays the details of a job named MYJOB using a Windows job:

NT_JOB GET_JOB_DETAIL

AGENT WINAGENT


ARGS --operation=GetJobDetail --TargetDB=MYDATABASE +

--UserName=AUSER --Password=3B38CA1614D55535 --Domain=OURDOMAIN +

--JobName=MYJOB

RUN DAILY

ENDJOB












The following job definition runs a predefined job named MYJOB using a Windows job:

NT_JOB RUN_JOB

AGENT WINAGENT


ARGS --operation=RunJob --JobName=MYJOB --TargetDB=MYDATABASE +


--Track=Y

RUN DAILY

ENDJOB



44 CLI User Guide



This example displays the execution log of job named MYJOB using a Windows job. The following CLI arguments are passed to the batch script:







The following job definition retrieves the execution log of a job named MYJOB using a Windows job:

NT_JOB GET_JOB_HISTORY

AGENT WINAGENT


ARGS --operation=GetJobHistory --JobName=MYJOB +

--TargetDB=MYDATABASE --UserName=AUSER +

--Password=3B38CA1614D55535 --Domain=OURDOMAIN +

--StartDateTime="2010-02-03 14:53:00"

RUN DAILY

ENDJOB

After the job completes, you can retrieve the execution log from the spool file. You can then use the GetStepLog operation to display the job step log.

The following job definition displays the job step log of the MYJOB job using another Windows job:

NT_JOB GET_STEP_LOG

AGENT WINAGENT


ARGS --operation=GetStepLog --JobName=MYJOB +


--Password=3B38CA1614D55535 --Domain=OURDOMAIN

RUN DAILY

ENDJOB


Integration with CA Workload Automation CA 7 Edition



To run the mssql_call script using CA Workload Automation CA 7 Edition, you define a Windows job that runs the script. The job runs on a Windows agent.

Note: For more information about defining Windows jobs using CA Workload Automation CA 7 Edition, see the CA Integrated Agent Services User Guide.







The following job definition lists the jobs defined in SQL Server Agent using a Windows job:

AGENT WINAGENT


ARGS --operation=GetJobList --TargetDB=MYDATABASE +


After the job completes, you can retrieve the list of jobs from the spool file. You can then use the GetJobDetail operation to get details about a particular job.

The following job definition displays the details of a job named MYJOB using a Windows job:

AGENT WINAGENT


ARGS --operation=GetJobDetail --TargetDB=MYDATABASE +


--JobName=MYJOB



46 CLI User Guide









The following job definition runs a predefined job named MYJOB using a Windows job:

AGENT WINAGENT


ARGS --operation=RunJob --JobName=MYJOB --TargetDB=MYDATABASE +


--Track=Y






This example displays the execution log of job named MYJOB using a Windows job. The following CLI arguments are passed to the batch script:







The following job definition retrieves the execution log of a job named MYJOB using a Windows job:

AGENT WINAGENT


ARGS --operation=GetJobHistory --JobName=MYJOB +


--Password=3B38CA1614D55535 --Domain=OURDOMAIN +

--StartDateTime="2010-02-03 14:53:00"

After the job completes, you can retrieve the execution log from the spool file. You can then use the GetStepLog operation to display the job step log.

The following job definition displays the job step log of the MYJOB job using another Windows job:

AGENT WINAGENT


ARGS --operation=GetStepLog --JobName=MYJOB +


--Password=3B38CA1614D55535 --Domain=OURDOMAIN


CA Workload Automation Agent for Microsoft SQL Server Workload Automation... · CA Workload...

Documents

Transcript of CA Workload Automation Agent for Microsoft SQL Server Workload Automation... · CA Workload...