SAPLSAM.ini configuration file
What is it?
SAPLSAM.ini is the configuration file the SAP Agent reads at startup and re-reads when changes are detected. It controls how the agent identifies itself as a Windows service, how it communicates with OpCon, how it connects to the SAP system, and how it handles job tracking, output retrieval, and logging.
The file lives in the <Configuration Directory>\SAP LSAM\ directory.
The Configuration Directory is based on where you installed your programs. For more information, refer to File Locations in the Concepts online help.
How to read this page
Each section below documents one section of the SAPLSAM.ini file. Tables list every setting in that section with the same four-column reference layout.
Column meanings
| Column | What it means |
|---|---|
| Default | The value SAPLSAM.ini ships with. Blank means the value is empty by default. |
| Dynamic | Y = the agent picks up a change without a restart. N = you must restart the SAP Agent service after changing this value. |
| Required | Y = the setting must have a value for the agent to start or function. N = the setting is optional. |
| Description | What the setting does and any constraints. |
Conventions
- Section headings in SAPLSAM.ini are written
[Section Name]in the file itself, but appear without brackets in this reference. - Alphabetic values in TCP/IP Parameters and Debug Options must be uppercase. The service does not start if they are lowercase.
- See Modify the SAPLSAM.ini file before making any changes.
Sections in SAPLSAM.ini
| Section | Purpose |
|---|---|
| General settings | Service name, concurrency, polling, output retrieval limits |
| TCP/IP parameters | Communication ports and IP allowlist for SMANetCom |
| Process creation parameters | Whether and how the agent saves job output |
| Debug options | Log size, archive retention, and trace levels |
| SAP system settings | Connection details, credentials, and XBP version |
| Job Track/Queue settings | Definitions for tracking or queuing SAP-initiated jobs |
| JORS settings | Socket used by the JORS service to deliver output to the EM |
Critical settings to verify first
Three settings must be correct before the SAP Agent can do useful work. Verify these first when troubleshooting a brand-new install or a service that won't start.
| Setting | Section | Why it matters |
|---|---|---|
| MaximumNumberOfJobs | General settings | If set to 0, no jobs run on this agent. |
| SocketNumberToSAM | TCP/IP parameters | Must match the Socket Number on the OpCon machine record so SMANetCom can reach the agent. |
| JORSSocket | JORS settings | Must match the JORS Port Number on the OpCon machine record so the EM can retrieve job output. |
Procedures
Modify the SAPLSAM.ini file
To modify the SAPLSAM.ini file, complete the following steps:
- Right-click the Start button and select Explore from the menu.
- Browse to
<Configuration Directory>\SAP LSAM\for the desired SAP Agent instance. - Right-click the SAPLSAM.ini file and select Open With.
- Select an ASCII text editor (for example, Notepad) from the Choose the program you want to use list box.
- Edit the settings you need to change. For complete information on each setting, see the section reference tables below.
- Go to File > Save.
- Close the text editor.
If you only changed dynamic settings (marked Y in the Dynamic column), the agent picks up the change automatically. If any non-dynamic setting changed, restart the SAP Agent service. See Managing the SAP Agent.
Encrypt credentials in SAPLSAM.ini
The SAP User and Password values, and the ExternalEventUser and ExternalEventPassword values, must be entered as encrypted strings in SAPLSAM.ini. All four use the same encryption tool and the same procedure — only the target field in SAPLSAM.ini differs.
The Password encryption tool is available only in the Enterprise Manager. There is no equivalent tool in Solution Manager at this time.
Generate an encrypted value
To generate an encrypted value, complete the following steps:
- Log on to the Enterprise Manager.
- Go to Enterprise Manager > Password Update > Password encryption tool.
- (Optional) Select the Visible option to show the password characters.
- In the Password field, enter the user name or password you want to encrypt.
- Select Encrypt.
- Select Copy to Clipboard.
Paste the encrypted value into SAPLSAM.ini
To paste the encrypted value into SAPLSAM.ini, complete the following steps:
-
Open
SAPLSAM.ini— see Modify the SAPLSAM.ini file. -
Locate the target field:
Encrypting Target field Section The SAP login user name User SAP System The SAP login password Password SAP System The external event user ExternalEventUser General Settings The external event password ExternalEventPassword General Settings -
Delete the existing value for the target field.
-
Paste the encrypted value (right-click and select Paste, or press CTRL+V).
-
Save and close the file.
Repeat both procedures for each value you need to encrypt.
Setting reference
General settings
Basic identity, concurrency, polling, and output-size settings for the SAP Agent.
| Setting | Default | Dynamic | Required | Description |
|---|---|---|---|---|
| DisplayServiceName | SMA OpCon Agent for SAP | N | Y | The service name displayed in the Service Control Manager. Must be unique per SAP Agent on the host. Do not change unless more than one agent is installed on the same machine. |
| ShortServiceName | SMA_SAPLSAM | N | Y | The hidden internal (registry) service name Windows uses. Must be unique per SAP Agent on the host. Do not change unless more than one agent is installed on the same machine. |
| MaximumNumberOfJobs | 10 | Y | Y | Maximum number of jobs the SAP Agent can process concurrently. Consider the host's CPU and memory. 0 means no jobs run. The agent does not enforce a maximum; typical range is 10 to 30. When the value changes, the agent sends the new limit to OpCon. |
| JobStatusCheckInterval | 30 | N | Y | Seconds between SAP polls for each job's status. Supported range: 5 to 300. The agent does not enforce the range. |
| MaxSpoolSizeToRetrieve | 1000000 | N | N | Maximum spoollist size in bytes to retrieve when Version is 3.0. Spoollists larger than this are not retrieved and are not available through View Job Output. |
| MaxJobLogSizeToRetrieve | 1000000 | N | N | Maximum job log size in bytes to retrieve. Job logs larger than this are not retrieved and are not available through View Job Output. |
| CaptureOutputBeforeJobFin | False | N | N | When True, the agent reports final job status to SAM as soon as the SAP job finishes, then captures the joblog and spool. The trade-off: View Job Output may not be immediately available because the agent is still gathering logs. Valid values: True, False. |
| BapiResponseTimeout | 300 | N | Y | Seconds to wait for any BAPI call into the SAP system. If the call does not respond within this time, the connection is treated as dead and a new connection is attempted. Valid range: 30 to 600. |
| ExternalEventUser | (blank) | N | N | The OpCon user the agent sends external events as. Enter the value encrypted — see Encrypt credentials in SAPLSAM.ini. The agent ignores a value it cannot decrypt, including a plain-text value. |
| ExternalEventPassword | (blank) | N | N | The password for the external event user. Enter the value encrypted — see Encrypt credentials in SAPLSAM.ini. The agent ignores a value it cannot decrypt, including a plain-text value. |
| JobCopyDelay | 1 | N | N | Seconds the agent waits before copying an SAP job. Not in the shipped file; the agent uses 1 when it is absent or 0. |
| JobStartDelay | 1 | N | N | Seconds the agent waits before starting an SAP job. Not in the shipped file; the agent uses 1 when it is absent or 0. |
| CaptureJobStatistics | FALSE | N | N | When TRUE, the agent writes the SAP job's statistics and application information to the job log. Valid values: TRUE, FALSE. |
The shipped SAPLSAM.ini spells this setting CaputeJobStatistics. The agent does not read that line. To turn job statistics on, add CaptureJobStatistics=TRUE to the General Settings section.
TCP/IP parameters
Communication ports and an optional IP allowlist for traffic from SMANetCom.
Enter all alphabetic TCP/IP parameter values in uppercase. The SAP Agent service does not start if the values are in lowercase.
| Setting | Default | Dynamic | Required | Description |
|---|---|---|---|---|
| SocketNumberToSAM | 13100 | N | Y | The socket the SAP Agent and SMANetCom communicate on. Must match the Socket Number on the OpCon machine record. Each agent on the same host must have a unique value. For unused-port guidance, see the Internet Assigned Numbers Authority. |
| QueryListenerPort | 13101 | N | N | The port the SAP Agent listens on for proxy requests. Open this port in the host firewall. |
| AllowedIPAddress_1 | ANY | Y | N | Restricts SMANetCom traffic to one or more TCP/IP addresses. ANY accepts traffic from any source. A specific address (for example, 192.0.2.10) restricts traffic to that source. The agent rejects connections from any other address. Useful when multiple SAMs share a network. Case-sensitive. |
| AllowedIPAddress_2 | (blank) | Y | N | Same behavior as AllowedIPAddress_1. |
| AllowedIPAddress_3 | (blank) | Y | N | Same behavior as AllowedIPAddress_1. |
| AllowedIPAddress_4 | (blank) | Y | N | Same behavior as AllowedIPAddress_1. |
| AllowedIPAddress_5 | (blank) | Y | N | Same behavior as AllowedIPAddress_1. |
Process creation parameters
Process creation options for SAP chains.
| Setting | Default | Dynamic | Required | Description |
|---|---|---|---|---|
| CaptureJobOutput | TRUE | Y | N | When TRUE, the agent saves each job's log and spool in the JobOutput folder beside its Log folder, as <SAP job name>#<SAP job count>.log and .spool, and moves them to JobOutput\Archives\<date> when the job ends. View Job Output works only when this is TRUE. |
Debug options
Log size, archive retention, and trace verbosity for troubleshooting.
Enter all alphabetic debug option parameter values in uppercase. The SAP Agent services do not start if the values are in lowercase.
| Setting | Default | Dynamic | Required | Description |
|---|---|---|---|---|
| MaximumLogFileSize | 150000 | Y | N | Maximum size in bytes per agent log file. Forces rotation so a single file does not grow unbounded. Site-specific. |
| ArchiveDaysToKeep | 10 | Y | N | How many archive folders to retain. The agent purges expired folders during each archive. |
| TraceSAMMessages | ON | N | N | Enables tracing of messages between the agent and SMANetCom into SAPLSAMTrace.log. Valid values: ON, OFF. |
| TraceLevel | 0 | Y | N | Verbosity of debug messages. 0 = failures only (minimal). 1 = additional debug. 2 = detailed debug. |
SAP system settings
Connection details, credentials, and XBP version for the SAP system the agent talks to.
| Setting | Default | Dynamic | Required | Description |
|---|---|---|---|---|
| Name | SAPSYSTEM | N | Y | The name of the SAP machine as defined in the OpCon Enterprise Manager (EM). |
| ClientID | 0 | N | Y | Client ID for the SAP system connection. Valid values: three-digit numbers 000 to 999. |
| Gateway | /H/127.0.0.1/H/test801 | N | Y | The full SAP connection string. A standard TCP/IP address works for SAP machines on a network. ISDN or other links require a router connection string (for example, /H/127.0.0.1/H/cpce801, where cpce801 is the SAP machine name and 127.0.0.1 is its IP address). |
| SystemNumber | 0 | N | Y | The system number for the SAP system connection. Valid values: two-digit numbers 00 to 99. |
| R3Name | (blank) | N | N | When Gateway uses an MSHOST, this defines the SAP R/3 instance name. |
| Group | (blank) | N | N | When Gateway uses an MSHOST, this optionally defines the SAP server group for a load-balancing connection. |
| RFCTrace | 0 | N | Y | Enables SAP RFC tracing. 0 = off. 1 = on. |
| User | (blank) | N | Y | The SAP user the agent connects as. Must hold the S_XMI_ALL privilege. Encrypt this value — see Encrypt credentials in SAPLSAM.ini. |
| Password | (blank) | N | Y | The password for the SAP user. Encrypt this value — see Encrypt credentials in SAPLSAM.ini. |
| Version | 3.0 | N | N | XBP interface version. Valid values: 2.0, 3.0. |
Job Track/Queue settings
Definitions for tracking or queuing SAP jobs that are submitted outside OpCon. For background on the feature, see Managing external jobs.
Prerequisites in SAP
For job tracking or queuing to work:
- Configure and activate a job intercept profile in SAP that matches the Job Track/Queue configuration in SAPLSAM.ini.
- Run INITXBP2 on the SAP system.
- Confirm Interception 3.0 is activated.
The screenshots below show one example of setting this up.
Initialization Program for Background Processing Interface XBP 2.0
Criteria Manager
SAPLsam.ini Settings
Defining multiple jobs to track or queue
Multiple jobs can be defined for tracking or queuing by creating groups of Track or Queue entries and changing the suffix 1 to a new unique value within each group (for example, TrackFrequencyName2, QueueFrequencyName1).
Settings reference
The settings split into a single shared poll interval and matched Track / Queue group definitions. Define JobTrackCheckInterval once for the whole section.
| Setting | Default | Dynamic | Required | Description |
|---|---|---|---|---|
| JobTrackCheckInterval | 300 | Y | N | Seconds between checks for tracked or queued jobs on the SAP system. Define this only once in the Job Track/Queue Settings section. |
The remaining settings come in two parallel sets — Track definitions and Queue definitions — that share the same fields. Define one set per SAP job you want to track or queue.
| Track setting | Queue setting | Description |
|---|---|---|
| TrackFrequencyName1 | QueueFrequencyName1 | The frequency name configured in OpCon for this job. (Dynamic: Y, Required: N) |
| TrackOpconSkdName1 | QueueOpconSkdName1 | The schedule name configured in OpCon for this job. (Dynamic: Y, Required: N) |
| TrackOpconJobName1 | QueueOpconJobName1 | The job name configured in OpCon for this job. (Dynamic: Y, Required: N) |
| TrackClientId1 | QueueClientId1 | The client id under which the job starts on the R/3 or CRM system. (Dynamic: Y, Required: N) |
| TrackJobName1 | QueueJobName1 | The job name in the R/3 or CRM system. Matched as a regular expression — see Managing external jobs. (Dynamic: Y, Required: N) |
| TrackJobCreator1 | QueueJobCreator1 | The job creator in the R/3 or CRM system. Matched as a regular expression — see Managing external jobs. (Dynamic: Y, Required: N) |
JORS settings
The single setting that controls the JORS service's listening port.
| Setting | Default | Dynamic | Required | Description |
|---|---|---|---|---|
| JORSSocket | 13110 | N | Y | The socket the JORS service uses to deliver job output to the Enterprise Manager (EM). Must match the JORS Port Number on the OpCon machine record. Each agent on the same host requires a unique value. |
JORSSocket must be set in both the agent .ini file and the advanced machine settings in the EM. For more information on changing the JORS Port Number, see Configuring Advanced Machine Parameters and Properties in the Enterprise Manager online help.
FAQs
Which settings can I change without restarting the SAP Agent service? Settings with Y in the Dynamic column. The agent re-reads SAPLSAM.ini when it detects a change. Settings with N require a service restart.
Why does the SAP Agent service fail to start after I edited SAPLSAM.ini? Two common causes:
- Alphabetic values in TCP/IP Parameters or Debug Options entered in lowercase. Both sections require uppercase.
- A duplicate ShortServiceName, DisplayServiceName, SocketNumberToSAM, or JORSSocket when running multiple instances on the same host.
Why doesn't View Job Output show me a job's spool or job log? Three things must be true:
- CaptureJobOutput is
TRUE. - The job log is smaller than MaxJobLogSizeToRetrieve.
- The spool is smaller than MaxSpoolSizeToRetrieve. If any of these is not true, the relevant output is not retrieved.
What is the difference between SocketNumberToSAM and JORSSocket? SocketNumberToSAM is the agent's main communication port with SMANetCom. JORSSocket is the port the JORS service uses to deliver logs and spool files to the Enterprise Manager. Each must match the corresponding setting on the OpCon machine record.
How do I encrypt the SAP user and password values? Use the Password encryption tool in the Enterprise Manager. See Encrypt credentials in SAPLSAM.ini.
Where do per-instance settings need to be unique on a multi-instance host? ShortServiceName, DisplayServiceName, SocketNumberToSAM, and JORSSocket must each be unique per instance. See Multiple instances.
Can I match SAP-side job names with wildcards?
Not with * and ? wildcards. TrackJobName1, TrackJobCreator1, QueueJobName1, and QueueJobCreator1, and the client fields, are matched as regular expressions. See Managing external jobs.
Glossary
SAPLSAM.ini — The configuration file for the SAP Agent. Located in <Configuration Directory>\SAP LSAM\.
SMANetCom — The OpCon component that communicates with agents. The SAP Agent's SocketNumberToSAM must match the Machine's socket number in OpCon so SMANetCom can reach the agent.
JORS — Job Output Retrieval System. The component that delivers SAP job logs and spool output to the Enterprise Manager.
XBP — eXternal Background Processing. The SAP interface used to start, monitor, and intercept background jobs. The agent's Version setting selects XBP 2.0 or 3.0.
BAPI — Business Application Programming Interface. SAP's API surface that the agent calls into. BapiResponseTimeout controls how long the agent waits before treating a BAPI call as failed.
Dynamic setting — A setting that the SAP Agent picks up automatically when SAPLSAM.ini changes, without a service restart.