Defining/Using Command Variables with AJS

Resolving The Problem

This document details AJS command variables, how to define and use them, and what is supplied by AJS (referred to as system parameters/variables).

Advanced Job Scheduler allows you to maintain a table of parameters to be used in the jobs or groups of jobs that you set up in Job Scheduler. Parameters are variables such as the beginning of each month, a division number, end of month, and so on. Additionally, parameters can be passed to Job Scheduler from external systems (for example, when users schedule jobs from a user menu).

In order to know what user-defined variables you need, you have to know what is supplied by AJS. With iNavigator, a new window will pop up if you attempt to add a command variable to your command, which will allow you to select from many date-related command variables:



The MDY portion of the command variable is self-explanatory. The possible values are defined below:

Qxxxx - Current, the current MM/DD/YY will be returned
Axxxx - Submitted, the date of the last job submission will be returned
Pxxxx - Previous, the MM/DD/YY previous to the current date will be returned
System value (in other words, QDATSEP)
User-defined variables (discussed just below)

Defining command variables with AJS

In order to use a user-defined command variable, it must be defined through AJS. This can be done using iNavigator or green screen. Through iNavigator, you should do the following:

1. Right click on Advanced Job Scheduler and select Properties
2. Select Command Variables tab, and select New

The variables can be based on a formula, returned from a user-supplied program, or as a reply from an inquiry message on the QSYSOPR message queue.

You can create variables-based simple data on a formula (that use AJS system-supplied variables, example shown) that call a user-supplied program to return, or from the system operator:

Specify data to set AJS Command Variable



Using formula to set AJS Command Variable



In this case, a formula is used to specify a 6-character date based on the *QMDY (current date). The day (D) is set to 1, and the month is set to the previous month (M-1). The complete list of these variables can be see in the AJS document, under the Using Formulas for Parameter Data section. Refer to the following URL:

https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_61/rzaks/sc415324.pdf

You should note that terminology has changed from 'parameters' to 'variables' over the course of time. This can be seen using the green screen when defining variables:

GO JS
Option 4 - Job Controls
Option 7 - Work with Parameters



In this case, you only see user-defined variables; however, you can add new variables at this panel.

Call Program to Set AJS Command Variable



The specified program will be called with a variable. When you change the value of that variable, it will be passed back through AJS. Consider the following example CL program:



The RTVCMDV program uses a data area to keep track the value. When the &AJSVAR variable is changed in the program, the change is reflected back in AJS when the command variable is used. The above program toggles the value between 'A' and 'B'. We can see that AJS used the values by analyzing the IJS6011 messages in the joblog for the AJS job:

IJS6011 Information 10 08/16/11 15:00:18.291844 QIJSC1ALG QIJS *STMT QIJSCALG QIJS *STMT
From module . . . . . . . . : QIJSC1ALG
From procedure . . . . . . : QIJSC1ALG
Statement . . . . . . . . . : 23100
To module . . . . . . . . . : QIJSCALG
To procedure . . . . . . . : QIJSCALG
Statement . . . . . . . . . : 2600
Message . . . . : Command sequence 0010 for job MLBCMD3 group *NONE sequence
01 ended normally.
Cause . . . . . : Command to execute was: CALL PGM(MBAILEY/TESTCMD) PARM(B).

IJS6011 Information 10 08/16/11 15:00:18.496751 QIJSC1ALG QIJS *STMT QIJSCALG QIJS *STMT
From module . . . . . . . . : QIJSC1ALG
From procedure . . . . . . : QIJSC1ALG
Statement . . . . . . . . . : 23100
To module . . . . . . . . . : QIJSCALG
To procedure . . . . . . . : QIJSCALG
Statement . . . . . . . . . : 2600
Message . . . . : Command sequence 0020 for job MLBCMD3 group *NONE sequence
01 ended normally.
Cause . . . . . : Command to execute was: CALL PGM(MBAILEY/TESTCMD)
PARM('A').

You can see the value changed from B to A. The letter 'A' has quotes because of how it was specified in the command for the job. It is recommended that quotes be used to help AJS with the precision:

10 CALL PGM(MBAILEY/TESTCMD) PARM(&TESTPRM2) --> no quotes specified
20 CALL PGM(MBAILEY/TESTCMD) PARM('&TESTPRM2') --> quotes specified

Use QSYSOPR to set AJS Command Variable



When this is specified, AJS will send the IJS6038 reply message to QSYSOPR.

The default reply for the IJS6038 message is *NONE (*N). The AJS job can either use a job control value, user's job description, required (*RQD), default (*DFT), or system reply list (*SYSRPYL). The last three can also be set in the job control or job description specified. The reply value will be used as the AJS command variable.

Using command variables with AJS

In order to use a user or system-supplied variable, you should prefix the variable with an ampersand (&), similar to CL programming convention:





The next time the job is submitted to run, the variable will be replaced with its value when AJS processes the command. The command must have valid syntax. AJS will use command analyzer to check the syntax to help prevent runtime command errors.

Note: If you are using the command variable as a parameter on a call to a program, you may need single quotes around the variable to set the precision correctly for character strings:



In this case, TESTPRM2 is defined as a CHAR(1) or 1-byte character string. In order to set the precision correctly on the call, the single quotes are needed. Without the quotes, testing showed that a 10-character string was passed with the significant data at the tenth byte. This creates issues when trying to manipulate the variable in the program, which assumes it is one character.

You should also note that parameters are passed 'by-value' to the called program. That is, the program does not have direct addressability to the AJS command variable, and any changes to the variable in the program are local to that program. It is not reflected back to the AJS command variable after returning control from the program.

If you want to change the value of an AJS command variable within a program or AJS job, you must use the AJS command, CHGDTAJS, which will change the value of the AJS command variable: