The supplied JCL procedure (DSNUPROC) for invoking a DB2 online utility
One way to invoke a DB2® online utility is to use the supplied JCL procedure, DSNUPROC. DSNUPROC is a standard set of JCL that IBM® provides to invoke online utilities. The advantage of using DSNUPROC is that it limits the amount of JCL that you need to write.
You customize this JCL procedure at installation time (in
SYS1.PROCLIB).
Executing DSNUPROC
To execute the DSNUPROC procedure, write and submit a JCL data set that contains the following statements:
- An EXEC statement that specifies DSNUPROC and any parameters that you want. Possible parameters are listed in DSNUPROC syntax.
- A SYSIN DD statement for the utility control statements.
- DD statements for any other data sets that your job needs except
for SYSPRINT and UTPRINT. The DSNUPROC procedure provides the SYSPRINT
and UTPRINT DD statements for printed output.
For a description of data sets that each utility needs, see Data sets that online utilities use.
DSNUPROC uses the parameters that you supply to build an appropriate EXEC statement that executes an online utility.
For an example of executing DSNUPROC, see Sample DSNUPROC listing.
DSNUPROC syntax
.-LIB=prefix.SSPGM----. .-,SIZE=OM----------. >>-DSNUPROC--+---------------------+--+-------------------+-----> '-LIB=DB2library-name-' '-,SIZE=region-size-' .-,SYSTEM=DSN------------. .-,UID=' '---------------. >--+------------------------+--+------------------------+-------> '-,SYSTEM=subsystem-name-' '-,UID=utility-qualifier-' .-,UTPROC=' '----------------------. >--+----------------------------------+------------------------>< '-,UTPROC=--+-'RESTART'----------+-' +-'RESTART(CURRENT)'-+ +-'RESTART(PHASE)'---+ '-'PREVIEW'----------'
DSNUPROC option descriptions
The
following list describes all the parameters.
- LIB=
- Specifies the data set name of the DB2 subsystem
library.
The default value is prefix.SSPGM.
- SIZE=
- Specifies the region size of the utility execution area; that
is, the value represents the number of bytes of virtual storage that
are allocated to this utility job.
The default value is 0M.
- SYSTEM=
- Specifies the DB2 subsystem
or group attachment name or subgroup attachment name.
The default value is DSN.
- UID=
- Specifies the unique identifier for your utility job. The maximum
name length is 16 characters. If the name contains special characters,
enclose the entire name between apostrophes (for example, 'PETERS.JOB'). Do
not reuse the utility ID of a stopped utility that has not yet been
terminated. If you do use the same utility ID to invoke a different
utility, DB2 tries to restart
the original stopped utility with the information that is stored in
the SYSUTIL directory table.
The default is an empty string. If you do not specify UID, or you specify UID='', DB2 assigns a utility ID of the form user-id.job-name to the utility job. user-id is the user ID. job-name is the job name in the JCL in which DSNUPROC is executed. If the total length of the generated utility ID is longer than 16 bytes, the user ID is truncated to 7 bytes.
- UTPROC=
- Controls restart processing. The default is an
empty string. Use the default if you want to allow DB2 to perform default restart processing; see Restarting an online utility.
To override the default restart behavior, specify one of the following values:
- 'RESTART'
- To restart at the most recent commit point. This option has the same meaning as 'RESTART(CURRENT).'
- 'RESTART(CURRENT)'
- To restart at the most recent commit point. This option has the same meaning as 'RESTART.'
- 'RESTART(PHASE)'
- To restart at the beginning of the phase that executed most recently.
- 'PREVIEW'
- To restart in preview mode. While in preview mode, the utility checks for syntax errors in all utility control statements, but normal utility execution does not take place.
Sample DSNUPROC listing
You can use JCL similar to the following example to invoke DSNUPROC:
//DSNUCOP JOB your-job-statement-parameters
// USER=userid,PASSWORD=password
//*ROUTE PRINT routing-information
//UTIL EXEC DSNUPROC,SYSTEM=DSN,UID=TEMP,UTPROC='
//SYSCOPY DD DSN=MYCOPIES.DSN8D10A.JAN1,DISP=(MOD,CATLG,CATLG),
// UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSIN DD *
COPY TABLESPACE DSN8D10A.DSN8S10D
FULL NO
SHRLEVEL CHANGE
/*The preceding JCL job (DSNUCOP) executes the following DSNUPROC procedure:
//DSNUPROC PROC LIB='DSN!!0.SDSNLOAD',
// SYSTEM=DSN,
// SIZE=0K,UID='',UTPROC=''
//********************************************************************
//* PROCEDURE-NAME: DSNUPROC *
//* *
//* DESCRIPTIVE-NAME: UTILITY PROCEDURE *
//* *
//* FUNCTION: THIS PROCEDURE INVOKES THE ADMF UTILITIES IN THE *
//* BATCH ENVIRONMENT *
//* *
//* PROCEDURE-OWNER: UTILITY COMPONENT *
//* *
//* COMPONENT-INVOKED: ADMF UTILITIES (ENTRY POINT DSNUTILB). *
//* *
//* ENVIRONMENT: BATCH *
//* *
//* INPUT: *
//* PARAMETERS: *
//* LIB = THE DATA SET NAME OF THE DB2 PROGRAM LIBRARY. *
//* THE DEFAULT LIBRARY NAME IS PREFIX.SDSNLOAD, *
//* WITH PREFIX SET DURING INSTALLATION. *
//* SIZE = THE REGION SIZE OF THE UTILITIES EXECUTION AREA.*
//* THE DEFAULT REGION SIZE IS 2048K. *
//* SYSTEM = THE SUBSYSTEM NAME USED TO IDENTIFY THIS JOB *
//* TO DB2. THE DEFAULT IS "DSN". *
//* UID = THE IDENTIFIER WHICH WILL DEFINE THIS UTILITY *
//* JOB TO DB2. IF THE PARAMETER IS DEFAULTED OR *
//* SET TO A NULL STRING, THE UTILITY FUNCTION WILL *
//* USE ITS DEFAULT, USERID.JOBNAME. EACH UTILITY *
//* WHICH HAS STARTED AND IS NOT YET TERMINATED *
//* (MAY NOT BE RUNNING) MUST HAVE A UNIQUE UID. *
//* UTPROC = AN OPTIONAL INDICATOR USED TO DETERMINE WHETHER *
//* THE USER WANTS TO INITIALLY START THE REQUESTED*
//* UTILITY OR TO RESTART A PREVIOUS EXECUTION OF *
//* THE UTILITY. IF OMITTED, THE UTILITY WILL *
//* BE INITIALLY STARTED. OTHERWISE, THE UTILITY *
//* WILL BE RESTARTED BY ENTERING THE FOLLOWING *
//* VALUES: *
//* RESTART(PHASE) = RESTART THE UTILITY AT THE *
//* BEGINNING OF THE PHASE EXECUTED *
//* LAST. *
//* RESTART = RESTART THE UTILITY AT THE LAST *
//* OR CURRENT COMMIT POINT. *
//* *
//* OUTPUT: NONE. *
//* *
//* EXTERNAL-REFERENCES: NONE. *
//* *
//* CHANGE-ACTIVITY: *
//* *
//**********************************************************************
//DSNUPROC EXEC PGM=DSNUTILB,REGION=&SIZE,
// PARM='&SYSTEM,&UID,&UTPROC'
//STEPLIB DD DSN=&LIB,DISP=SHR
//**********************************************************************
//* *
//* THE FOLLOWING DEFINE THE UTILITIES' PRINT DATA SETS *
//* *
//**********************************************************************
//*
//SYSPRINT DD SYSOUT=*
//UTPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//*DSNUPROC PEND REMOVE * FOR USE AS INSTREAM PROCEDURE