Skip to main content

Dynamic Variable General Rules and Suggestions

Examples of where Dynamic Variables may be used are offered throughout this documentation in each topic. There is more information about dynamic variables in the Screens and Windows section of this topic. Here are some general rules and suggestions to keep in mind when planning to use Dynamic Variables:

  • Dynamic Variables and the tokens derived from them are different from the original Operator Replay Variable Tokens used in Operator Replay scripts. These two different LSAM variable types are used for different purposes as of this version of the LSAM, and they cannot be interchanged. However, it is possible to transfer values from Dynamic Variables to Operator Replay Tokens.
caution

Do NOT continue using the original Operator Replay Variables and their unique tokens. These deprecated artifacts are left over from an original prototype of the LSAM software. Support for this variable type is preserved as a courtesy to early adopters of the software who may still be using very old automation rules. Whenever possible, replace these with the newer, more powerful Dynamic Variable {TOKENS}.

  • The Dynamic Variable type of L is used exclusively to update the local data area (LDA) contents associated with general IBM i batch jobs, including also tracked, queued or captured jobs. (Operator Replay automation can support LDA contents by indirect methods, such as using Control Language commands in Captured Data Response Rules that are linked to Operator Replay Script Steps.) Dynamic variables of type L replace data in the LDA based on the starting position and length fields specified in the Dynamic Variable master record. These two numeric fields apply only to type L variables and then cannot be used for type V variables. For dynamic variables of type L, the Variable Name must be either the Captured Job ID of a captured job, or the IBM i Job Name of a batch, tracked or queued job. More details about Type-L variables can be found at Job Tracking and Queuing -> How LSAM Job Tracking Works -> Local Data Area (LDA) Support and at Dynamic Variables -> Managing the Local Data Area.

  • The Dynamic Variable type of V cannot be used to update LDA content in the same automated ways described above, although Control Language commands executed by several different LSAM automation tools can update the "*LDA" using a Dynamic Variable type V {TOKEN} as the value. Instead, the V variable type is used to define tokens that can be inserted into the job definition parameters or the call command string of a captured job. Type V dynamic variables may have any meaningful name. One purpose for Dynamic Variable tokens is to insert them into the capture job definitions using the WRKCAPJOB function. However, there also exist many other uses for dynamic variable tokens.

  • It is possible for Dynamic Variable tokens to appear, for example, in the Call command string of any batch job submitted by OpCon. This is made possible by the rules of LSAM dynamic variables that are different from the rules for OpCon variables/tokens made from OpCon properties. OpCon job processing recognizes a pair of dual straight or curly brackets: [[name]] or {{name}} as an OpCon variable, but it ignores the single pair of curly brackets: {VARNAME} that is used to build an LSAM dynamic variable token.

  • All Dynamic Variable value substitution processing for the Call Command of submitted jobs is performed by a sub-procedure of the LSAM job scheduler server program. Value substitution takes place as a last step just before the SBMJOB command string is actually executed to start the job. One variation to this method is that Dynamic Variables will also be honored by the LSAM procedures that support an operator manually releasing a job that was held by the LSAM for tracking or queuing. The values used in the submitted job paramaters as Dynamic Variable {TOKENS} are being replace might have been specified in the Variables Tab of an OpCon IBM i Job Master record.

  • There are five ways to specify the value used for a Dynamic Variable:

    • A fixed value may be specified in the VALUE field of the dynamic variable master record, either by manual Dynamic Variable master file maintenance (found on most of the LSAM menus) or by the SETDYNVAR command, which can be registered in several of the LSAM automation tools that support IBM i command-level fields.

      tip

      The VALUE field of the Dynamic Variable master record supports embedded {TOKENS}, up to many layers deep if an embedded variable token also includes its own embedded {TOKEN}. This technique is useful when more than one value formatting rule is required to produce the final format of data that has been retrieved from a database table, a data area, or even an IBM i system value. When attempting this technique is strongly advised to use the DSPDYNVAR command (or option 6=DSPDYNVAR from the variables list display) to run a test of the value formatting results before relying on nested Dynamic Variable Tokens in a production job. For more information about this techinque see Overview of Nested Dynamic Variable Tokens

    • A user-defined program may be specified in the Dynamic Variable master record. Defining this type of program is documented at User-defined Programs for Replacing Dynamic Variable Values. In this case, if the user-defined program is not found at run time, a specified fixed value will be used as the default in place of the program-supplied value. User-defined programs must accept and return at least one character string parameter of any length from 1 to 1024 characters. (In parameter 1 the current value of the Dynamic Variable is sent to the user-defined program. The name of the Dynamic Variable is also provided as parameter 2.) If the user-defined program returns all blanks in the value parameter, the blanks will be accepted as the value and the effect of this is that the dynamic variable token will be removed from its location in the command string and the command string will be compressed to remove the left-over spaces; although, leading and trailing spaces may be preserved as part of a variable's value based on the Character Trime Start and Length fields. There is detailed discussion about how to manage value character string trimming at Trimming Character Values of Dynamic Variables.

    • The LSAM command SETDYNVAR may be used to add a new dynamic variable or to change many of the base master record parameters that define a dynamic variable. However, the auxiliary function codes used to fetch and/or refine variable values cannot be created or changed by this command. Many of this Agent's automation tools can use the SETDYNVAR command to set the fixed value of the dynamic variable just before the variable is used. The SETDYNVAR command parameters are defined under Utitlity Commands for Manipulating Dynamic Variables at SETDYNVAR: Set LSAM Dynamic Variable.

    • Captured Data Response Rules support naming a Dynamic Variable that will be used to store the value of the currently captured data, from:

      (1) Operator Replay screen capture,

      (2) the SCANSPLF command Scan Rules or

      (3) Message Management message text capture rules.

      These rules also make reference to Dynamic Variable tokens in their Response Command field and their comparison data fields.

    • The OpCon Job Master records for IBM i Jobs support a Variables Tab where a Dynamic Variable name is entered in the left column of a table of one or more variable register entries, and a value to be sent to the IBM i Agent in that Dynamic Variable is entered in the right column next to the Dynamic Variable name. A common way to supply values to Dynamic Variables is to enter an OpCon [[Property]] in the value column. This is one of the best ways to store any values accessible to the OpCon server and have then stored into Dynamic Variables where the IBM i Agent can leverage those values for configuring Scripts or other Agent automation tools. Information about the Values Tab is found in OpCon Concepts -> Jobs -> Job Types -> IBM i Job Details -> Variables.

  • An practical use of the LSAM command SETDYNVAR would be to execute this command in a separate job of an OpCon schedule, just before executing the job that depends on a dynamic variable. Similarly, the SETDYNVAR command can be specified as the pre-run command for an OpCon job sent to IBM i (see TIP, below). However, this older technique is now better managed by the Variables Tab that is part of the IBM i Job Master record definition in an OpCon Schedule.

    • When attempting to manage Dynamic Variables from separate jobs, consider using the multi-instance prefixes appended to the Variable Name in order to isolate variable values to a schedule or a job. There are instances that are parallel with the OpCon Schedule and the OpCon Job, and also separate intances assigned to an IBM i Job or to a series of one or more IBM i Jobs that are connected by SBMJOB commands where one job submits the other and will share variable values among any other jobs connected to the same tree of job submissions. For more information see Overview of Multi-Instance Dynamic Variables.
    tip

    The IBM i LSAM processes the SETDYNVAR command specified in a pre-run command line differently from other pre-run commands. All other pre-run commands actually become separate IBM i jobs that are linked with the primary Call command job that depends on the pre-run results. But the LSAM processes the SETDYNVAR command immediately and directly from within the LSAM job scheduler server program. This method of processing allows the new dynamic variable value to be used by the primary Call command associated with the pre-run command in the same OpCon job start request. But as with all pre-run commands, if there is any failure of the SETDYNVAR command processing, it will be reported as job status code 3 and LSAM completion message ID SMA0034 (Pre-run job error). For this reason, there might be situations where there is an advantage to executing the SETDYNVAR as a separate job, upon which another job could depend, rather than using the pre-run command field.

  • An interesting application of the SETDYNVAR command used in OpCon job definitions would be to insert an OpCon property token into the command string where the SETDYNVAR VALUE parameter is specified. This would allow any property value computed by OpCon to be transmitted to the LSAM, where it could then become part of a job's LDA content, used as a SBMJOB command parameter value or used to modify the Call command string of the job. Using this technique offers the advantage of specifying the additional command parameters of the SETDYNVAR command. However...

    • However, as mentioned above, a more recent and possibly more orderly way to set a Dynamic Variable value for a job would be to register the Variable Name and its Value in the Variables Tab of an IBM i Job in an OpCon Schedule. This table of values will be used to set the Dynamic Variable values just before any other processing of the Job Start request within the Agent's Job Scheduler server program. Optionally, any variable in the Variables Tab table can use an OpCon [[Token]] to supply the value. The token replacement is executed as the OpCon Job Scheduler activity is preparing a Job Start request, accompanied by one or more XML-formatted field codes with their values.