Job Submission and Substitution

This section describes the job submission and variable substitution services available to help prepare template JCL for jobs to submit.
cvsrmv-14-0
This section describes the job submission and variable substitution services available to help prepare template JCL for jobs to submit.
2
 
 
Overview of Job Submission and Substitution
CA Vantage
 supports two methods of job submission:
  • end-user initiated
  • automatically initiated jobs
Storage managers (or other authorized users) submit end-user jobs manually from one of the available clients. Automatic job submission is carried out in response to predefined limits having been reached or conditions having been satisfied. The storage manager defines these limits and conditions as part of the customization process as well as the jobs to be submitted and any timing involved, whenever the limits or conditions are reached.
Model JCL - JCL Templates
When you create a job (JCL stream) to submit, you determine the type of job being submitted, the number of steps, and so on. The job can involve a standard storage management package (such as CA Disk), standard IBM utility programs, your own utility programs, or any combination of these. These programs perform archiving, disk-to-disk migration, idle space release, volume defrags, reporting, or any other function. You can also use IEFBR14 jobs for testing purposes.
CA Vantage
 helps you specify 
substitution variables
 (
symbolic parameters
) in the sample JCL you provide, allowing you to create very generalized 
model JCL
. Whenever 
CA Vantage
 submits a job (JCL stream) to the internal reader, it first scans the entire JCL stream, finds all the variable names, and substitutes the current values for all the variables that were used.
The Windows Client also has an Edit Member (and Submit) function under the z/OS menu. You can use the Drag and Drop feature to drag rows from object displays and drop them onto a JCL template in the Edit window. Substitution from the rows into the Variables in the template will be done.
 
CA Vantage
 has a feature for helping you manage JCL, the JCL Model List feature.
