Skip to main content
Version: 23.1

Extended Discussion of Parameters

Additional explanation and examples are provided to help understand how to set and use certain of the LSAM parameters listed above.

TLS Security Implementation​

Introduction to TLS Security for the IBM i Agent​

This discussion offers supplemental information in addition to what is provided in Communication Settings in the Concepts documentation, and other referenced sections of documentation that explain each part of implementing TLS Security in the OpCon network. The ready should look for information about configuring the OpCon Server communications programs, including SMANetcom, and the MSLSAM (Windows Agent).

This section is focused on guidelines for implementing compliant and compatible TLS Security for the OpCon Agent for IBM i (= the IBM i LSAM), in cooperation with the OpCon Server itself and, if SMA File Transfer with Windows is required, also in cooperation with the MSLSAM. It is typically possible to also use TLS Security with most of the other OpCon Agents, but please consult OpCon documentation for instructions about specific operations required to implement digital certificates and client/server authentication within those other Agents.

Implementing Digital Certificates for TLS Security​

In general, SMA does not provide specific instructions for generating or installing the digital certificates that are required to support TLS-secured data communication connections. However, the following guidelines are provided as a checklist to help ensure that minimal requirements are not missed.

Follow the OpCon core product documentation for implementing TLS Security:

  1. At least one digital certificate identifying the OpCon server must be generated or obtained and installed into the Microsoft Windows certificate store on the OpCon server.
    • Digital certificates can be self-signed or issued by well-known public Certificate Authorities.
  2. Similarly, the OpCon application server's digital certificate, or the CA root certificate for the authority that issued the OpCon Server certificate, must be imported into the IBM i *SYSTEM certificate store, using the IBM i web-based DCM (Digital Certificate Manager) application.

The IBM i DCM (Digital Certificate Manager) must be used to complete the following operations:

  1. First, if it is not already established, follow IBM instructions to active the *SYSTEM certificate store.
    • Always select the *SYSTEM certificate store to complete most of the following steps (except for the following step 2.b.).
  2. There is sometimes an exception where a special CA certificate store might be used to generate a CA certificate that identifies the IBM i server itself as a certificate-generating authority.
    • If the IBM i server will be a self-signed CA that issues TLS Client/Server certificates for the IBM i LSAM applications, then the internal CA certificate should be imported into the *SYSTEM certificate store as a Trusted CA.
    • Similarly, exporting the IBM i local CA certificate is a good way to then import that CA certificate into the affected Windows systems (such as the OpCon Server and possibly other Windows Agent machines), so that individual TLS Client/Server certificates for the IBM i applications do not, themselves, have to be exported/imported.
  3. TLS Client/Server digital certificates for the IBM i Applications can be issued by a public CA (Certificate Authority), or they can be self-signed certificates issued by the IBM i partition in the client environment.
    • TLS Client/Server digital certificate requests can be generated by the IBM i DCM web application, although, it has been observed that not all of the certificate request options one might desire are readily available from the IBM i DCM web application. Even so, any external digital certificate request application can be used, as long as the local IBM i system identity factors and functional characteristics are known and carefully submitted.
    • Certificates issued by a public CA must then be imported into the IBM i *SYSTEM certificate store.
      • Copy the digital certificate to a directory within the IFS root file system of the IBM i partition where that will execute the DCM web application and host the *SYSTEM certificate store.
  4. If a locally generated TLS Client/Server certificate will be exported from the IBM i *SYSTEM certificate store:
    • Export the certificate to an IFS root '/' file system directory. Frequently it is convenient to specify a .CER suffix on the exported file name.
    • Always use ASCII text mode when transferring a .CER file from the IBM i IFS root file system directory to another system, such as a MS Windows partition or machine.

