From 42b24474eb8e9302093db78b716ed87845ba3e64 Mon Sep 17 00:00:00 2001 From: Roy Weesner Date: Fri, 25 Sep 2026 13:28:53 -0500 Subject: [PATCH] docs: correct job actions, Oracle client, installer log, and configuration Job actions: - MySQL and Oracle run script files only - Shared behavior: run-as account, encrypted values, environment variables, Encrypt Connection, client programs - MS SQL Job monitoring, retry and exit codes documented - Retry, Use Script Exit Code and MySQL port FAQs corrected Installation: SQL*Plus rather than SQLcl, client programs on the PATH, installer log name, instance names optional and port offset. Configuration, JORS, logging, scripts: service names, UseSmoApi reloads, AllowedIPAddress_5, SQL Agent folder name, JORS part of the agent service, environment-variable groups. Standards: landing-page front matter (link menu unchanged), window and interface wording, link extensions. Co-Authored-By: Claude Opus 5.5 --- docs/administration/configuration-file.md | 17 +++--- docs/administration/manage-agent.md | 2 +- docs/administration/scripts.md | 12 ++-- docs/administration/service-configuration.md | 8 +-- docs/advanced-features/jors.md | 17 ++---- docs/advanced-features/logging.md | 10 ++-- docs/index.md | 7 +++ docs/installation/multiple-instances.md | 8 ++- docs/installation/new-installation.md | 18 +++--- docs/installation/upgrade-installation.md | 2 +- docs/reference/job-actions.md | 58 +++++++++++++++----- docs/release-notes.md | 2 +- 12 files changed, 102 insertions(+), 59 deletions(-) diff --git a/docs/administration/configuration-file.md b/docs/administration/configuration-file.md index 091e9e7..be03bf9 100644 --- a/docs/administration/configuration-file.md +++ b/docs/administration/configuration-file.md @@ -20,7 +20,7 @@ The **SQLAgent.ini** file is the SQL Agent's configuration file. The agent reads - Tune logging and trace levels for troubleshooting. - Point the agent at initialization and termination scripts. -The SQLAgent.ini file lives in the `\SQLAgent\` directory. +The SQLAgent.ini file lives in the `\SQL Agent\` directory. :::note The Configuration Directory is set during installation and is based on where you installed your programs. For more information, refer to [File Locations](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/File%20Locations.htm) in the **Concepts** online help. @@ -40,7 +40,7 @@ If either socket value does not match its OpCon counterpart, jobs cannot start a To modify the SQLAgent.ini file, complete the following steps: -1. Open File Explorer and go to `\SQLAgent\` for the desired SQL Agent instance. +1. Open File Explorer and go to `\SQL Agent\` for the desired SQL Agent instance. 2. Right-click the **SQLAgent.ini** file and select **Open With**. 3. Select an ASCII text editor (such as Notepad) from the list. 4. Make the necessary modifications. For complete information on each setting, see the tables below. @@ -61,12 +61,14 @@ The basic settings for the SQL Agent. |[General Settings]|Default|Dynamic|Required|Description| |--- |--- |--- |--- |--- | -|DisplayServiceName|SMA OpCon Agent for SQL|N|Y|The service name displayed in the Service Control Manager. The name must be unique for each SQL Agent. Do not change this unless there is more than one agent on this physical machine.| -|ShortServiceName|SMA_SQLNET|N|Y|The hidden, internal (i.e., registry) service name SQL refers to. The name must be unique for each SQL Agent. Do not change this unless there is more than one agent on this physical machine.| +|DisplayServiceName|SMA SQL Agent (.NET)|N|Y|The service name displayed in the Service Control Manager. The installer registers the Windows service with the display name **SMA OpCon Agent for SQL**, which is the name shown in **Services**. The name must be unique for each SQL Agent. Do not change this unless there is more than one agent on this physical machine.| +|ShortServiceName|SMA_SQLAGENTNET|N|Y|The hidden, internal (i.e., registry) service name SQL refers to. For each additional instance, the installer appends the instance number (for example, `SMA_SQLAGENTNET1`). The name must be unique for each SQL Agent. Do not change this unless there is more than one agent on this physical machine.| |MaximumNumberOfJobs|50|Y|Y|Defines the maximum number of jobs the agent can simultaneously manage. When setting the MaximumNumberOfJobs, consider the SQL Agent machine's processor speed and memory (RAM) size. No job is processed when this setting is 0. Although the maximum value allowed is 500, typical customer usage ranges from 10 to 30 jobs.| |InitializationScript|Blank|N|N|The full path to the initialization script. The initialization script runs when the SQL Agent service starts. SMA Technologies recommends using this script to map network drives or to perform any other required initialization procedure. Enclose the path in double quotes ("*path*").| |TerminationScript|Blank|N|N|The full path to the termination script. The termination script runs when the SQL Agent service stops. SMA Technologies recommends using this script to disconnect network drives or to perform any other required termination procedure. Enclose the path in double quotes ("*path*").| +The shipped SQLAgent.ini also contains a **HungScript** setting in this section. How the agent uses it is not documented here. + ### TCP/IP parameters The network settings for the SQL Agent. @@ -78,10 +80,11 @@ Enter all alphabetic TCP/IP parameter values in uppercase. The SQL Agent service |[TCP/IP Parameters]|Default|Dynamic|Required|Description| |--- |--- |--- |--- |--- | |SocketNumberToSAM|21100|N|Y|Defines the socket number through which the agent and the SMANetCom communicate. This number must match the machine's socket number defined in Solution Manager or Enterprise Manager. If there are multiple agents installed on one machine, each agent must have a unique value. For an up-to-date list of unused ports, please refer to the Internet Assigned Numbers Authority at www.iana.org.| -|AllowedIPAddress_1|ANY|Y|N|Determines if communication from the SMANetCom to the agent is restricted to one or more TCP/IP addresses. If ANY is specified, the agent accepts communication from any TCP/IP address. If a specific TCP/IP address is defined (e.g., 126.40.90.231), the agent only accepts communication from the specified address. The agent refuses a connection if communication is attempted from another address. This definition enhances communication security by refusing communications from other TCP/IP addresses. If multiple SAMs are on a network, this address ensures the agent is only accepting messages from the intended SMANetCom. This parameter is case-sensitive.| +|AllowedIPAddress_1|ANY|Y|N|Determines if communication from the SMANetCom to the agent is restricted to one or more TCP/IP addresses. If ANY is specified, the agent accepts communication from any TCP/IP address. If a specific TCP/IP address is defined (for example, 192.0.2.10), the agent only accepts communication from the specified address. The agent refuses a connection if communication is attempted from another address. This definition enhances communication security by refusing communications from other TCP/IP addresses. If multiple SAMs are on a network, this address ensures the agent is only accepting messages from the intended SMANetCom. This parameter is case-sensitive.| |AllowedIPAddress_2|Blank|Y|N|Same as Address_1 explanation.| |AllowedIPAddress_3|Blank|Y|N|Same as Address_1 explanation.| |AllowedIPAddress_4|Blank|Y|N|Same as Address_1 explanation.| +|AllowedIPAddress_5|Blank|Y|N|Same as Address_1 explanation.| ### Debug options @@ -103,12 +106,12 @@ Settings for configuring JORS for job output retrieval. |JORSSocket|21110|N|Y|Defines the socket number through which the JORS Service communicates. This number must match the JORS Port Number defined in Solution Manager or Enterprise Manager under **Advanced Machine Settings** > **Communication Settings**. If there are multiple SQL Agents installed on one machine, each agent's JORS Service must have a unique port. For an up-to-date list of unused ports, please refer to the Internet Assigned Numbers Authority at www.iana.org.| |MaxJorsFileSize|65536|N|N|The maximum size of a Job Output file retrieved for viewing in OpCon. If the output file is larger than the MaxJorsFileSize, it is truncated when viewed. The minimum and default value is 65536 bytes (64 KB) and the maximum value is 52428800 bytes (50 MB). If an invalid value is specified, the file defaults to 65536.| |LogComposition|MIX|N|N|LogComposition only applies when a job output file larger than the MaxJorsFileSize is being viewed. **START** presents MaxJorsFileSize bytes from the start of the file. **END** presents MaxJorsFileSize bytes from the end of the file. **MIX** presents half of MaxJorsFileSize bytes from the start of the file and half from the end.| -|UseSmoApi|True|N|N|Determines how the agent retrieves output for MS SQL Server Agent jobs. When set to **True** (default), the agent uses the SMO (SQL Server Management Objects) API. When set to **False**, the agent uses a direct T-SQL call to the `sp_help_jobhistory` stored procedure instead. Set to **False** if SMO API performance is slow or unavailable in your environment.| +|UseSmoApi|True|Y|N|Not in the shipped file; add it to the JORS Settings section to change it. Determines how the agent retrieves output for MS SQL Server Agent jobs. When set to **True** (default), the agent uses the SMO (SQL Server Management Objects) API. When set to **False**, the agent uses a direct T-SQL call to the `sp_help_jobhistory` stored procedure instead. Set to **False** if SMO API performance is slow or unavailable in your environment.| ## FAQs **Where is the SQLAgent.ini file stored?** -The SQLAgent.ini file is stored in the `\SQLAgent\` directory. The Configuration Directory is set based on where you installed your programs. +The SQLAgent.ini file is stored in the `\SQL Agent\` directory. The Configuration Directory is set based on where you installed your programs. **Why won't my SQL Agent service start after editing SQLAgent.ini?** Check that all alphabetic TCP/IP parameter values are entered in uppercase. The SQL Agent service does not start if these values are in lowercase. diff --git a/docs/administration/manage-agent.md b/docs/administration/manage-agent.md index 5e7101e..9c70b35 100644 --- a/docs/administration/manage-agent.md +++ b/docs/administration/manage-agent.md @@ -28,7 +28,7 @@ Start the agent after a stop, after a reboot if the service did not auto-start, To start the SQL Agent, complete the following steps: 1. Go to **Start** > **Control Panel** > **Administrative Tools** > **Services**. -2. Select **SMA OpCon Agent for SQL** in the **Services** list. The **SMA OpCon Agent for SQL Properties** dialog displays. +2. Select **SMA OpCon Agent for SQL** in the **Services** list. The **SMA OpCon Agent for SQL Properties** window displays. 3. Confirm that the **Startup Type** is set to **Automatic (Delayed Start)**. If it is not, complete the following steps: 1. Select **Automatic (Delayed Start)** from the **Startup Type** list. 2. Select **OK**. diff --git a/docs/administration/scripts.md b/docs/administration/scripts.md index 60dacfe..f33b630 100644 --- a/docs/administration/scripts.md +++ b/docs/administration/scripts.md @@ -67,17 +67,17 @@ net send machine/username "Agent Stopped" ## Job environment variables -When the SQL Agent starts a cmd-based job (MS SQL Script, MySQL, Oracle, ODBC, OLE DB), it sets the following environment variables in the job's process environment. Scripts invoked as the job body (`.sql` or `.bat` files run by the agent) can read these variables. +When the SQL Agent starts a job that runs a command-line client (MS SQL Script, MS SQL DTExec, MySQL, Oracle), it sets the following environment variables in the job's process environment. MS SQL Job and Other DB (ODBC and OLE DB) jobs run inside the agent and do not receive them. Scripts invoked as the job body (`.sql` or `.bat` files run by the agent) can read these variables. :::caution Not available in InitializationScript or TerminationScript These variables are set per-job at the time a job process starts. InitializationScript and TerminationScript run at service start/stop — no job is running at that point, so none of these variables are available in those scripts. ::: -The agent sets two parallel groups of variables: one for the impersonated (batch) user context and one for the system account context. +The agent sets one of two groups of variables, depending on the account the job runs as: the `SMA_` group when the job runs as its Windows User ID, or the `SMA_MSLSAM_` group when it runs as the SQL Agent service account. A script that must work in both cases should check for both names. -### Impersonated user context +### Job runs as its Windows User ID -These variables are available in the impersonated user's process environment. +The agent sets these variables when the job definition has a **Windows User ID**. | Variable | Description | |---|---| @@ -88,9 +88,9 @@ These variables are available in the impersonated user's process environment. | `SMA_SCHEDULE_FREQ` | The schedule frequency name for the job. | | `SMA_JOBOUTPUT_FILENAME` | The full path to the job output file for the current run. | -### System account context +### Job runs as the service account -These variables are set in the system account's process environment. They carry the same values as the impersonated user context variables. +The agent sets these variables instead when the job has no **Windows User ID**, or when it begins with `USE SERVICE ACCOUNT`. They carry the same information as the `SMA_` group. | Variable | Description | |---|---| diff --git a/docs/administration/service-configuration.md b/docs/administration/service-configuration.md index e175739..b79dbaa 100644 --- a/docs/administration/service-configuration.md +++ b/docs/administration/service-configuration.md @@ -19,7 +19,7 @@ The SQL Agent service can run under two different account types, and the choice In Local System mode, select a Windows User account from your network for the Windows User ID in the job definition in Solution Manager. -For information on configuring mapped network drives in the SQLAgent.ini file, see [Using the InitializationScript and TerminationScript](scripts). For information on adding a batch user for SQL, refer to [Adding a Batch User for SQL](https://help.smatechnologies.com/opcon/core/rolling/Files/UI/Enterprise-Manager/Adding%20Batch%20Users.htm#Adding2) in the **OpCon** online help. +For information on configuring mapped network drives in the SQLAgent.ini file, see [Using the InitializationScript and TerminationScript](scripts.md). For information on adding a batch user for SQL, refer to [Adding a Batch User for SQL](https://help.smatechnologies.com/opcon/core/rolling/Files/UI/Enterprise-Manager/Adding%20Batch%20Users.htm#Adding2) in the **OpCon** online help. ## Run the SQL Agent as the Local System Account @@ -36,7 +36,7 @@ The Local System Account must have the following advanced Windows privileges: To configure the SQL Agent to run as a Local System Account, complete the following steps: 1. Go to **Start** > **Control Panel** > **Administrative Tools** > **Services**. -2. Select the SQL Agent service from the **Services** list. The **Properties** dialog displays. +2. Select the SQL Agent service from the **Services** list. The **Properties** window displays. 3. If not selected already, select **Automatic (Delayed Start)** from the **Startup Type** list. 4. Select the **Log On** tab. 5. Select the **Local System account** option. @@ -72,7 +72,7 @@ To add the required advanced Windows privileges, complete the following steps: 1. Go to **Start** > **Control Panel** > **Administrative Tools** > **Local Security Policy**. 2. Under **Security Settings**, select **Local Policies** > **User Rights Assignment**. 3. For each privilege in the list above, select the privilege and select **Add User Or Group**. -4. In the **Select Users Or Groups** dialog, select **Locations** and choose the machine or domain depending on whether you are adding a local user or a domain user. +4. In the **Select Users Or Groups** window, select **Locations** and choose the machine or domain depending on whether you are adding a local user or a domain user. 5. In the object name field, enter the name of the user. To add the Local System Account, choose the current machine and enter `SYSTEM`. 6. Repeat steps 3 through 5 for each privilege. @@ -81,7 +81,7 @@ To add the required advanced Windows privileges, complete the following steps: To configure the SQL Agent to run as a Domain User, complete the following steps: 1. Go to **Start** > **Control Panel** > **Administrative Tools** > **Services**. -2. Select the SQL Agent service from the **Services** list. The **Properties** dialog displays. +2. Select the SQL Agent service from the **Services** list. The **Properties** window displays. 3. If not selected already, select **Automatic (Delayed Start)** from the **Startup Type** list. 4. Select the **Log On** tab. 5. Select the **This account** option. diff --git a/docs/advanced-features/jors.md b/docs/advanced-features/jors.md index 1cb2f71..b3de8d2 100644 --- a/docs/advanced-features/jors.md +++ b/docs/advanced-features/jors.md @@ -12,7 +12,7 @@ tags: ## What is it? -The **Job Output Retrieval System (JORS)** is a Windows service that captures the output (stdout/stderr plus job metadata) generated by each job that runs through the SQL Agent. JORS gives operators a way to see what a job actually produced — useful for: +The **Job Output Retrieval System (JORS)** captures the output (standard output and error output, plus job metadata) generated by each job that runs through the SQL Agent. JORS is part of the SQL Agent service; the installer does not create a separate JORS service. JORS gives operators a way to see what a job actually produced — useful for: - Diagnosing job failures and runtime errors. - Confirming that a job did the work it was supposed to do. @@ -25,8 +25,7 @@ JORS communicates with OpCon over a port configured in SQLAgent.ini. The configu For each job, JORS captures: - **Internal Job Name** -- **STDOUT** generated by the job -- **STDERR** generated by the job +- **STDOUT** and **STDERR** generated by the job, written to the same file - **Job Start/End Time** - **Job Process Name and PID** - **Job ExitCode** @@ -35,10 +34,9 @@ For each job, JORS captures: The agent creates one log file per job containing all of the captured information. -| Phase | Location | +| Location | Notes | |---|---| -| While the job is running | `\SQLAgent\JobOutput\` | -| After the job completes | `\SQLAgent\JobOutput\Archives\\` | +| `\SQL Agent\JobOutput\Archives\\` | `` is the date the job started, in the form `yyyy_MM_dd (Weekday)`. The agent writes the file there while the job runs. | :::note The Output Directory was set during installation. For more information, refer to [File Locations](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/File%20Locations.htm) in the **Concepts** online help. @@ -48,11 +46,8 @@ The SQL Agent cleans up archived JobOutput folders based on the **ArchiveDaysToK ## FAQs -**Where are job output files stored while a job is running?** -While the job is running, the output is stored in the JobOutput folder. - -**Where are job output files moved after a job completes?** -Once the job completes, the output is saved under `\SQLAgent\JobOutput\Archives\`. +**Where are job output files stored?** +The agent writes each job's output file under `\SQL Agent\JobOutput\Archives\`, in a folder named for the date the job started, in the form `yyyy_MM_dd (Weekday)`. **How long are archived job outputs kept?** The SQL Agent removes archived JobOutput folders based on the ArchiveDaysToKeep setting under Debug Options. Logs older than ArchiveDaysToKeep are cleaned up at midnight. diff --git a/docs/advanced-features/logging.md b/docs/advanced-features/logging.md index a0a2704..2294352 100644 --- a/docs/advanced-features/logging.md +++ b/docs/advanced-features/logging.md @@ -19,7 +19,7 @@ The SQL Agent and its supporting components write log files that record service - Trace SMANetCom messages while troubleshooting. - Investigate intermittent failures. -Logs reside in the `\SQLAgent\Log\` directory. The Output Directory was set during installation. +Logs reside in the `\SQL Agent\Log\` directory. The Output Directory was set during installation. :::note For more information about file locations, refer to [File Locations](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/File%20Locations.htm) in the **Concepts** online help. @@ -32,11 +32,11 @@ For more information about file locations, refer to [File Locations](https://hel | **SQLAgent.log** | Agent processing information. Configuration is also written here at startup and whenever the SQL Agent detects a change to SQLAgent.ini. | | **SQLAgentTrace.log** | Detailed diagnostic messages. Only written when tracing is activated. | -For details on enabling tracing and tuning log size, see [Debug options](../administration/configuration-file#debug-options) in the SQLAgent.ini reference. +For details on enabling tracing and tuning log size, see [Debug options](../administration/configuration-file.md#debug-options) in the SQLAgent.ini reference. ## Log archiving -When a log file reaches the configured maximum size, the SQL Agent archives it. Archived logs live in `\SQLAgent\Log\Archives\`. +When a log file reaches the configured maximum size, the SQL Agent archives it. Archived logs live in `\SQL Agent\Log\Archives\`. ### Archive folder layout @@ -44,7 +44,7 @@ A folder exists in **Archives** for each day the SQL Agent processes. Folders us ### Archive file naming -As each log file fills up, the SQL Agent moves it into the current archive folder and renames it using the convention `LogName StartTime - StopTime.log`. For example, an archive file for the time range of 12:58:16 to 13:58:00 would be `SMAAgent 125816 - 135800.log`. +As each log file fills up, the SQL Agent moves it into the current archive folder and renames it using the convention `LogName StartTime - StopTime.log`. For example, an archive file for the time range of 12:58:16 to 13:58:00 would be `SQLAgent 125816 - 135800.log`. ### Retention @@ -57,7 +57,7 @@ The SQL Agent does not purge an archive folder if it contains any files other th ## FAQs **Where do SQL Agent log files live?** -Log files reside in the `\SQLAgent\Log\` directory. The Output Directory is set during installation. +Log files reside in the `\SQL Agent\Log\` directory. The Output Directory is set during installation. **How long are archived logs kept by default?** By default, the SQL Agent retains 10 days of archived logs. To change this, configure the SQLAgent.ini file. diff --git a/docs/index.md b/docs/index.md index dce4ee4..a5b8121 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,13 @@ --- slug: '/' sidebar_label: 'SQL Agent' +title: SQL Agent +description: "OpCon agent that allows OpCon to schedule SQL queries or jobs within a Windows environment against databases such as MS SQL Server, MySQL, Oracle, ODBC/OLE DB, and SSIS. Covers installation, administration, advanced features, and reference." +tags: + - Conceptual + - System Administrator + - Automation Engineer + - Agents hide_table_of_contents: true displayed_sidebar: null --- diff --git a/docs/installation/multiple-instances.md b/docs/installation/multiple-instances.md index 398fdd5..72cf01f 100644 --- a/docs/installation/multiple-instances.md +++ b/docs/installation/multiple-instances.md @@ -12,7 +12,7 @@ tags: ## What is it? -You can install more than one instance of the SQL Agent on a single machine. Each instance must have a unique instance name and port number so OpCon can communicate with each one independently. Use multiple instances when: +You can install more than one instance of the SQL Agent on a single machine. Each instance must have its own port numbers so OpCon can communicate with each one independently. The installer numbers each instance; an instance name is optional. Use multiple instances when: - You need to isolate jobs running against different databases or environments. - Different agent instances must run under different service accounts. @@ -26,10 +26,12 @@ To install an additional SQL Agent instance, complete the following steps: 1. Repeat the [Install the SQL Agent](new-installation.md#install-the-sql-agent) procedure. The installation package automatically transforms to install a new instance of the agent. - :::tip Use a unique instance name and port - On the **Configure Instance Name** screen, enter a name that distinguishes this instance from the others. On the **Configure Ports** screen, set port values that are not already in use by another agent on the machine. + :::tip Instance name and ports + On the **Configure Instance Name** screen, you can enter a name that distinguishes this instance from the others. On the **Configure Ports** screen, if you keep the default ports, the installer adds 100 × the instance number to them — for example, `21200` and `21210` for instance 1. Confirm that no other agent on the machine uses the ports this instance gets. ::: + The installer registers each additional instance's service as `SMA_SQLAGENTNET`, where `` is the instance number. + 2. Define a new machine in OpCon with a unique name and port number using the procedure for [Machine creation](new-installation.md#machine-creation). The socket number you set in OpCon must match the port you chose in the installer. ## Related topics diff --git a/docs/installation/new-installation.md b/docs/installation/new-installation.md index be13a5b..dfaa5c0 100644 --- a/docs/installation/new-installation.md +++ b/docs/installation/new-installation.md @@ -30,11 +30,15 @@ Before you start the installer, make sure the machine has: - **Local Administrator** sign-in rights for the Windows user running the installer. - **.NET Framework 4.8** installed on the machine. The installer will install it if it is not already present. - **The OpCon installation media** containing the **SMA OpCon Agent for SQL Install**.exe file. -- **A management studio or command-line client** for the database the agent will run jobs against. +- **The command-line client** for each database the agent will run jobs against, installed and on the PATH of the account each job runs as. A management studio on its own is not enough. -:::tip Examples of supported clients -- **MS SQL Server**: SQL Server Management Studio or `SQLCMD.exe`. -- **Oracle**: SQLcl. +:::tip Client programs the agent runs +- **MS SQL Script**: `SqlCmd.exe` +- **MS SQL DTExec**: `DtExec.exe` +- **MySQL**: `MySql.exe` +- **Oracle**: SQL*Plus (`SqlPlus.exe`). SQLcl is not used. + +MS SQL Job and Other DB jobs connect from inside the agent and need no client program. ::: ## Install the SQL Agent @@ -80,7 +84,7 @@ To run the installation, complete the following steps: 5. Select **Finish** on the **InstallShield Wizard Completed** screen. :::note Troubleshooting -The installer writes a log file named **SMA_OpCon_SQL_Agent_Install.log** to the Windows directory. Consult this file if you suspect any installation problems. +The installer writes a log file named **SMA_OpCon_Agent_SQL_Install.log** to the Windows directory. Consult this file if you suspect any installation problems. ::: ## Service startup setup @@ -98,7 +102,7 @@ Use the procedure below if you need to change the startup type or the account th To set up service startup, complete the following steps: 1. Go to **Start** > **Control Panel** > **Administrative Tools** > **Services**. -2. Select the newly installed **SMA OpCon Agent for SQL** service. The **SMA OpCon Agent for SQL Properties** dialog displays with the **General** tab in focus. +2. Select the newly installed **SMA OpCon Agent for SQL** service. The **SMA OpCon Agent for SQL Properties** window displays with the **General** tab in focus. 3. Select the **Service Startup type**: - **Automatic (Delayed Start)** *(recommended)* - **Automatic** @@ -116,7 +120,7 @@ After the agent is installed, create a machine record in OpCon so the scheduler ### Create the machine in OpCon -Select the tab for your OpCon client and complete the sub-procedures in order. +Select the tab for your OpCon interface and complete the sub-procedures in order. diff --git a/docs/installation/upgrade-installation.md b/docs/installation/upgrade-installation.md index bf59512..777fd2c 100644 --- a/docs/installation/upgrade-installation.md +++ b/docs/installation/upgrade-installation.md @@ -122,7 +122,7 @@ To run the upgrade, complete the following steps: 6. Reconfigure the service "Log on as" settings using the credentials you captured in *Before you begin*. :::note Troubleshooting -The installer writes a log file named **SMA_OpCon_SQL_Agent_Install.log** to the Windows directory. Consult this file if you suspect any installation problems. +The installer writes a log file named **SMA_OpCon_Agent_SQL_Install.log** to the Windows directory. Consult this file if you suspect any installation problems. ::: ## Restart the service diff --git a/docs/reference/job-actions.md b/docs/reference/job-actions.md index 80147f5..c0be610 100644 --- a/docs/reference/job-actions.md +++ b/docs/reference/job-actions.md @@ -30,14 +30,26 @@ For the full field-by-field reference, see [SQL Job Details](https://help.smatec | [MS SQL DTExec](#ms-sql-dtexec) | Running SSIS packages with `dtexec` | [Fields for MS SQL DTExec](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_MS_SQL_DTExec) | | [MS SQL Job](#ms-sql-job) | Triggering SQL Server Agent jobs | [Fields for MS SQL Job](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_MS_SQL_Job) | | [MS SQL Script](#ms-sql-script) | Running ad-hoc T-SQL or script files | [Fields for MS SQL Script](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_MS_SQL_Script) | -| [MySQL](#mysql) | Running queries or scripts against MySQL | [Fields for MySQL](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_MySQL) | -| [Oracle](#oracle) | Running queries or scripts against Oracle | [Fields for Oracle](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_Oracle) | +| [MySQL](#mysql) | Running script files against MySQL | [Fields for MySQL](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_MySQL) | +| [Oracle](#oracle) | Running script files against Oracle with SQL*Plus | [Fields for Oracle](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_Oracle) | | [Other DB](#other-db) | ODBC or OLE DB connections to any other database | [Fields for Other DB](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_Other_DB) | :::tip How to use this page Each job-type section uses **tabs** to switch between configuration variants. Pick the tab that matches your scenario rather than scrolling through every variant. ::: +## How the agent runs every job action + +These rules apply across the job actions. Differences between actions are noted in each section. + +| Topic | Behavior | +|---|---| +| Account the job runs as | If the job's **Windows User ID** is set, the job runs as that Windows user and the **Password** field holds that user's Windows password. The agent does not pass a database password in that case. If **Windows User ID** is empty, or begins with `USE SERVICE ACCOUNT`, the job runs as the SQL Agent service account. | +| Encrypted values | Any part of the server name, password, database name, script statements, script path, output file path, other options, Oracle parameters, connection string, or environment variable names and values can be entered between `` and ``. The agent decrypts each such part before it builds the command. | +| Environment variables | Each action uses them differently: MS SQL Script sets them in the job's process environment; MySQL defines each one as a MySQL user variable (`@NAME`); Other DB replaces `$(NAME)` in the script text with the value; Oracle and MS SQL DTExec do not use them. | +| Encrypt Connection | Applies to MS SQL Script only, where the agent adds `-N` to the `sqlcmd` command line. The other actions do not use it. | +| Client programs | MS SQL Script, MS SQL DTExec, MySQL, and Oracle run `SqlCmd.exe`, `DtExec.exe`, `MySql.exe`, and `SqlPlus.exe`. Each program must be installed and on the PATH of the account the job runs as. Other DB and MS SQL Job connect from inside the agent. | + --- ## MS SQL DTExec @@ -102,6 +114,23 @@ Start and monitor a job, overriding the saved credentials with a password suppli +### How the agent monitors an MS SQL Job + +- **Monitor only.** When the job definition is set to monitor only, the agent does not start the SQL Server Agent job. It watches the job and reports its outcome. For every MS SQL Job, the agent checks the job's status every 10 seconds. +- **Monitor end time.** The end time is a number of hours after the start of the schedule date. When that time is reached, the agent reports the OpCon job as finished with exit code `0`, even if the SQL Server Agent job is still running. The SQL Server Agent job is not stopped. +- **Retry Attempts.** If the agent connects but the SQL Server is not available, it waits 5 minutes and tries again, up to the number of retry attempts in the job definition (default `0`). An error while connecting is not retried. The 5-minute wait is fixed. + +The agent reports the SQL Server Agent job's outcome as the exit code: + +| Exit code | SQL Server Agent job outcome | +|---|---| +| `0` | Succeeded | +| `1` | Failed | +| `2` | Retry | +| `3` | Cancelled | +| `4` | In progress | +| `5` | Unknown | + --- ## MS SQL Script @@ -141,7 +170,7 @@ Specifies an output file path and applies a password overwrite at runtime. -Authenticates with the agent's Windows account and runs a script from a `.sql` file. +Uses a trusted Windows connection and runs a script from a `.sql` file. The connection uses the job's Windows User ID, or the SQL Agent service account when no Windows User ID is set. ![Defining MS SQL Script with Windows Authentication and Script File](../static/img/Defining-MS-SQL-Script-with-Windows-Authentication-and-Script-File.png "Defining MS SQL Script with Windows Authentication and Script File") @@ -149,23 +178,23 @@ Authenticates with the agent's Windows account and runs a script from a `.sql` f :::note UseScriptExitCode -When the **Use Script Exit Code** option is enabled and the job uses an **inline script statement**, the agent wraps the statement in `EXIT(statement)` when calling `sqlcmd`, causing `sqlcmd` to return the query result as its process exit code. This option has no effect when the job uses a script file path instead of an inline statement. +When the **Use Script Exit Code** option is enabled and the job uses an **inline script statement**, the agent wraps the statement in `EXIT(statement)` when calling `sqlcmd`, causing `sqlcmd` to return the query result as its process exit code. This option has no effect when the job uses a script file path instead of an inline statement. In every case, the job's exit code is the `sqlcmd` exit code; the agent always adds `-b`, so `sqlcmd` returns an error exit code when a statement fails. ::: :::note EncryptConnection -When the **Encrypt Connection** option is enabled in the job definition, the agent adds the `-N` flag to the `sqlcmd` command line, which tells `sqlcmd` to use an encrypted connection for the SQL Server session. +When the **Encrypt Connection** option is enabled in the job definition, the agent adds the `-N` flag to the `sqlcmd` command line, which tells `sqlcmd` to use an encrypted connection for the SQL Server session. The option applies to MS SQL Script only. ::: --- ## MySQL -Run queries or scripts against MySQL. The example tabs show the most common configurations. +Run a script file against MySQL. The agent runs the file in **Script File Path**; it does not run statements entered in the job definition. The example tabs show the most common configurations. For the field reference, see [Fields for MySQL](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_MySQL) in the **Concepts** online help. :::note MySQL default port -When no port is specified in the job definition, the agent connects to MySQL on the default port **3306**. +When no port is specified in the job definition, the agent does not pass a port to `MySql.exe`, so the MySQL client's own default port is used. ::: @@ -185,7 +214,7 @@ Overrides the saved password at runtime. -Runs a script file and substitutes environment variables into the SQL. +Runs a script file with environment variables. The agent defines each variable as a MySQL user variable before it runs the script, so the script refers to it as `@NAME`. **Script File Path:** `C:\SQLScripts\mysql_insert_params.sql` @@ -204,7 +233,7 @@ Insert into address (Lastname, Firstname, Address) values (@LN, @FN, @ADS); ## Oracle -Run jobs against Oracle. The tabs cover the most common parameter and connection patterns. +Run a script file against Oracle with SQL*Plus (`SqlPlus.exe`). The agent runs the file in **Script File Path**; it does not run statements entered in the job definition. The tabs cover the most common parameter and connection patterns. For the field reference, see [Fields for Oracle](https://help.smatechnologies.com/opcon/core/rolling/Files/Concepts/SQL-Job-Details.md#Fields_for_Oracle) in the **Concepts** online help. @@ -232,7 +261,7 @@ Passes encrypted parameters into the Oracle job. -References a saved Oracle connection by ID rather than entering the connection details inline. +Adds the Connection ID to the connection. With a **Server Name**, a numeric Connection ID is used as the port (`:`). Without a **Server Name**, the Connection ID is used as the Oracle connect identifier (`@`). ![Defining Oracle with Connection ID](../static/img/Defining-Oracle-with-Connection-ID.png "Defining Oracle with Connection ID") @@ -350,13 +379,16 @@ ODBC connection string with an in-line script and environment variables. Use **MS SQL Job** to trigger and monitor a pre-existing SQL Server Agent job. Use **MS SQL Script** to run T-SQL directly via `sqlcmd` — either an in-line script or a `.sql` file. MS SQL Script does not require a pre-existing SQL Server Agent job. **How does the agent retry a failed connection?** -Retry behavior is configured per job in the job definition's **Retry Attempts** field (default: **0**). When a retry is triggered, the agent waits **5 minutes** between each attempt. The retry count and sleep interval are job-level settings, not agent-level settings. +Only MS SQL Job jobs retry. If the agent connects but the SQL Server is not available, it waits 5 minutes and tries again, up to the job definition's **Retry Attempts** (default: **0**). The 5-minute wait is fixed. An error while connecting is not retried. See [How the agent monitors an MS SQL Job](#how-the-agent-monitors-an-ms-sql-job). **What port does MySQL use if I leave the port field blank?** -The agent connects on the MySQL default port **3306** when no port is specified in the job definition. +The agent does not pass a port, so the MySQL client uses its own default port. **What does "Use Script Exit Code" do for MS SQL Script jobs?** -When enabled and the job uses an inline script statement, the agent wraps that statement in `EXIT(statement)` when calling `sqlcmd`, causing `sqlcmd`'s process exit code to reflect the query result. When disabled, or when the job uses a script file path, the agent uses its own internal exit code logic. +When enabled and the job uses an inline script statement, the agent wraps that statement in `EXIT(statement)` when calling `sqlcmd`, causing `sqlcmd`'s process exit code to reflect the query result. In every other case the job's exit code is still the `sqlcmd` exit code. + +**Can MySQL or Oracle jobs run statements entered in the job definition?** +No. For MySQL and Oracle, the agent runs only the script file in **Script File Path**. Put the statements in a script file. ## Related topics diff --git a/docs/release-notes.md b/docs/release-notes.md index 48cc119..35466d6 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -181,7 +181,7 @@ This release adds Windows Authentication support for SSIS packages and support f #### New features -- **Added Windows Authentication support for MS SQL DTExec jobs.** SSIS packages run via `dtexec` can now authenticate using the Windows account of the executing user rather than requiring SQL Server credentials. +- **Added Windows Authentication support for MS SQL DTExec jobs.** SSIS packages run via `dtexec` can now authenticate using the Windows account of the user running the job rather than requiring SQL Server credentials. - **Added Integration Services Server (ISSERVER) support for MS SQL DTExec jobs.** SSIS packages stored on an Integration Services Server can now be run directly from OpCon. #### Bug fixes