Substitution of variables uses the whole template record and changes all of its content. If the record is determined as a JCL statement (if it starts by "/" and its length is 80), the substitution is limited to columns 1 through 71.
Edit Member
Use the Windows Client ability to edit any PDS or PDSE member containing 80-byte records. They may contain source code, configuration data, JCL templates, or other text files. This generic editor supports standard text editing functions such as Cut, Copy, Paste, Save, and Save As. It also includes specialized edit tools to:
  • Insert the variable name for any field in any object
  • Drag rows from an object table and drop them into the member being edited (drag and drop)
  • Show substitution of the field values (from the drag and drop) into the field variables that appear in the member being edited
  • Repeat entire sections of the member (bounded by //*REPEAT* and //*REPEATEND* statements) for each row being dropped into the member
  • Submit the member to the internal reader (submit a job)
To open the editor, select z/OS, Edit Member (Submit) from the Main menu bar. 
Opening a Member
 
Follow these steps:
 
  1. Click on the folder icon, from the editor toolbar, or open the File menu, and select Open to display the Open Member dialog.
  2. Type a PDS name in the PDS field.
  3. Click Directory to view a list of all the members in a selected PDS.
    The system displays a list of members. Additional member information includes the date and time of the last modification, member size, and user ID.
  4. Click on the member you intend to edit (or key in its name in the member field), and click OK.
    The member appears in the PDS Member Editor dialog.
Edit Member - Special Tools and Services
Edit the member using the standard text editing functions such as Cut, Copy, Paste, Save and Save As. Or use the specialized tools to insert object field variables, drag and drop records into the member, show the substitution, and submit the job (assuming it is a JCL member, of course).
The Edit Member Dialog includes these menus:
  • File menu - this includes the commands New, Open, Save, Save As, and Exit.
  • Edit menu - this includes the commands Undo, Redo, Cut, Copy, Paste, Find, and Replace.
  • Tools menu - this includes the commands Variables, Show Substitution, and Submit.
The most frequently used functions are also available from the toolbar. If you place your cursor over an icon in the toolbar, a help label describes the icon.
The editor provides access to the following set of text and file manipulation commands:
  • Use the Cut, Copy, and Paste commands to perform standard text editing functions.
  • Use the Find, Find Next, and Replace commands to search for text and to perform global text replacements.
  • Use the Undo command to reverse the last operation you performed.
  • Use the Open command to open a new member.
  • Use the Save command to save a modified member under its existing name.
  • Use the Save As command to save a modified member under a new name.
  • Use the Close command to exit the editor.
  • Use the Variables command to display the list of object field names, and click on a field name to insert the field's Variable name into the member at the current cursor position. Click on the
    Display (and insert) Variables
     icon to list all the objects and their fields. Clicking on a field name moves the variable name for that field into the member at the cursor location.
  • Use the Substitute command to substitute the variables in the templates with values extracted from selected objects. Click on the 
    Show substitutions
     icon after dragging and dropping object records onto the (template) member being edited if you want to see the resulting member after all field variables have been substituted with their respective field values. Sections repeated due to the //*REPEAT* and //*REPEATEND* statements are also shown.
  • Use the Submit command to submit the member to the internal reader. Use this only for JCL members. The submit command also includes a scheduler which allows the job submit to be deferred until a later date and time, if desired. Click on the 
    Submit member to internal reader
     icon only for JCL members. A scheduler function enables the submit function to be done at a later date and time, if required.
Edit Member - Drag and Drop Feature
The drag-and-drop feature is available in the Windows Client as part of the Edit Member option in the z/OS menu. This feature lets you drag-and-drop rows from an object table into the Edit window to substitute variables in a JCL template.
 
Follow these steps:
 
  1. Open the PDS member containing the appropriate JCL template using the Edit Member option in the z/OS menu.
  2. Select the object table row or rows you want to drag onto the template. You can use any of the selection methods available. To select:
    • a single row
      Click on the row number of the row you want to select.
    • multiple non-contiguous rows
      Click on the row number of the first row you want to select and release the mouse, then Ctrl-click on any additional row numbers of rows you want to select.
    • contiguous rows
      Click the left mouse button and drag the pointer over the row numbers of the rows you want to select. (You can also click on the row number of the first row you want to select and release the mouse, then hold down the Shift key and click on the last row number of the last row you want to select.)
    • all the rows in a table
      Click Select All Lines from the Edit menu.
  3. After you have selected the rows you want to include, release the mouse button.
  4. Move your cursor to position it on top of (any) one of the row numbers selected, then click and hold your left mouse button. While holding the mouse button move the mouse slightly and the drag-and-drop icon will appear. The appearance of the icon indicates that the Windows Client is ready to copy your selected rows. Do not release the mouse button.
  5. Once you see the icon, continue to drag the selected rows (indicated by the icon following your moving cursor) to the template and drop them by releasing the mouse button.
For more information, this feature is further described in the Windows Client help system under the topics Using Drag and Drop, and Edit Member.
Substitution Variables and Services
 
CA Vantage
 supports five types of substitution variables:
  • CA Vantage
     System Variables, for example, %%DATE%%
  • CA Vantage
     Object and Field Variables, for example, %%DEVTYPE%%
  • CA Vantage
     Old Format Variables, for example, %VOLUM
  • z/OS System Symbols, for example, &SYSCLONE
  • z/OS System Parameters, for example, !SYSNAME ('!' = X'5A')
The 
CA Vantage
 System Variables and 
CA Vantage
 Object and Field Variables can also be 
tokenized
 and 
sub-stringed
. Detailed information about all five types, tokenizing, sub-stringing, and other related topics compose the rest of this section.
Substitution of variables uses the whole template record and changes all of its content. If the record is determined as a JCL statement (if it starts by "/" and its length is 80), the substitution is limited to columns 1 through 71.
Substitution - 
CA Vantage
 System Variables
 
CA Vantage
 system variables are available at all times, they can be used in any context, including work being done with any object. The following is a list of the 
CA Vantage
 system variables:
  • %%DATE+nnnn%% %%DATE-nnnn%%
    Variable: Today's date plus or minus 
    nnnn
     number of days, returned in Gregorian format.
    Format: DDMMMYYYY
  • %%TIME%%
    Variable: Time
    Format: HH:MM
  • %%DATEG%%
    Variable: Gregorian date
    Format: DDMMMYYYY
    This variable is obsolete and removed from the Windows Client Substitution Variables window, but it is still supported on the host side.
  • %%DATEJ+nnnn%% %%DATEJ-nnnn%%
    Variable: Today's date plus or minus 
    nnnn
     number of days, returned in Julian format.
    Format: YYYYDDD
  • %%DATEN+nnnn%% %%DATEN-nnnn%%
    Variable: Today's date plus or minus 
    nnnn
     number of days, returned in Gregorian format with numeric month.
    Format: DDMMYYYY
  • %%HHMMSS%%
    Variable: Time with seconds
    Format: HHMMSS
  • %%SYSID%%
    Variable: System ID used by JES2 to identify the operating system. If SMF is not installed, SYSID defaults to 4 asterisks.
    Format: 4 character alphanumeric string
  • %%SYSNAME%%
    Variable: GRS name for current system ownership used by MVS and other major components to identify the system on which 
    CA Vantage
     runs.
    Format: 8 character alphanumeric string
  • %%TODAY+nnnn%% %%TODAY-nnnn%%
    Variable: Today's date plus or minus 
    nnnn
     number of days, returned in Gregorian format.
    Format: DDMMMYYYY”
  • %%TODAYG+nnnn%% %%TODAYG-nnnn%%
    Variable: Today's date plus or minus 
    nnnn
     number of days, returned in Gregorian format.
    Format: DDMMMYYYY
    This variable is obsolete and removed from the Windows Client Substitution Variables window, but it is still supported on the host side.
  • %%TODAYJ+nnnn%% %%TODAYJ-nnnn%%
    Variable: Today's date plus or minus 
    nnnn
     number of days, returned in Julian format.
    Format: YYYYDDD
    This variable is obsolete and removed from the Windows Client Substitution Variables window, but it is still supported on the host side.
  • %%DSNPFX%%
    Variable: The value assigned to system parameter DSNPFX.
    Format: 1 to 35 character DSN prefix
  • %%HSMPFX%%
    Variable: The value assigned to system parameter HSMPFX.
    Format: 1 to 35 character DSN prefix
  • %%SCREVENT%%
    Variable: The event type of the executing script. “GOA”, “SYSTEM”, and so on.
    Format: 8 character Script Event Type
  • %%SCRNAME%%
    Variable: The name of the executing script.
    Format: 8 character Script Name
  • %%SCRPHASE%%
    Variable: The phase number of the executing script. “1”, “2”, “3”, and so on.
    Format: 1 character Script Phase Number
  • %%SCRSIMUL%%
    Variable: Is the script running in simulation mode?
    Format: 1 character Script Simulation Mode
  • %%NUMBRECS%%
    Variable: Selected number of elements from an object.
    Format: 1 - 15 character Selected number of records
Substitution - 
CA Vantage
 System Parameters
CA Vantage
 system parameters are also available for substitution and can be used in any context, including work being done with any object. The system parameter substitution will appear as the following:
%%
system_parameter_name
%%
For more information about system parameters, see System Parameters.
Substitution - 
CA Vantage
 Object and Field Variables
CA Vantage
 Object and Field Variables are available (can be resolved) only when working in the context of a specific object. For example, when working with object POOLS, there are variables for every field within that object. Model JCL (a JCL template) intended for use with this object, can use any or all of the field variables for that object. When 
CA Vantage
 is asked to use that template with the POOLS object, it applies the template to each row it processes and substitutes the 
actual contents of the 
referenced fields into the generated output, for example, the JCL stream being submitted.
If the same template is applied to a different object, few if any of the fields can be substituted because most, if not all, of the field names are different between the two objects.
Since there are hundreds of objects, and many fields within each object, the complete list of these substitution variables is too large to include here. However, to obtain the list for one or all objects, use the GENMAP utility.
Substitution - 
CA Vantage
 Old Format Variables
The following substitution variables use a format from very old releases. Even though these old format variables may still work, it is highly recommended that you use the new Object and Field Variables described above (and convert any old variables, if still in use, to the new ones).
  • The old %VOLUM parameter was used to get the actual volume name when using old volume threshold support. The current variable when working with the volumes object is %%VOLUME%%.
  • The old %DCB parameter was used to get the actual number of free DSCBs in the VTOC when monitoring volumes. The current variable when working with the volumes object is %%DSCBFREE%%.
  • The old %VIR parameter was used to acquire the actual number of free VTOC Index Records when monitoring volumes. The current variable when working with the volumes object is %%VIRSFREE%%.
  • The old %JOB parameter was intended for use as part of the job name. When found in a template, it was usually replaced with the last three characters of the object name. This variable helped provide unique job names for all jobs submitted. The exception was when it was used with the old threshold support for logical data set groups (on primary storage). In this case, it was replaced with the last three characters of the name of the logical group. In most cases, the above usage can be replaced by using a substring of the appropriate object field, for example, %%VOLUME(3,3)%% will use the last three characters of the volume name, and %%GRPNAME(7,3)%% will use the last three of the group name.
  • The old %GROUPNAME and %GROUPNM parameters were used with logical data set groups on primary storage.
  • When %GROUPNAME was found in a template, it was replaced with all ten characters of the group name. When %GROUPNM was found, it was replaced with only the first eight characters of the group name. The current variable when working with the logical data set groups on primary storage is %%GRPNAME%%, which is the ten character field. To get only the first eight characters, use the substring function, that is, specify %%GRPNAME(0,8)%%.
  • The old %UNI parameter was used with the old defrag monitor. When found in a template, it was replaced with the unit type of the monitored disk volume. The current variable when working with the volumes object is %%DEVTYPE%%.
  • The old %PR parameter was used with the old volume or storage group threshold monitors. When found in a template, it was replaced with the number that represents the percent of the monitored volume or storage group that is currently allocated, that is, the percent allocated. The current variable when working with the volumes object is %%PCTALLO%%, and when working with pools (storage groups) it is %%POOLUPCT%%.
Substitution - z/OS System Symbols
System Symbols are all z/OS system related. IBM introduced them in MVS along with the SYSPLEX feature to motivate sharing one SYS1.PARMLIB between as many systems as possible.
The 
CA Vantage
 substitution feature can now use the same symbols for substitution into both JCL and 
CA Vantage
 system parameters. The following is one example of this:
&SYSNAME (substitute to system name in z/OS, for example: XAE1)
CA Vantage
 system parameter example:
HSMLOGX (DFHSM.&SYSNAME..LOGX)
For a description of IBM's z/OS System Symbols, see the appropriate IBM literature, for example their 
Initialization and Tuning Reference
 manual.
Substitution - z/OS System Parameters
System parameters hold values that control the initialization and performance of z/OS. Some parameters identify other members of SYS1.PARMLIB that are to be used. For example, the GRSCNF system parameter identifies the GRSCNFxx member. The IEASYSxx PARMLIB member specifies the system parameters that the system is to use. The operators can specify system parameters during initialization, or accept the system parameters specified in IEASYSxx. The operators may also modify the value of the system parameters when the system is up and running.
The 
CA Vantage
 substitution feature can now use the same symbols for substitution into both JCL and 
CA Vantage
 system parameters. The following is one example of this:
!SYSNAME (substitute to system name in z/OS, for example: XAE1)
CA Vantage
 system parameter example:
MCDSDSN (DFHSM.!SYSNAME..MCDS) * MCDS DATASET
SYSNAME happens to be a variable that is both a z/OS System Symbol and a z/OS System Parameter. Both should resolve to the same value.
For a description of IBM's z/OS System Parameters, see the appropriate IBM literature, for example their 
Initialization and Tuning Reference
 manual.
Substitution - Tokens
Some 
CA Vantage
 Object Variables hold text strings of several 
words
 rather than simple values. You can extract a 
word
 (token) from the total string and use it for substitution by placing the token number you want after a colon in the substitution variable. If, for example, an object variable named TEXT is a text string, the substitution variable %%TEXT:12%% specifies the twelfth 
word
 of the string TEXT.
When parsing the total string to extract the individual tokens (
words
), 
white spaces 
are used the same way as in some high level programming languages, such as C. In 
CA Vantage
 substitution, the white-space characters are the comma, the blank, and the equal sign. White-space characters separate individual tokens. Any number of consecutive white-space characters serve as a single separator between tokens.
Example of token values
 
The object variable named TEXT in the following example has seven tokens:
MSG1234E Error in program = PROG1, RC=16
If specified as tokens, then during substitution the token variables get the expanded values indicated:
  • %%TEXT:1%%
    Becomes 
    MSG1234E
     
  • %%TEXT:2%%
    Becomes 
    Error
     
  • %%TEXT:3%% 
    Becomes 
    in
     
  • %%TEXT:4%%
    Becomes 
    program
     
  • %%TEXT:5%%
    Becomes 
    PROG1
     
  • %%TEXT:6%%
    Becomes 
    RC
     
  • %%TEXT:7%%
    Becomes 
    16
     
The character sequences “ = ” (blank, equal sign, blank) between Token 4 and Token 5, and “, ” (comma, blank) between Token 5 and Token 6, are consecutive white-space characters and serve as single separators. Therefore, they are not counted as tokens.
Substitution - Substrings
In 
CA Vantage
 System or Object Variables, you can specify a substring of the complete replacement text. The notation for a substring is to specify the offset of the starting character and the desired length, in parenthesis. (Compare this to the notation for a token, which uses the colon followed by the number of the 
word
 in the text.)
To obtain 
the rest
 of a string, specify 0 (zero) or a high number for length. If, for example:
%%HHMMSS%% substitutes to 085230
then:
%%HHMMSS(0,4)%% substitutes to 0852, and %%HHMMSS(2,99)%% substitutes to 5230.
To combine token and substring substitution, the token number must come before the substring specification. 
CA Vantage
 uses the token number first, to find the desired token. Then it extracts the substring from the token. If, for example:
%%TEXT%% substitutes to I am from Czechoslovakia, %%TEXT(0,10)%%%%TEXT:4(5,4)%% becomes I am from Oslo.
Substitution Failures
If variables fail to be substituted into your templates (message VAN0835E or VAN0836E), the combined length of the substituted values may exceed the length of the output area. If so, either remove some of the variables or use tokens to substitute shorter strings into the templates.
The maximum length of substituted variable substring is 124 characters. The following is an example of the variable substitution with the maximum substring length: %%HLOTXT(0,124)%%.
GENMAP Utility - List Field Variables
The GENMAP utility can generate (produce) all the Object and Field Variables, and mapping macros, for every 
CA Vantage
 object. It also shows you the names and numbers assigned to every object.
For more information, see the member MAPPINGS distributed in the CCTUSAMP library.
INCLUDE Statement
JCL templates can contain %%INCLUDE statements. The INCLUDE statement points to the name of a sequential data set or to the data set and member name of a PDS. When a template that contains an INCLUDE statement is opened, it is automatically expanded and the contents of the designated file included in the parent template. INCLUDE statements can be recursive.
The syntax of the INCLUDE statement is:
%%INCLUDE DSNAME
datasetname
MEMBER
membername
The keyword DSNAME can be abbreviated as DSN, MEMBER can be abbreviated as MEM.
Also, the blank delimiters can be replaced by a comma (,) or an equal sign (=). Any number of consecutive delimiters is allowed. The above statement could also be written as:
%%INCLUDE DSN=
datasetname
, MEM =
membername
The DSN can be up to 44 characters long, the member name up to 8 characters.
If DSN is omitted, the system assumes that the included file resides in the same library as the parent template. Therefore, when using a single library for JCL templates, there is no need to specify the DSN.
INCLUDE statements are intended for the reuse of existing templates in the creation of new ones. They provide a convenient way to create standard building blocks for JCL streams. For example, INCLUDE statements allow for job card customization in a standard storage management job template.
Member JCARD in DSN=CA.VANT.JCLLIB can contain your customized version of the following:
//JOBNAME JOB (ACCT-INFO),'YOUR-NAME',CLASS=C,MSGCLASS=X, // NOTIFY=&SYSUID
Member JDEFRAG in DSN=CA.VANT.JCLLIB can then contain:
%%INCLUDE DSN=CA.VANT.JCLLIB,MEMBER=JCARD //*************************************************************** //*** JCL TEMPLATE FOR DEFRAG OF A VOLUME ** //*************************************************************** //DEFRAG EXEC PGM=ADRDSSU //SYSPRINT DD SYSOUT=* //SYSIN DD * DEFRAG DYNAM(%%VOL%%) /*
If an error occurs during the expansion of an INCLUDE statement (for example, a referenced member is not found), processing stops and an error message appears instead of the expanded statement.
REPEAT Statement
By including a REPEAT statement (or a pair of REPEAT/REPEATEND statements) in the JCL template, you can perform the same substitution on more than one object record.
REPEAT causes the substitution mechanism to duplicate the last section of the template for each record on which you want to perform the operation. (REPEAT duplicates the last portion of the template as many times as there are selected records, variables that appear before the REPEAT statement are substituted only for the first record selected.)
The pair REPEAT/REPEATEND causes the substitution mechanism to duplicate the section of the template located inside the pair, as many times as there are selected records. Variables that appear outside the REPEAT/REPEATEND pair are substituted only for the first record selected.
The //*REPEAT* statement allows for a maximum of 999,999 records to be inserted.
The syntax of the REPEAT statement is:
//*REPEAT*
The syntax of the REPEAT/REPEATEND statement is:
//*REPEAT* //%%YOUR_VARIABLE%% //*REPEATEND*
New Template
If you want to repeat the JCL template when the value of a selected object field changes, use the keyword "NEWTEMP=".
The sections below and above the REPEAT/REPEATEND section will be added to the substituted text and substitution processing will continue in the REPEAT/REPEATEND section of the new template.
The following is the syntax for NEWTEMP:
//*REPEAT*,NEWTEMP=field_name //%%YOUR_FIELD_NAMES%% AND TEXT //*REPEATEND*
The input object must be sorted on the field name selected in NEWTEMP.
Example of using NEWTEMP
 
//VOLJM%%MODEL%% JOB (01026),'BJART',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1), // REGION=0K,NOTIFY=&SYSUID //QURYCMD EXEC PGM=IEBGENER //SYSUT2 DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //SYSUT1 DD DATA,DLM=ZZ PROFILE NOPREFIX NOMSGID //*REPEAT*,NEWTEMP=MODEL VOLUME %%VOLUME%% %%DEVTYPE%% %%MODEL%% //*REPEATEND* ZZ //*
This expands into:
//VOLJM1 JOB (01026),'BJART',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1), // REGION=0K,NOTIFY=&SYSUID //QURYCMD EXEC PGM=IEBGENER //SYSUT2 DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //SYSUT1 DD DATA,DLM=ZZ PROFILE NOPREFIX NOMSGID VOLUME ALLOC1 3390 1 VOLUME ALLOC2 3390 1 VOLUME TSO93P 3390 1 ZZ //* //VOLJM9 JOB (01026),'BJART',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1), // REGION=0K,NOTIFY=&SYSUID //QURYCMD EXEC PGM=IEBGENER //SYSUT2 DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //SYSUT1 DD DATA,DLM=ZZ PROFILE NOPREFIX NOMSGID VOLUME VTC025 3390 9 VOLUME VTC026 3390 9 VOLUME VTC027 3390 9 ZZ //*
When the value of the field "MODEL" changes, a new template is written to the substituted JCL.
Only one //*REPEAT*,NEWTEMP= section can exist in the JCL template. If multiple sections are coded, only the first //*REPEAT*,NEWTEMP= will work correctly. Subsequent sections will not be substituted. However, using multiple //*REPEAT* sections without the NEWTEMP works well. You can circumvent the NEWTEMP restrictions. The following is an example of how you can circumvent the NEWTEMP restrictions.
Example of using multiple REPEAT sections without the NEWTEMP 
 
  1. Use the Summary Designer and create a Value Summary Object from the DTOC4SYS object with Volume as the value field. Set the optional "DSN INCL" filter on the source object. The following is an example of Summary Designer entries to create the Summary Object:
    • General Section
      Name: Test NEWTEMP workaround
      Description: Test NEWTEMP workaround
      Base Object: Data Sets For System (All) (DTOC4SYS)
      Filter: "Data Set Name" INCL dsn.data.setname/
      Mode: LI - Last Interval
      Method: VALUE
      Method applies on fields: Field 1 "Volume"
    • Content Section
      Count: Yes
      Percent: No
      Fields included: ( Field ] Aggregations ): "Data Set Name" First
  2. Create a script and JCL template like the following example. Use the same filter in the script as in the summary.
    <GENERAL> EVENT_TYPE=GOA TITLE=Testing Newtemp workaround SIMULATE=N ENABLED=Y LOAD_SCRIPT=Y STARTTIME=0000 ENDTIME=2400 <EVENT_PROCEDURE> SELECT_OBJ=S00DMV4A SET_REALTIME SET_FILTER=VOL <> X EXECUTE DO_FOR_ALL ZOOM_TO_OBJ=DTOC4SYS SET_LASTINTVL SET_FILTER=DSN INCL dsn.data.setname/ EXECUTE IF_RECORDS_GT=0 SUBSTITUTE_JCL=DSN=jcl.data.setname.JCL,MEMBER=TNEWTEMP,STRIP=B SUBMIT_JOB ELSE ENDIF NEXT ENDDO
    Where the following is the TNEWTEMP JCL member:
    //jobcard REGION=0K,NOTIFY=&SYSUID //EXECUTE EXEC PGM=IEFBR14 //* First REPEAT //* %%VOL%% //*REPEAT* //* %%DSN%% //*REPEATEND* //* //* //* Second REPEAT //*REPEAT* //* %%DSN%% //*REPEATEND* //* //*
    This expands into:
    //jobcard REGION=0K,NOTIFY=&SYSUID //EXECUTE EXEC PGM=IEFBR14 //* VOLUME1 //* DSN.DATA.SETNAME1 //* //* //* DSN.DATA.SETNAME2 //* //*
