The supplied JCL procedure (DSNUPROC) for invoking a Db2 online utility
One way to invoke a Db2 online utility is to execute the supplied JCL procedure DSNUPROC. The advantage of using DSNUPROC is that it limits the amount of JCL that you need to write.
Executing DSNUPROC
To execute the DSNUPROC procedure, write and submit a JCL job 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 utility job needs except for SYSPRINT and UTPRINT. DSNUPROC provides the SYSPRINT and UTPRINT DD statements for printed output.
DSNUPROC uses the parameters that you supply to build an EXEC statement that executes an online utility.
DSNUPROC syntax
DSNUPROC option descriptions
- LIB=
- Specifies the data set name
of the Db2 subsystem library.
The default value is prefix.SDSNLOAD.
- 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.
To override the default restart behavior, specify one of the following values:
- 'RESTART'
- Restarts at the most recent commit point.
- 'RESTART(CURRENT)'
- Restarts at the most recent commit point. RESTART and RESTART(CURRENT) have the same meaning.
- 'RESTART(PHASE)'
- Restarts at the beginning of the phase that was being processed.
- 'PREVIEW'
- Restarts 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.
Related information:
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.DSN8D13A.JAN1,DISP=(MOD,CATLG,CATLG),
// UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSIN DD *
COPY TABLESPACE DSN8D13A.DSN8S13D
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