UAGRERUN Stand-Alone Execution

Owned by Stonebranch (Deactivated)
Jul 12, 2024
6 min read

Introduction

This document describes the procedure for running the UAG for z/OS UAGRERUN program in stand-alone mode.

UAGRERUN is a program included with UAG for z/OS that runs as the first step in any job submitted by UAG for z/OS. Its responsibilities include:

  • Creating the control blocks needed for the agent to track the job to completion.
  • On rerun, comparing the current JCL to the previous runs’ JCL.
  • Deleting qualifying datasets created by the job with DISP=NEW
  • Performing any GDG dataset adjustments required.
  • Performing step selection.
  • Printing reports.

Stand-Alone Capabilities and Limitations

UAGRERUN can also be run stand-alone. In that case, it provides similar functionality without any involvement of UAG for z/OS or the Universal Controller.

When running stand-alone, UAGRERUN can provide the following functionality:

  • Deleting qualifying datasets created by the job with DISP=NEW (Except GDGs).
  • On rerun, performing GDG dataset adjustments if GDGPROC=R is specified.
  • Performing step selection.
  • Printing reports.

When provided with a history dataset, it can perform the following additional processing:

  • On rerun, comparing the current JCL to the previous runs’ JCL.
  • On rerun, deleting qualifying GDG datasets created by the job with DISP=NEW if GDGPROC=A is specified.

When running stand-alone, the following functionality is unavailable:

  • Capturing and using of any run-time information on the job. Including step condition codes, ABENDs, JCL errors and other failures.
  • Inheriting parameter setting from UAG for z/OS. This includes, but is not limited to, setting such as dsn_delete_exclude and gdg_processing.
  • Any functionality that includes communication to- or from the Universal Controller.
  • Rerunning jobs that were originally run through the Universal Controller is not supported.

If a serious error occurs that might compromise the execution of the job, UAGRERUN will issue a message describing the error and issue a U4095 ABEND.

Running UAGRERUN Stand-Alone

In order to run UAGRERUN in stand-alone mode, the Job step below should be added as the first step in the job.