Control Stripping of Spaces of the Values
Use the 
CA Vantage
 sysparm STRIP to control variable substitution in Edit Member - Drag-and-Drop Feature.
For more information, see the description of the STRIP parameter in System Parameters.
Sample Templates with Substitution Variables
Member SAMPJCL5 from the CCTUSAMP library is shown below, and illustrates the use of substitution variables in a model JCL template.
FDR Compactor to defrag a volume:
(Member = SAMPJCL5 from the CCTUSAMP library.)
%%INCLUDE DSN=CA.VANT.JCLLIB,MEMBER=JCARD //*************************************************************** //*** EXAMPLE JCL FOR FDR COMPAKTOR ** //*** ** //*** CUSTOMIZE THIS EXAMPLE FOR YOUR INSTALLATION NEEDS ** //*** ** //*************************************************************** //COMPAKT EXEC PGM=FDRCPK //SYSPRINT DD SYSOUT=* //SYSMAP DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //CPKWORK DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //TAPE1 DD UNIT=T3480, // DSN=YOUR.DATASET.%%VOL%%,DISP=(,CATLG) //DISK1 DD UNIT=%%UNIT%%,VOL=SER=%%VOL%%,DISP=OLD //SYSIN DD * COMPAKT DUMP=YES,PSRLSE=ALL,PORLSE=ALL,TEMPS=KEEP SELECT ALLDSN,DSORG=(PO,PS) /*
The following JCL examples can be found in the CCTUSAMP library:
  • JCLCONSL
    Batch utility job to issue operator commands.
  • SAMPJCL1
    CA Disk DSCL job to archive data sets.
  • SAMPJCL2
    CA Disk DSCL job to move data sets.
  • SAMPJCL3
    CA Disk DSCL job to release idle space.
  • SAMPJCL4
    DFSMSdss job to defrag a volume.
  • SAMPJCL5
    FDR compactor job to defrag a volume.
  • SAMPJCL6
    DFSMSdss job to run idle space release and defrag a volume.
  • SAMPJCL7
    DFSMShsm MIGRATE command to archive data sets.
  • SAMPJCL8
    TSO SEND command to send a message to a TSO logon ID for a storage group threshold.
  • SAMPJCL9
    TSO SEND command to send a message to a TSO logon ID for a volume threshold.
  • SAMPJC10
    TSO SEND command to send a message to a TSO logon ID for a group threshold.
  • SAMPJC11
    DFSMSdss job for a full dump operation to be used by the Hardware Monitor.
  • SAMPJC12
    No longer included (was another defrag example).
  • SAMPJC13
    Job to send e mail from 
    CA Vantage
    .
  • SAMPJC14
    Job to scratch ASG-Zara tape volumes.
  • SAMPJC15
    Job to expire ASG-Zara volume chains.
  • SAMPJC16
    Job to update ASG-Zara volume account info.
  • VANSENDM
    Job to send 
    CA Vantage
     mail or messages to 
    CA Vantage
     users.