In OpCon, the machine records for the IBM i machine must be updated with a certificate serial number when a self-signed TLS Client/Server certificate is being imported by itself into the OpCon Windows server, that is, when there is no IBM i CA trusted root certificate already imported into the Windows system.

  • This same principle applies when any TLS Client/Server certificate is imported into the Windows system, when the CA that issued the certificate is not already identified by a Trusted Root certificate (that is already registered in the Windows system).
  • Put another way, it is not necessary to import individual TLS Client/Server certificates into a system whenever the CA that issued the certificate is identified as a Trusted Root (which means that the CA Root certificate has already been imported into the local system's certificate store).

There are four (4) TLS Applications in the IBM i LSAM software (as of the date of this publication) that must be registered in the IBM i *SYSTEM certificate store, and then assigned a TLS Client/Server certificate.

  • LSAM Job Scheduling and JORS services (a TLS Server).
  • LSAM SMAFT (SMA File Transfer) Agent (a TLS Client, initiated by an OpCon SMA File Transfer job start request).
  • LSAM SMAFT Server (a TLS Server, a never-ending LSAM server job that runs alongside of the other LSAM server jobs).
  • LSAM Operator Replay:   The script driver (a TLS Client), accessing the IBM i Telnet Server.

The IBM i *SYSTEM certificate store must be initialized (as mentioned above) before an Application can be registered, but...

  • The digital certificates do not have to be generated or registered (yet) to complete the Application registration in the LSAM software configuration steps.
  • It is critical that the LSAM registration of the Application ID match exactly the Application ID that will be registered in the IBM i *SYSTEM certificate store.

After the Applications are registered, use the IBM i DCM web application to assign the appropriate TLS Client/Server digital certificate to each application.

  • The same TLS Client/Server certificate could be used for all four Applications.
  • The client may choose to use two to four separate TLS Client/Server certificates, depending on the entity's security standards or common practices.

Steps to Implement TLS Security for the IBM i LSAM​

The following instructions apply specifically to the data communication connection between the IBM i LSAM and the OpCon SAM, used for Job Scheduling and (for this LSAM) the JORS Server. For information that is specific to the SMA File Transfer protocol or the Operator Replay Script driver use of the Telnet Server, refer to TLS Security details within those chapters of this Agent documentation.

Some of the following steps may require information that originates from the Digital Certificate guidelines, above.

  1. New installs of the LSAM (OpCon Agent) for IBM i must use an install file with a name similar to LI211043B (or newer, where the "211" refers to the IBM i Agent version 21.1).

    • Version 04.00.03 or older of the IBM i LSAM are not supported for TLS Security. But they can be upgraded to LSAM version 18.1 using the latest version of the 18.1 install file (which can support TLS security), and then the LSAM can be upgraded to version 21.1.

  2. The OpCon server software must be at a version 17.2.x or newer.

    • For versions of OpCon prior to 18.3.1, it might be necessary to obtain and execute SQL instructions that are used to update the OpCon database (at the location of the SQL Server) to enable new TLS Security settings for IBM i machine records.
      • Originally, these statements were available in a file named "UpdateLSAMTYPES_AUXForSMAFTTLS.sql". Please contact SMA Support for assistance with obtaining and executing this update to the OpCon server's database.

  3. Within General Settings for the IBM i LSAM machine record:

    • Enter the Fully Qualified Domain name, for example: IBM i General Settings

  4. In Advanced Settings for the IBM i LSAM machine record, complete the following updates.

    • Under Communication Settings:

      • Set the "Use TLS for Scheduling Communications" flag to True.

      • Enter the TLS Certificate Distinguished Name; this is often the same as the Fully Qualified Domain Name (but verify what the certificate says; some views show this as the certificate Common Name (CN).

      • The TLS Certificate Serial number is not required when certificates are published by a trusted CA (Certificate Authority). But if a self-signed certificate is being used by this machine, then enter the certificate serial number so that OpCon can find its local copy of the certificate to authenticate the communication connection user.

    Communication Settings

    • Under SMA File Transfer Settings, it is usually recommended to start by allowing both TLS-secured and non-TLS connections to be supported, until all the OpCon and LSAM communication links can be verified. After that, only disable non-TLS connections if it is true that all machines used at the site are confirmed as supporting TLS security for SMA File Transfer.

      • Unrelated to TLS security, but required, set the File Transfer Role for IBM i machines to "Both".

      • Set the File Transfer TLS Port Number to the same value as the non-TLS port.

        The IBM i LSAM uses the same port number for either type of connection and depends on a combination of the LSAM local controls, plus the remote SMA File Transfer partner's controls, to determine whether TLS security handshake can be completed.

        NOTE: OpCon "File Transfer" jobs, under the Options tab, can override each job's settings to either force only TLS connections, or to allow non-TLS connections.

      • Set Support TLS for SMAFT Server Communications = True.

      • Set Support TLS for SMAFT Agent Communications = True.

      • Set File Transfer non-TLS Port Number to the same value as the TLS port (for IBM i machines).

      • Set Support non-TLS for SMAFT Server Communications = True.

      • Set Support non-TLS for SMAFT Agent Communications = True.

    • Be sure to use the Update and Save buttons to store the machine record changes.

    File Transfer Settings

  5. Update the IBM i LSAM Parameters.

    • The LSAM green screen main menu is accessed, for example, by using the command SMAGPL/STRSMA. Select option 7 on the main menu. There are tables summarizing the meaning of these parameters in the IBM i Agent Configuration Settings section of this User Help.

    • After verifying the main LSAM Control Parameters, press Enter or PageDown twice to reach display format 3 and update the "Job Scheduling and JORS TLS Security Options."

      • Set "Use TLS Security" = Y.

      • The "TLS Handshake" default value of 30 seconds is usually more than long enough to complete a TLS handshakes.

        If an error message in the LSAM Communications trace log (LSAM sub-menu 6, option 5, log view 1) shows a "handshake timeout" message, it's possible to try the connection again after updating this value to a longer time, and then stopping/restarting the LSAM Servers (to actualize the new setting). However, in most cases it seems that a handshake timeout is really an indication that the other side has rejected the LSAM's digital certificate (for any of several reasons).

      • The "TLS DCM App description" is suggested in the TLS Security parameters table, above, and on the green screen display, page 3 of LSAM Parameters. But it can be user-defined. It is not critical, but is the description that will show in certain IBM i DCM displays.

      • The "TLS DCM Application ID" is critical, because this field value, as entered in this display format, will be used by the LSAM communication program to find the digital certificate it must use, that was stored in the IBM i certificate store.

  6. Update the IBM i LSAM Parameters.

    • a. The LSAM green screen sub-menu for SMA File Transfer in the IBM i is accessed using option 8: SMA File Transfer menu, from the LSAM main menu. From the sub-menu, select option 7: SMAFT Configuration Parameters, from this sub-menu.

    • Press Enter or PageDown once to reach the "SMA File Transfer SSL/TLS Security Options."

    • Set the flag "Use TLS Security?" to 'Y'.

    • The other fields in this segment of TLS Security options are managed similar to the instructions above for Job Scheduling and JORS, except that there are two different programs (or DCM Applications) for SMAFT that must each be described and labeled.

  7. Before TLS Security can be engaged, remember to complete the IBM DCM maintenance:

    • Register the four LSAM Applications, making sure that the Application ID (not the Description) matches exactly what is registered in the LSAM Parameters.

    • After digital certificates are obtained and installed, or created from within the IBM DCM application, assign one or more digital certificates to the four LSAM Applications.

  8. After setting all the LSAM options and completing other preparations (above), use the LSAM sub-menu 6. If the LSAM server jobs were already started, they must first be stopped using the sub-menu option 2, in order for new LSAM Parameter values to be implemented. Then use sub-menu option 1 to restart the server jobs.

    • The same operation holds true for the LSAM's SMAFT server job, managed from sub-menu 8, although in most cases a SMAFT Parameters flag will indicate that the SMAFT Server job will stop and restart along with all the other LSAM server jobs.

Discussion of Keep Socket Open Parameter​

The Keep Socket Open parameter controls the performance of the IBM i LSAM sockets communication program.

caution

The setting of this parameter must match the equivalent parameter in the machine table of OpCon Administration. When the advanced General values parameter for a machine has been set to: Close socket during synchronization = False, then the matching IBM i LSAM must be set to: Keep socket open = Y (yes), and vice versa. Failure to match these parameter values can cause a loss of data.

tip

In most cases, set Keep Socket Open = Y. Do not change this value unless instructed to do so by SMA technical support. This value supports the highest possible rates of communications. However, if a communications link with an IBM i LSAM must be set to close the socket between each transaction, then some other performance parameters in the OpCon machine table must be set to less aggressive values. These parameters and their settings are illustrated in the following table.

Communication Performance​

CategoryParameterWith Keep socket openWith Close socket per TX
Buffer SettingsMax Consecutive Send Messages1001
Timer SettingsConsecutive Send Sleep Time (ms)100200 -- 1000 SMA Technologies recommends testing the lowest reliable rate.

Character Translation​

The function of OpCon controlling jobs in IBM i is managed by the LSAM job scheduling server programs. The TCP/IP sockets communications program (job SKTCMN, program CMNSTKR00) must translate job control information between the native ASCII character set used by the OpCon server and the language-specific EBCDIC character set used by the IBM i partition where the LSAM server jobs run.

The LSAM Parameters are set by default to use IBM i translation tables for U.S. English. But the LSAM also supports an option to use CCSID character set numbers instead, since this translation method may work better in non-U.S. English language environments. Please contact SMA Support for assistance if it is believed that the table names might need to be changed. An SMA technical analyst should evaluate the LSAM's job scheduling communications log in order to help determine whether a change to a different translation table, or the use of CCSID character sets will be required.

To specify a numeric CCSID character set in the Table field, type the special value of "*CCSID" into the Library field. If one table uses a CCSID number, then both tables must use a CCSID number. It is not allowed to mix a translation table name with a CCSID character set number. When specifying CCSID character set numbers, specify the character set that pertains to the set name that is on the right side of the -> arrow character. For example, in the United States, a value of 37 (US EBCDIC) would be specified next to ASCII ->E:, and a value of 819 (US ASCII) would be specified next to EBCDIC->A:.

The CCSID pair of 37 <-> 819 typically produces the same result on a US EBCDIC machine as using the default translation table names of QEBCDIC and QASCII. But in other countries it is more difficult to identify useful translation tables, and in those sites better results can be obtained by identifying the CCSID character sets that are used by the IBM i operating system for DB2 EBCDIC data and IFS ASCII stream files.

Discussion of Bypass Flags​

Error bypass flag SMA0014 is discussed in Job Tracking and Queuing.

When choosing the settings for the error bypass flags SMA0007 and SMA0008, it will help to understand the behavior visible from the OpCon Schedule display. It is important to remember that regardless of how these bypass flags are set, these error message IDs represent that there is a technical problem that is preventing one or more jobs from running when OpCon has requested to start the jobs. If the bypass flags are not set to bypass the errors, OpCon will report the jobs as failed and the jobs can be restarted after the error has been corrected.

If a job has been submitted by bypassing one of these errors, OpCon will report the job as shown in the following examples (refer to both Job Status discussions, below); it will assume that the jobs are active but incomplete. In this case, the IBM i system operator or administrator becomes responsible for manually correcting the configuration problems under IBM i and then manually releasing the jobs.

If it is decided that a job being held in a job queue that has an error (either condition SMA0007 or SMA0008) should be deleted and not run when the error has been bypassed, the correct procedure for deleting the job is to use the OpCon Kill command from the job's context (right mouse click) menu in the OpCon User Interface Schedule display. Using the Kill command will allow OpCon to correctly set the job status in the schedule and it also removes the job from the IBM i job queue.

If an IBM i system operator deletes a job from an IBM i job queue, OpCon will not be able to report the failed status of that job, but will continue to show the job as active until the next OpCon job status poll interval. After OpCon sends a job status poll (transaction TX2) to the LSAM, the LSAM will be able to discover that the job is either not found or is in *OUTQ (output queue) status.

tip

It may take some time for the LSAM to report a failed status for a job that was ended by an operator directly from IBM i, outside of the control of the LSAM. This is because the LSAM will only search for the job status when it receives a job status request transaction (TX2) from OpCon. The interval that controls how often OpCon sends a job status request is set using the OpCon Administration function -> Options table -> Time Settings -> Minutes between checking running jobs.

In previous versions of he IBM i LSAM software, it was possible for the server jobs to issue the error message ID SMA0097. If this error code appears next to an IBM i job in an OpCon schedule, this indicates that the LSAM software needs to be updated with the latest software patches.

Job Status for Attempted Job Starts (TX1)​

If the IBM i LSAM Parameters switches (SMA0008 or SMA0007) are set to "Y" = Yes, allowing job queue error conditions to be bypassed, the LSAM will return a special job status to the OpCon Schedule, rather than rejecting the job request. The job will appear to be active, however, it will show the special status message "Job running - JOBQQ HELD". (See the next section about the TX2 transaction for an illustration of where the following messages appear in one of the OpCon user interfaces.)

  1. The Schedule job status will show: "Job Running - JOBQ HELD"
    • This status means, "The job queue is held, not allowing the job to enter a subsystem where it can become active."
  2. The message sent to the SAM Log will read (possibly with a different job queue name):
    • "Job queue HELD: QGPL/QBATCH preventing job: jobname #1234567890"

When this status appears, the job will not start executing until an operator intervenes and manually releases the held job queue. Once the job queue is released, the job should run normally and OpCon and the LSAM will continue normal operations automatically.

When a job has been allowed to bypass error code SMA0007 and enter a job queue that is not attached to an IBM i subsystem, the report from the OpCon Schedule works the same as for error SMA0008, but with the following different text:

  1. The Schedule job status will show: Job Running -- JOBQ NO SBS
    • This status means, "the job queue is not attached to a subsystem."
  2. The message sent to the SAM Log will read:
    • "JOBQ not linked to SBS: library/jobq preventing job: jobname #1234567890"
      • (The SAM job name and job number are shown at the end of the message.)

Job Status After OpCon Status Request (TX2)​

If a job remains stuck in a job queue and does not achieve active status, the LSAM job status check program will either report that the job queue is still HELD (as shown above), or for any other reasons, the job status will appear as in the following example:

Job Status When Stuck In Job Queue

Job Status When Stuck In Job Queue

As the OpCon Schedule display above illustrates, a job that is still in the job queue and not actually started yet shows a status of "Job Running -- STILL IN JOBQ". This status can occur for any of at least the following three reasons:

  1. If the job queue was not attached to a subsystem (originally reported with the status of "Job Running -- JOBQ NO SBS")
  2. If a job was manually placed in HOLD status while it was still in the job queue.
  3. If the maximum number of jobs permitted are already active in the attached subsystem, and the job has to wait until one of the active jobs ends.

If an operator is able to repair any of these causes, the submitted job should start immediately and OpCon and the LSAM will automatically resume normal schedule control operations.

A [job queue] in HELD status is handled differently, as explained above. When the job queue is released, the job should start and the OpCon job monitoring will return to normal status codes.

SMA0007 Bypass Logic​

The LSAM job scheduler server program (LSASCHR00, job TXMMNG) checks the job queue for a job start request to make sure the job queue is attached to a subsystem. This check prevents OpCon from submitting a job that will never be executed. The default action of the LSAM server (bypass flag value 'N') when it finds a job queue that is not attached to a subsystem is to fail the job start request with error code SMA0007. If the bypass flag value is set to 'Y', the job is submitted but the LSAM continues to report a special error condition to OpCon SAM that shows next to the job in the OpCon schedule.

Sometimes it may be possible that unusual conditions cause the LSAM server to receive a false indication that a job queue is not attached to a subsystem, when it actually is. In this case, it may be helpful to try setting the SMA0007 bypass flag to a number (1 - 9) of retries. The LSAM server will recheck the job queue status after waiting for the number of seconds specified in the Delay for SMA0007 retry, and it will repeat this process for the number of retries. If the job queue status still returns as unattached after the retries, then the LSAM job scheduler server program will fail the job start request with error code SMA0007, just as if the bypass flag had been set to 'N'.

During the process of checking the job queue status, if the LSAM server program receives an error from the IBM i routine that performs the check, the LSAM server will report this error to the system operator message queue (normally QSYSOPR). Two error messages will be sent to the system operator, resembling the following examples:

  • "LSASCHR00 retrieve job queue API reports error CPF1234"
  • "CPF1234 error message text (refer to second level help text of message for more information)"

The first message is used to clearly identify that this message and the one following it have come from the LSAM job scheduler server program, SMA0007 logic. The first message is used to report the message identifier that will appear next in the operator message queue. The second message, which cannot be anticipated in this document, will contain the information returned by IBM i when the API for retrieving job queue information failed. The second message may prove helpful in diagnosing the unexpected circumstances that caused the API to fail. When these messages appear in the system operator message queue, if it is not clear what action to take, please report them to SMA Support for assistance.

SMA5801 Notification of Job MSGW Status and LSAM Feedback​

The LSAM job scheduler and status server tasks detect when a job is stuck in a MSGW (message waiting) status. This detection can occur immediate as a job starts, if the job immediately reports an error, or periodically after the job as started, whenever the OpCon server sends a job status request (TX2). The frequency of job status requests is controlled by OpCon performance options (refer to the OpCon Concepts documentation).

Whenever the LSAM server jobs detect the MSGW status, they always send LSAM Feedback information (field code 5801) to OpCon, at the same time as the job status displayed in the OpCon User Interface is updated with the MSGW status.

tip

LSAM Feedback support was added to the IBM i LSAM with PTF # 403178. At the same time, depending on the OpCon version, it was also necessary to execute some SQL statements to update the SMALOOKUP control file in the OpCon database in order to add definitions for the field code 5801. Those SQL statements were documented in the IBM i LSAM PTF Post-Install Instructions. Newer versions of OpCon would already have this field code added.

There are two different ways to configure a response when a job is reported by the LSAM as stuck in the MSGW status. First, OpCon Event commands can be triggered by the Job Events assigned to the OpCon job master record. Second, the local LSAM server jobs can be configured to trigger Message Management rules by generated a message ID SMA5801.

OpCon Job Events Triggered by LSAM Feedback​

LSAM Feedback is one of three methods that can be used to trigger Job Events for IBM i jobs, when the Job Event tab of the job master record shows the "MSGW Status for Active Job" Feedback option. To configure any OpCon Event command that will execute whenever a job is stuck in the MSGW status, update the LSAM Feedback Value field with the character string %MSGW% (include the percent sign % so that the letters MSGW will match the value string sent by the LSAM regardless of its position in the value text). One or more Event commands can be triggered whenever the LSAM job scheduler server jobs send the LSAM Feedback value text to OpCon.

In addition to pre-programmed generation of LSAM Feedback by the Agent's automation features, users may generate LSAM Feedback from any job that OpCon started. Jobs that use LSAM features such as Operator Replay or the SCANSPLF command can execute the LSAM utility command LFEEDBACK from any supported command line, including the command line of Captured Data Response Rules. (See also the entry about the LFEEDBACK command in the chapter Commands and Utilities.)

Local LSAM Response to MSGW via Message Management​

At the same time that LSAM Feedback is generated, the LSAM job scheduler and job status server jobs can also be configured to generate message ID SMA5801. This option is activated by changing the SMA5801 MSGQ+LIB fields from blanks to a valid message queue name and a message queue library name. To deactivate this option, set these two fields back to blanks.

Remember that any updates to the LSAM Parameters control file will not become effective until after the LSAM server jobs are stopped and restarted.

This SMA5801 option for the LSAM enables local response to the job status of MSGW, separately from any OpCon job master response. Both methods can be used, but care should be taken to avoid generating duplicate Event commands when responses are configured at both levels.

The local response is triggered by the message ID SMA5801 being sent to the designated message queue. The text of the SMA5801 message will include the IBM i job ID that is waiting for a message reply. The local response actions are defined by adding Message Management Parameters. One or more Message Management Parameter master records can be configured to respond to the message ID SMA5801, and different responses can be added for specific job names - possibly in addition to one generic response that would be triggered for any job where the MSGW status is detected. Remember, also, that each Message Management Parameter record can be linked to Capture Data Rules which can be connected to Response Rules. This response matrix makes it possible to conditionally execute any action within the IBM i partition as well as any OpCon Event command.

The response to message ID SMA5801 does not connect directly to the pending message that caused the job's MSGW status. That original message will still require a response, either manual or automatic. Separate Message Management Parameters must be added if the original message is one that might be repeated in the future. This means that one strategy for using the SMA5801 message is to support learning among the IBM i operations team, helping to call attention to messages that might benefit from future automation. Remember that the MSGW status could be for an error message or it could be for any normal program-generated message that requires an operator response.

Bypass Command Validate​

The LSAM job scheduler server program (LSASCHR00, job TXMMNG) previously always attempted to validate the syntax of the command line in IBM i jobs submitted by OpCon. However, the LSAM server program did not support logic that would accommodate unique initial library lists that could be specified for jobs, and it was also unable to easily accommodate specific object authorities in environments that require the LSAM server user profile (SMANET) to be restricted.

The LSAM Parameters bypass flag normally instructs the LSAM job scheduler server to bypass, or skip any validation of the job's command line syntax. This is the recommended setting for most environments. This bypass flag has been provided so that existing IBM i LSAM clients who prefer to use the old validation method can set the bypass flag to N = no in order to continue running the LSAM with its old characteristics.

The LSAM command line syntax validation did provide a quick response in case a command was incorrectly typed, but it did not provide as much diagnostic assistance as would typically be available from the job log of a failed job. According to the old method, it was sometimes necessary to log on to an IBM i workstation in order to view the job log of the LSAM job scheduler server whenever a command was rejected for incorrect syntax. Depending on the setting of job logging parameters, the OpCon "view output" feature would typically provide more helpful information about anything that is wrong with a command line. The "view output" function supports inspection of an IBM i job log from the same console display where the OpCon schedule status is viewed.

Discussion of Translation Tables​

The IBM i LSAM communications server programs that exchange data with OpCon must translate between the IBM i native EBCDIC character set (which could be an international language variation) and the ASCII character set that is native to the MS Windows Server environment where the OpCon communications programs function.

The IBM i LSAM supports three methods for accomplishing character translation:

  1. Specify a matched pair of IBM-provided translation tables.
  2. Define and specify a pair of user-defined translation tables.
  3. Specify a pair of CCSID character sets (one for EBCDIC and one for ASCII).

The default values presented in the LSAM Configuration Parameters are translation tables in the system library QSYS: QEBCDIC and QASCII. However, the system supplied tables are insensitive to various national character sets and so the LSAM may not be able to easily adapt to the practical applications of differing keyboards and language characters that could be used to configure OpCon job master records and OpCon Event commands. For non-U.S. clients the preferred option is probably to use CCSID character sets. User testing is required to prove that a pair of tables or CCSID character sets will work with OpCon.

IBM supports the creation of user-defined translation tables under IBM i. IBM supplies documentation that explains how to perform the following steps that might be useful in the process of developing new translation tables that would more aptly serve a unique environment:

  • Work with tables (WRKTBL) to view their contents.
  • Retrieve the definition of an existing translation table into a source file member (RTVTBLSRC).
  • Create or update a translation table source file member to modify how the translation works.
  • Create a user-defined translation table in a DB2 UDB (DB2/400) library (CRTTBL).

The translation tables or CCSID character sets named here will affect all forms of communication between the LSAM and OpCon.

danger

Great caution must be exercised when selecting the translation tables or CCSIDs used by the LSAM. The translation must always support the existing OpCon transaction protocol rules; therefore, the reserved characters utilized by the OpCon transaction protocol must be understood. Standard XML protocol characters are among those that must be protected. SMA recommends that a test LSAM environment be used to fully prove a new translation table before attempting to use it for live operations. Please contact the SMA Support team if assistance is needed to adapt OpCon translation.

OpCon Event Command Characters​

A typical problem experienced by IBM i LSAM users when specifying OpCon Even commands is the difficulty of trying to insert square brackets [[ ]] around the token fields that can be supported by OpCon Event processing.

For example, when an IBM i LSAM Message Management parameter has been configured to issue an OpCon Event upon discovery of an error message, it might be useful to include some variable value in a notification message. A message sent to OpCon from a Message Management Event might look something like this:

example

$CONSOLE:DISPLAY,This message text is being sent on [[$DATE]],SYSTEM,MESSAGE

In the example above, the character sequence [[$DATE]] will be replaced by the system date as soon as OpCon receives this $CONSOLE:DISPLAY event. This token appears in the OpCon SMANetCom Trace Log, but by the time the message appears on the SAM Log, the token has already been replaced by an actual date value.

One difficulty that arises for IBM i workstation users is that the IBM 5250 workstation keyboard, emulated by the iSeries Access software on a PC, does not support direct keying of the square brackets characters.

However, it is not necessary to create new translation tables to overcome this particular issue, because OpCon already provides a solution for IBM and other similar platforms. The brace (curly bracket) characters {{ }} may be used as a substitute for the square brackets as Event Token field delimiters. In this case, the example above could be typed on a 5250 (emulated) workstation as follows:

example

$CONSOLE:DISPLAY,This message text is being sent on {{$DATE}},SYSTEM,MESSAGE

It is possible that in some environments, the default translation tables involved in certain types of data exchange will prevent a correct translation of the braces (curly brackets){ }. In this case, the ability to specify user-defined translation tables could be helpful. For more information about translation tables, refer to Discussion of Translation Tables.

tip

Dynamic Variables, supported by the IBM i LSAM in places such as a job's call command string, are identified by a single pair of braces (curly brackets) {}. OpCon allows these to be passed to the IBM i LSAM without mistaking them for an OpCon Property token because the OpCon token requires that the braces be doubled in order to be recognized, for example: {{property_token}} or [[property_token]] versus {dynamic_variable}.