CA Workload Automation Agent for Microsoft SQL Server

Transcription

1 CA Workload Automation Agent for Microsoft SQL Server CLI User Guide r11.3.1

2 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 , , and (c)(1) - (2) and DFARS Section (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.

3 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

4 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 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 techpubs@ca.com. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at

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 mssql_call Script Integrate with SQL Server Agent Example: List Jobs Defined in SQL Server Agent Example: Display the Details of a Job Example: Display Details of All Job Steps Example: Display Details of a Job Step Example: List Target Servers that a Job Can Run on Example: Run a Predefined Job Example: Retrieve the Status of a Job Example: Display the Execution Log of a Job Example: Display the Job Step Log Example: Cancel a Running Job Available Fields in Spool File Output by Operation Chapter 3: Running the CLI Using Your Scheduling Manager 33 Integration with CA Workload Automation DE Example: Identify SQL Server Agent Job Using a Windows Job Example: Run SQL Server Agent Job Using a Windows Job Example: Identify the Reason a SQL Server Agent Job Failed Using a Windows Job Integration with CA Workload Automation AE Example: Identify SQL Server Agent Job Using a Command Job Example: Run SQL Server Agent Job Using a Command Job Example: Identify the Reason a SQL Server Agent Job Failed Using a Command Job Integration with CA Workload Automation ESP Edition Example: Identify SQL Server Agent Job Using a Windows Job Example: Run SQL Server Agent Job Using a Windows Job Example: Identify the Reason a SQL Server Agent Job Failed Using a Windows Job Integration with CA Workload Automation CA 7 Edition Example: Identify SQL Server Agent Job Using a Windows Job Contents 5

6 Example: Run SQL Server Agent Job Using a Windows Job Example: Identify the Reason a SQL Server Agent Job Failed Using a Windows Job CLI User Guide

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. Chapter 1: Overview 7

8 Using the Command Line Interface 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. 8 CLI User Guide

9 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. This section contains the following topics: 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. Chapter 2: Integrating with SQL Server Agent 9

10 Invoking the Microsoft SQL Server CLI 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. 10 CLI User Guide

11 mssql_call Script Integrate with SQL Server Agent 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 RunJob Lists target servers that a SQL Server Agent job can run on. 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. Chapter 2: Integrating with SQL Server Agent 11

12 b mssql_call Script Integrate with SQL Server Agent 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. --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. 12 CLI User Guide

13 mssql_call Script Integrate with SQL Server Agent --Domain=domain_name (Optional) Specifies the Windows domain name for Windows authentication. Notes: --Trace=Y N 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. (Optional) Indicates whether the agent writes debug information into the spool file. Y N Writes debug information into the spool file. 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 Chapter 2: Integrating with SQL Server Agent 13

14 mssql_call Script Integrate with SQL Server Agent 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 N Lists only enabled jobs. Lists only disabled jobs. The default is to return enabled and disabled jobs. --ExecutionStatus= (Optional) Specifies the execution status to filter on. Options are as follows: Lists only jobs that are not idle or suspended. Lists only jobs that are executing. Lists only jobs that are waiting for a thread. Lists only jobs that are between retries. Lists only jobs that are idle. 14 CLI User Guide

15 mssql_call Script Integrate with SQL Server Agent 5 7 Lists only jobs that are suspended. 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. Chapter 2: Integrating with SQL Server Agent 15

16 mssql_call Script Integrate with SQL Server Agent The GetJobStep 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. --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 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. The RunJob 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. 16 CLI User Guide

17 mssql_call Script Integrate with SQL Server Agent --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. --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 N 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. 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 Specifies the internal job identification number. Specify the JobId argument or the JobName argument, but not both. Chapter 2: Integrating with SQL Server Agent 17

18 mssql_call Script Integrate with SQL Server Agent --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. The GetJobHistory 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. --StepId=job_step_id (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: " :53:00" 18 CLI User Guide

19 mssql_call Script Integrate with SQL Server Agent The GetStepLog 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. --StepId=job_step_id (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. 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. --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. Chapter 2: Integrating with SQL Server Agent 19

20 mssql_call Script Integrate with SQL Server Agent 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=3B38CA1614D Domain=OURDOMAIN --Description=\"%this%\" The spool file output lists two matching jobs: [job_id] [name] [description] [AD9AFEA6-9F6F-4BD1-B3EF-42C ] [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=3B38CA1614D 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-42C ] [SERVER1] [Test job monitoring] [1] [this is a test job] [[Uncategorized (Local)]] [domain\userid] [ :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=3B38CA1614D Domain=OURDOMAIN --JobName="Test job monitoring" The spool file output is similar to the following: [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] [3] [step 3] [CmdExec] [c:\user\work\wait.bat 20] [4] [step 4] [CmdExec] [c:\user\work\wait.bat 1] 20 CLI User Guide

21 mssql_call Script Integrate with SQL Server Agent 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 --Password=3B38CA1614D Domain=OURDOMAIN --JobName="Test job monitoring" --StepName="Step 2" The spool file output is similar to the following: [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 The spool file output is similar to the following: [server_id] [server_name] [enlist_date] [0] [SERVER1] [ :00:00.0] Chapter 2: Integrating with SQL Server Agent 21

22 mssql_call Script Integrate with SQL Server Agent 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 --Password=3B38CA1614D Domain=OURDOMAIN --JobName="Test job monitoring" --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 --Password=3B38CA1614D Domain=OURDOMAIN --JobName="Test job monitoring" --Track=N The spool file output is similar to the following: 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=3B38CA1614D Domain=OURDOMAIN --TargetDB=localdb --JobName="Test job monitoring" The spool file output is similar to the following: [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-42C ] [SERVER1] [Test job monitoring] [ ] [140257] [1] [4] [0 (unknown)] [0] [1] 22 CLI User Guide

23 mssql_call Script Integrate with SQL Server Agent 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 Password=3B38CA1614D Domain=OURDOMAIN --TargetDB=localdb --JobName="Test job monitoring" The spool file output is similar to the following: [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] [ ] [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 Password=3B38CA1614D Domain=OURDOMAIN --TargetDB=localdb --JobName="Test job monitoring" The spool file output is similar to the following: [job_id] [job_name] [step_id] [step_name] [step_uid] [date_created] [date_modified] [log_size] [log] [AD9AFEA6-9F6F-4BD1-B3EF-42C ] [Test job monitoring] [1] [step 1] [EEB A A44-02C11F9D1222] [ :50:51.833] [ :51:05.817] [2184] [Pinging 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 Password=3B38CA1614D Domain=OURDOMAIN --TargetDB=localdb --JobName="Test job monitoring" The spool file output is similar to the following: job (jobname=test job monitoring) has been cancelled successfully Chapter 2: Integrating with SQL Server Agent 23

24 Available Fields in Spool File Output by Operation Available Fields in Spool File Output by Operation 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 name enabled Specifies the name of the server the job belongs to. Specifies the name of the job. Indicates whether the job is enabled to be executed. description category owner Specifies the job description. Specifies the job category. 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 Specifies the unique ID for the job. originating_server Specifies the name of the server the job belongs to. 24 CLI User Guide

25 Available Fields in Spool File Output by Operation 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, 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. Chapter 2: Integrating with SQL Server Agent 25

26 Available Fields in Spool File Output by Operation on_success_action Specifies the action to take if the step succeeds. Options are as follows: Quits with success. Quits with failure. Goes to the next step. 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: on_fail_step_id server Quits with success. Quits with failure. Goes to the next step. Goes to the step indicated by the on_fail_step_id field. Indicates the next step to execute when the on_fail_action field is set to 4. 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. 26 CLI User Guide

27 Available Fields in Spool File Output by Operation 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: Indicates the step failed. Indicates the step succeeded. Indicates the step was canceled. 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. Chapter 2: Integrating with SQL Server Agent 27

28 Available Fields in Spool File Output by Operation 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. Note: By default, all the available fields are included in the output. The GetJobStatus 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. 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. 28 CLI User Guide

29 Available Fields in Spool File Output by Operation CurrentExecutionStatus Indicates the current execution status of the job. Options are as follows: Indicates that the job is executing. Indicates that the job is waiting for a thread. Indicates that the job is between retries. Indicates that the job is idle. Indicates that the job is suspended. Indicates that the job is performing completion actions. CurrentExecutionStep Specifies the step that is currently running. CurrentRetryAttempt Type Specifies the current retry attempt if the job is running and the step has been retried. Species the type of job. Options are as follows: Indicates that the job has no target servers. Indicates a local job. Indicates a multiserver job. Note: By default, all the available fields are included in the output. The GetJobHistory operation can display the following fields: instance_id Specifies the history entry identification number. Chapter 2: Integrating with SQL Server Agent 29

30 Available Fields in Spool File Output by Operation job_id Specifies the unique ID for the job. job_name step_id Specifies the name of the job. Specifies the job step ID. step_name Specifies the name of the step. 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_ ed Specifies the operator who was ed 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). 30 CLI User Guide

31 Available Fields in Spool File Output by Operation retries_attempted server Specifies the number of times the step was retried (always 0 for job history). 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 Specifies the name of the job. Specifies the job step ID. step_name step_uid Specifies the name of the step. Specifies the unique identifier of the step (system-generated) in the job. date_created Specifies the date that the step was created. date_modified log_size Log Specifies the date that the step was last modified. Specifies the size of the job step log in megabytes (MB). Specifies the job step log output. Note: By default, all the available fields are included in the output. Chapter 2: Integrating with SQL Server Agent 31

32

33 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. This section contains the following topics: 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. Chapter 3: Running the CLI Using Your Scheduling Manager 33

34 Integration with CA Workload Automation DE 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: 3. Click OK. Name get_job_list Agent WINAGENT Command to run wrappers\mssql_call.bat Arguments to pass --operation=getjoblist --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D Domain=OURDOMAIN 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 1. Create a Windows job in the Application. 2. Enter the following information in the Basic page of the job definition: 3. Click OK. Name get_job_detail Agent WINAGENT Command to run wrappers\mssql_call.bat Arguments to pass --operation=getjobdetail --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D Domain=MYDOMAIN --JobName=MYJOB After the job completes, you can retrieve the job details from the spool file. 34 CLI User Guide

35 Integration with CA Workload Automation DE 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) Target server database (MYDATABASE) User name (AUSER), password (3B38CA1614D55535), and domain (OURDOMAIN) Option to track the job to completion To run a predefined job 1. Create a Windows job in the Application. 2. Enter the following information in the Basic page of the job definition: 3. Click OK. Name run_job Agent WINAGENT Command to run wrappers\mssql_call.bat Arguments to pass --operation=runjob --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D Domain=OURDOMAIN --Track=Y When the job completes successfully, it indicates that MYJOB has completed successfully on SQL Server Agent. Chapter 3: Running the CLI Using Your Scheduling Manager 35

36 Integration with CA Workload Automation DE 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) Name of the SQL Server Agent job (MYJOB) Target server database (MYDATABASE) User name (AUSER), password (3B38CA1614D55535), and domain (OURDOMAIN) The time the job started running ( :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 1. Create a Windows job in the Application. 2. Enter the following information in the Basic page of the job definition: 3. Click OK. Name get_job_history Agent WINAGENT Command to run wrappers\mssql_call.bat Arguments to pass --operation=getjobhistory --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D Domain=OURDOMAIN --StartDateTime=" :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. For example, you can display the job step log of the MYJOB job using another Windows job. To display the job step log 1. Create a Windows job in the Application. 2. Enter the following information in the Basic page of the job definition: Name get_step_log Agent WINAGENT Command to run wrappers\mssql_call.bat Arguments to pass --operation=getsteplog --JobName=MYJOB --TargetDB=MYDATABASE --UserName=AUSER --Password=3B38CA1614D Domain=OURDOMAIN 36 CLI User Guide

37 Integration with CA Workload Automation AE 3. Click OK. After the job completes, you can retrieve job step log from the spool file. Integration with CA Workload Automation AE 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 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 command 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 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=3B38CA1614D Domain=OURDOMAIN Chapter 3: Running the CLI Using Your Scheduling Manager 37