Special Job Submission Services
You can use the following special services for job submission:
  • EOJ Services
  • Security
  • Scheduling
  • Batch utility to issue operator commands
EOJ Services
Whenever General Object Automation (GOA) executes a SUBMIT_PHASE_JOB, it automatically inserts an //EOJ statement at the end of the job being submitted, if it is not already present.
The Submit Processor used by automation components searches for //EOJ within the template JCL. If it finds one, it changes it to execute the appropriate API (PGM=KNGEJ001), which will pass information back to the automation component of the subsystem.
The EOJ API indicates the job has ended, but also passes the subsystem the highest return code from the submitted job. The highest return code from the job is also set (indicated) for the EOJ step itself.
GOA processing of a multi-phase automation script can shift to the next phase based upon either the EOJ notification or timing parameters.
Security Services
To allow both automated and end-user job submissions, the security access of both 
CA Vantage
 and of individual jobs must be addressed as explained below.
For more information regarding Security Services, see Startup Step 5: Establish Proper Security Environment in Startup Steps.
Security - Maintaining Security when Users Submit Jobs
If the 
CA Vantage
 security support is active (which is the default), users can submit jobs from many of the object displays. To establish proper security for these jobs, 
CA Vantage
 automatically inserts keywords USER=
logon ID 
and PASSWORD=
password 
into the job statement of the JCL being submitted.
If for some reason you do not want this substitution, specify system parameter USERIDPW (N) in the VKGPARMS member of PARMLIB. If you do so, the proper security for these jobs becomes the responsibility of your local installation standards and procedures.
Security - Maintaining Security when Automation Submits Jobs
In RACF and 
CA Top Secret
 environments, the model job statement in any JCL to be submitted should not contain the logon ID and password parameters. Instead, let the internal reader exit add the logon ID and password (associated with the 
CA Vantage
 started task) to the job when the job is submitted.
