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 Variables/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.

  • 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.) 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. Instead, this 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 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. The only 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 for tracking or queuing.

  • There are four 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.

      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 moer information about this techinque see Overview of Nested Dynamic Variable Tokens

    • A user-defined program may be specified in the dynamic variable master record. 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. (The name of the Dynamic Variable is also provided as parameter 2, and in parameter 1 the current value of the Dynamic Variable is sent to the user-defined program.) 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 in the Dynamic Variables chapter about how to manage value character string trimming.

    • 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 either Operator Replay screen capture or the SCANSPLF command Scan Rules. These rules also make reference to Dynamic Variable tokens in their Response Command field and their comparison data fields.

  • 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. 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.

    • 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 othe processing of the Job Start request withing 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.