//STEP00   EXEC PGM=UAGRERUN,PARMDD=SYSIN
//UNVHIST  DD DSN=<DSNAME>,DISP=(MOD,CATLG),
//         UNIT=SYSALLDA,SPACE=(CYL,(2,2)),
//         DCB=(DSORG=PS,RECFM=VB,BLKSIZE=4104,LRECL=4100)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
NOUAG,
<Other-parameters>
/*

Explanation of JCL statements:

JCL StatementDescription
STEP00

This line executes program UAGRERUN and indicates the parameters can be found in the dataset defined by DDNAME SYSIN.

Program UAGRERUN can likely be found in the system link-list, so a STEPLIB or JOBLIB should not be necessary. If needed, a STEPLIB can be added after the EXEC statement.

UNVHIST

This is an optional DD statement to define the history dataset to UAGRERUN. The history dataset is used to store information about this execution of the job. During a rerun, information about the previous run will be read from this dataset.

If a rerun of the job might be required, this DD statement is required and must point to the same dataset during rerun as was used during the previous run of the job. The same dataset can be used for multiple jobs as long as they do not require concurrent access. Data will never be deleted from this dataset. A new job record will be added for each job. Occasionally, it might be necessary to delete this dataset as it gets too large.

The dataset must be a Physical Sequential dataset (DSORG=PS). It can be a fixed or variable record length. Variable is recommended. The record length must be a minimum of 4096 bytes for fixed and 4100 bytes for variable length records. Any valid block size can be used.

Space requirements for the dataset are dependent on the number of job steps and the number of datasets used by the job. It is however unlikely that even the largest job would need more than 2 tracks of 3390 type DASD.

SYSPRINTThis DD statement defines the output dataset used by UAGRERUN to write its reports.
SYSINDefines the input parameter dataset referenced by the PARMDD keyword on the EXEC statement. A PARM keyword can also be used on the EXEC statement. However, the system limits the total length of all parameters which can be coded on a PARM keyword to 100 bytes. By using PARMDD, this limit is extended to 32,760 bytes.
NOUAGThis parameter is required to run UAGRERUN in stand-alone mode

UAGRERUN Parameter Descriptions

This section describes the parameters used when running UAGRERUN stand-alone.

Any parameter can be commented out by adding a hashtag (‘#’) in front of it.

ParameterDescription
NOUAGThis parameter indicates UAGRERUN is to run stand-alone. It is a required parameter.
RERUN=<Job-ID>Indicates this is a rerun of the job with the specified job ID. The job name cannot have changed between the initial run and the rerun. Information of the job with the specified ID must have been saved in the dataset referenced by the UNVHIST DD statement.
FORCEValid with RERUN only. Force rerun ignores JCL changes between the initial run and the rerun.
GDGPROC={ A | R }

Indicates the GDG dataset processing mode.

When GDGPROC=A is specified, GDG datasets will be processed in absolute mode. The absolute generation (.G0000V00 format) of GDG datasets will be used during rerun processing. This requires use of the UNVHIST dataset.

e.g.: Step STEP01 of a job creates a +1 generation of a GDG dataset. The actual generation produced is MY.SAMPLE.GDG.G0103V00. When the job is rerun, UAGRERUN will delete dataset MY.SAMPLE.GDG.G0103V00 and override the GDG name for STEP01 to recreate MY.SAMPLE.GDG.G0103V00.

When GDGPROC=R is specified, GDG datasets will be processed in relative mode. The relative generation number (0, +1 -1, etc.) will be used to process GDG datasets.

  • Example 1: Step STEP01 of a job creates a +1 generation of a GDG dataset. When the job is rerun, UAGRERUN will not delete the dataset created in the previous run. A new +1 generation will be produced.
  • Example 2: Step STEP01 of a job creates a +1 generation of a GDG dataset. Step STEP02 reads in the +1 generation and prints reports based on the data. When the job is rerun, step STEP01 is not executed. UAGRERUN will adjust the generation of the GDG in STEP02 to reference generation 0 instead.
OPSDSDEL={ Y | N )

This parameter is used to prevent UAGRERUN from deleting datasets.

Default behavior for UAGRERUN is to delete qualifying datasets before executing the job. Setting OPSDSDEL to N prevents UAGRERUN from deleting any datasets.

PREVIEWThis parameter causes UAGRERUN to print its reports only. No datasets will be deleted and no steps other than UAGRERUN will executed.
HELPUAGRERUN will print instructions and end.
START={ STEP [.PROCSTEP] | ( 2 – 255) }

This parameter is used to select the first step to execute. The default is the second step.

The value of the parameter can be a step name, the name of a step in a procedure, or the absolute number of a step. If the selected step executes a JCL procedure, the first step in the procedure will be the first step executed.

END={ STEP [.PROCSTEP] | ( 2 – 255 ) }

This parameter is used to select the last step to execute. The default is the last step.

The value of the parameter can be a step name, the name of a step in a procedure, or the absolute number of a step. If the selected step executes a JCL procedure, the last step in the procedure will be the last step executed.

SKIP={ STEP [.PROCSTEP] | ( 2 – 255 ) }

This parameter is used to skip execution of a step. If the indicated step executes a JCL procedure, none of the steps in the procedure will be executed.

SKIP will cause a step to not be executed, even if it has been previously selected to execute using START/END or NOSKIP.

NOSKIP={ STEP [.PROCSTEP] | ( 2 – 255 ) }

This parameter is used to force execution of a step. If the indicated step executes a JCL procedure, all steps in the procedure will be executed.

NOSKIP will cause a step to be executed, even if it has been previously excluded from execution using START/END or SKIP.

START, END, SKIP and NOSKIP can be combined to select the job steps to execute. Initially, all steps will be selected for execution. If either START or END is specified, they will be applied first. Then, SKIP and NOSKIP will be applied in the order they are specified. On rerun, any step selections from the prior run will be remembered and honored, unless overridden.

Examples

Execute UAGRERUN in stand-alone mode. Run all steps and delete any datasets before execution.

//STEP00   EXEC PGM=UAGRERUN,PARM=NOUAG
//SYSPRINT DD SYSOUT=*


Execute UAGRERUN in stand-alone mode. The job has 5 steps, not counting UAGRERUN. Run only the last 3.

//STEP00   EXEC PGM=UAGRERUN,PARM=’NOUAG,START=4’
//SYSPRINT DD SYSOUT=*


Execute UAGRERUN in stand-alone mode. Rerun steps STEP04 through STEP12 of the job with ID JOB29766 but skip step PRTRPT in the procedure executed by step STEP06. Run in preview mode only.

//STEP00   EXEC PGM=UAGRERUN,PARMDD=SYSIN
//UNVHIST  DD DSN=MY.SAMPLE.DSNAME,DISP=(MOD,CATLG),
//         UNIT=SYSALLDA,SPACE=(CYL,(2,2)),
//         DCB=(DSORG=PS,RECFM=VB,BLKSIZE=4104,LRECL=4100)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
NOUAG,
RERUN=JOB29766,
PREVIEW,
START=STEP04,
END=STEP12,
SKIP=STEP06.PRTRPT
/*