Be sure that the logon ID and password associated with the 
CA Vantage
 started task (usually the storage administrator logon ID, or one with equivalent authority), has full authority to the data the automation job must process.
CA ACF2
, however, does not substitute the task logon ID and password into the job through the reader exit. Instead, a special logon ID should be created for these submitted jobs. The model JCL references it in either a //*LOGONID logon ID statement or the USER=logon ID parameter of the JOB statement.
For more information, see 
CA ACF2
 Example in Startup Step 5.1: Establish Proper Access Authority in Startup Steps.
Whichever security system you use, verify that the logon ID associated with the submitted jobs has the proper authority as outlined above.
Job Scheduling Services
CA Vantage
 can submit jobs immediately for end-user requests or for any condition it has been asked to monitor. But in both cases, job submission can also be scheduled for execution at a later time.
The 
CA Vantage
 scheduler lets you schedule jobs using one of two methods:
  • Specifying an absolute day and time when you want the job to be executed
  • Specifying a delay in days, hours, or minutes
Batch Utility to Issue Operator Commands
You can issue operator commands to 
CA Vantage
 or other systems by using the batch job step provided in the JCLCONSL member of the CCTUSAMP library. You can provide one or more operator commands as the SYSIN stream to this utility, or a single command using the PARM= parameter on the EXEC statement. When the PARM= parameter is used, the SYSIN stream is ignored.
An example of when this utility may be useful is as follows. Assume GOA script 
XXX 
submits a batch process that may require an extended period of time to complete, and that you want to ensure that script 
XXX
 does not even try to submit the job again until after it completes the first time.
This can be achieved by adding a step to disable the script as follows:
//STEP1 EXEC PGM=VANCONSL //STEPLIB DD DISP=SHR,DSN=
ca.vantarg
.LOADLIB //SYSIN DD * F SAMS,AUTO,DISABLE=GOA,XXX
And a final step to enable it again:
//STEPLAST EXEC PGM=VANCONSL //STEPLIB DD DISP=SHR,DSN=
ca.vantarg
.LOADLIB //SYSIN DD * F SAMS,AUTO,ENABLE=GOA,XXX