Skip to content
CA Vantage™ Storage Resource Manager - 14.0
Documentation powered by DocOps

Job Submission and Substitution

Last update August 31, 2018

This section describes the job submission and variable substitution services available to help prepare template JCL for jobs to submit.

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.

Note: 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.
Note: 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.

Note: 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

    Note: 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

    Note: 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

    Note: 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%%

Note: 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)

Note: 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.

Note: 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
Note: 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.

Note: 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.

Note: 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.

Note: 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.

Note: 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.

Note: 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.

Note: 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

Was this helpful?

Please log in to post comments.