Lesson 2.3: Running the COPY utility from a JCL job

Writing job control language (JCL) jobs is a common way to run utilities. Although the JCL standards for your company might differ, this tutorial gives you an idea of how the process works.

In the previous lesson, the MY_EMP2 table was left in COPY-pending status. In this tutorial, you will run the COPY utility to resolve this restricted state.

Before you begin

Before you begin
  • Complete Lesson 2.2: Running the LOAD utility from DB2I.
  • Determine the JCL JOB statement conventions for your site. The JOB statement looks something like the following example:
    //REPORT  JOB 'TUTOR01',MSGLEVEL=(1,1),CLASS=A,MSGCLASS=A,   
//         USER=TUTOR01,PASSWORD=

Procedure

Procedure

  1. Confirm that the table space is in COPY-pending status by running the DISPLAY DATABASE command.
    1. From the DB2I Primary Option Menu, select option 7 DB2 Commands.
    2. In the DB2 Commands panel, issue the DISPLAY DATABASE command. Replace the database name (DSN00016 in the following example) with the name of your database that contains the MY_EMP2 table. 
        F1=Help    F2=Split   F3=Exit    F5=Rfind   F7=Up      F8=Down    F9=Swap     
 F10=Left   F11=Right  F12=Cancel                                               

                               DB2 COMMANDS                    SSID: DB2A      
 ===>                                                                          
                                                                               
 Position cursor on the command line you want to execute and press ENTER       
                                                                               
 Cmd 1 ===> -DISPLAY DATABASE(DSN00016) SPACENAM(*) RESTRICT                      
 Cmd 2 ===>                                                                    
...
  F1=HELP      F2=SPLIT     F3=END       F4=RETURN    F5=RFIND     F6=RCHANGE  
  F7=UP        F8=DOWN      F9=SWAP     F10=LEFT     F11=RIGHT    F12=RETRIEVE
      The results of this command show that your table space is in COPY-pending status: 
       DSNT360I  -DB2A ***********************************                    
 DSNT361I  -DB2A *  DISPLAY DATABASE SUMMARY                            
                 *    RESTRICTED                                        
 DSNT360I  -DB2A ***********************************                    
 DSNT362I  -DB2A     DATABASE = DSN00016  STATUS = RW                   
                    DBD LENGTH = 4028                                   
 DSNT397I  -DB2A                                                        
 NAME     TYPE PART  STATUS            PHYERRLO PHYERRHI CATALOG  PIECE 
 -------- ---- ----- ----------------- -------- -------- -------- ----- 
 MYREMP2  TS    0001 RW,COPY                                           
 MYREMP2  TS                                                            
 ******* DISPLAY OF DATABASE DSN00009 ENDED      ********************** 
 DSN9022I  -DB2A DSNTDDIS 'DISPLAY DATABASE' NORMAL COMPLETION          
 ***
      The first column (NAME) contains the name of the table space that contains the MY_EMP2 table. In this example, that table space name is MYREMP2. Also, notice that DISPLAY DATABASE output includes abbreviations for restricted states. In this case, COPY means COPY-pending status. For more information about DISPLAY DATABASE output, see DSNT361I
  2. Create a member to contain the COPY utility job.
    1. From the ISPF/PDF Primary Option Menu, select option 2 Edit.
    2. In the Edit Entry panel, type the data set name and the new member name in the Name field, and press Enter. 
         Menu  RefList  RefMode  Utilities  Workstation  Help                         
 	 
                                Edit Entry Panel                                
 Command ===>                                                                   
                                                                    More:     + 
 ISPF Library:                                                                  
    Project . . .                                                               
    Group . . . .          . . .          . . .          . . .                  
    Type  . . . .                                                               
    Member  . . .                 (Blank or pattern for member selection list)  
                                                                                
 Other Partitioned, Sequential or VSAM Data Set, or z/OS UNIX file:             
    Name . . . . . 'USER.SRCLIB.TUTORIAL(COPY)'                             + 
    Volume Serial . .           (If not cataloged)                              
                                                                                
 Workstation File:                                                              
    File Name  . .                                                              
                                         Options                                
 Initial Macro  . . . .                     Confirm Cancel/Move/Replace         
 Profile Name . . . . .                     Mixed Mode                          
 Format Name  . . . . .                     Edit on Workstation                 
  F1=Help      F2=Split     F3=Exit      F7=Backward  F8=Forward   F9=Swap      
 F10=Actions  F12=Cancel
      The EDIT panel opens for the new member.
  3. In the EDIT panel, type the JCL job for the COPY utility.
    You can copy the following example JCL and change it as needed. 
    //COPYTUT JOB 'TUTOR01',MSGLEVEL=(1,1),CLASS=A,                         
 //         USER=TUTOR01                              
 //*                                                                     
 //STEP1 EXEC DSNUPROC,SYSTEM=DB2A,                                      
 //        UID='TUTUTIL001',UTPROC=''                                    
 //SYSIN DD *                                                            
   TEMPLATE C1 DSN &JOBNAME..&LOCREM..&PRIBAC.                             
             DISP (MOD,CATLG,DELETE)                                     
  COPY TABLESPACE  DSN00016.MYREMP2                                       
      COPYDDN (C1,C1) RECOVERYDDN (C1,C1)                                 
 //
    This example JCL includes the following items:
    A JOB statement
    The JOB statement gives this job the name COPYTUT, identifies the programmer as TUTOR01, and defines several other parameters. Edit this statement to meet the standards for your organization. For a description of the JOB statement and syntax, see JCL statements: What does the JOB statement do? (z/OS basic skills).
    An EXEC statement
    The EXEC statement defines the job step and invokes the DSNUPROC procedure to run the utility. DSNUPROC is a standard procedure that is included with Db2 to invoke utilities. By invoking this procedure, you can avoid writing extra JCL. Make sure that you pass the appropriate parameters to this procedure. For example, the SYSTEM parameter must contain your Db2 subsystem name. For a description of the parameters, see The supplied JCL procedure (DSNUPROC) for invoking a Db2 online utility.
    TEMPLATE utility control statement
    The SYSIN DD statement includes a TEMPLATE utility control statement. The TEMPLATE utility is a Db2 utility that you can use to define templates for any data sets that you need for utility output. Essentially, a template eliminates the need to define JCL DD statements for every data set that you must allocate. In this case, the TEMPLATE utility defines a template for the image copy data sets. The name of the template is C1. The DSN option defines the naming convention for the data sets. You can modify this template to accommodate the data set conventions for your organization. For a description of the TEMPLATE syntax, see Syntax and options of the TEMPLATE control statement.
    COPY utility control statement
    The COPY utility control statement specifies that the utility will create four image copies: one primary copy and one backup copy at the local site, and one primary copy and one backup copy at the recovery site. The COPY utility is to use the C1 template to allocate these data sets. In the COPY statement, change the qualified table space name to the name of your table space that is in COPY-pending status. Notice that the COPY utility, like many utilities, operates on the table space. For help with the COPY statement syntax, see Syntax and options of the COPY control statement.
    Remember: All of your JCL statements (the ones that start with //) must start in the first column. JCL also has rules about which text can go in certain columns. For help with JCL, see Basic JCL concepts (z/OS Basic Skills).
  4. Submit the job to run the utility. 
      File  Edit  Edit_Settings  Menu  Utilities  Compilers  Test  Help            
 
 EDIT       USER.SRCLIB.TUTORIAL(COPY) - 01.00              Columns 00001 00072 
 Command ===> SUB                                           Scroll ===> PAGE 
 ****** ***************************** Top of Data ******************************
 000200 //COPYTUT JOB 'TUTOR01',MSGLEVEL=(1,1),CLASS=A,                         
 000300 //         USER=TUTOR01,PASSWORD=C0DESHOP                               
 000310 //*                                                                     
 000600 //STEP1 EXEC DSNUPROC,SYSTEM=DB2A,                                      
 000610 //        UID='TUTUTIL001',UTPROC=''                                    
 000700 //SYSIN DD *                                                            
 001000 TEMPLATE C1 DSN &JOBNAME..&LOCREM..&PRIBAC.                             
 001100             DISP (MOD,CATLG,DELETE)                                     
 001200 COPY TABLESPACE  DSN00016.MYREMP2                                       
 001300     COPYDDN (C1,C1) RECOVERYDDN (C1,C1)                                 
 001400 //                                                                      
 ****** **************************** Bottom of Data ****************************
    If you receive the message ENTER JOBNAME CHARACTER(S) -, type any character and press Enter.
    A message indicates that the job was submitted and provides the job number. 
    JOB COPYTUT(JOB00174) SUBMITTED  
***
  5. View the job output.
    1. Issue the TSO SDSF ST command to display the job output in the status of jobs log.
    2. Find your job in the list and issue the S line command next to it to display the utility output.
    3. Determine if the utility completed successfully.
      • A utility return code of DSNUTILB 0000 indicates that the utility completed successfully.
      • Any utility return code other than DSNUTILB 0000 indicates that the utility did not complete successfully. Use the Db2 utility messages to debug the error. Db2 utility messages begin with DSNU. To see these messages, type BOTTOM in the Command field, and press Enter. Press PF11 to scroll right.
      • If you see JCL errors, use the following resources to help correct the errors:

      To correct any errors in your JCL or to debug any other problems, press PF3 multiple times to return to the data set member that contains your JCL. Correct the errors and then repeat steps 4 and 5 until the job completes successfully.

  6. View the image copies:
    1. Press PF3 until you return to the ISPF/PDF Primary Option Menu.
    2. Type option 3.4 to open the DSLIST utility.
    3. In the Data Set List Utility panel, type COPYTUT in the Dsname level field, and press Enter.

      Your image copy data sets begin with the qualifier COPYTUT because of the template that you used. The template specified that your job name (indicated by the variable &JOBNAME.) will be the first qualifier in the data set name. In this case, your job name was COPYTUT. For a complete description of template names and variables, see Syntax and options of the TEMPLATE control statement.

    The data sets that contain the image copies are listed. 
       Menu  Options  View  Utilities  Compilers  Help                              
 	 
 DSLIST - Data Sets Matching COPYTUT                                 Row 1 of 4 
 Command ===>                                                  Scroll ===> PAGE 
                                                                                
 Command - Enter "/" to select action                  Message           Volume 
 -------------------------------------------------------------------------------
          COPYTUT.L.B                                                    SCR03  
          COPYTUT.L.P                                                    SCR03  
          COPYTUT.R.B                                                    SCR03  
          COPYTUT.R.P                                                    SCR03  
 ***************************** End of Data Set list ****************************
                                                                                
  F1=Help    F2=Split   F3=Exit    F5=Rfind   F7=Up      F8=Down    F9=Swap     
 F10=Left   F11=Right  F12=Cancel

    If you view the contents of the data sets, you might notice that the data is not in an easily readable format. The image copies are not written for people to read, but for Db2 to use for recovery.

  7. Verify that the COPY-pending status was resolved for the table space that contains the MY_EMP2 table. In this example, the table space name is MYREMP2.
    1. From the DB2I Primary Option Menu, type option 7 Commands.
    2. Issue the following DISPLAY DATABASE command. Remember to change the database name (DSN00016) and table space name (MYREMP2) to your values. 
        F1=Help    F2=Split   F3=Exit    F5=Rfind   F7=Up      F8=Down    F9=Swap     
 F10=Left   F11=Right  F12=Cancel                                               

                               DB2 COMMANDS                    SSID: DB2A      
 ===>                                                                          
                                                                               
 Position cursor on the command line you want to execute and press ENTER       
                                                                               
 Cmd 1 ===> -DISPLAY DATABASE(DSN00016) SPACENAM(MYREMP2)                      
 Cmd 2 ===>                                                                    
...
  F1=HELP      F2=SPLIT     F3=END       F4=RETURN    F5=RFIND     F6=RCHANGE  
  F7=UP        F8=DOWN      F9=SWAP     F10=LEFT     F11=RIGHT    F12=RETRIEVE
      The following output is displayed. The status of the table space is read/write only, which means that the table space is no longer in a restrictive state. 
      DSNT360I  -DB2A ***********************************                   
DSNT361I  -DB2A *  DISPLAY DATABASE SUMMARY                           
                *    GLOBAL                                           
DSNT360I  -DB2A ***********************************                   
DSNT362I  -DB2A     DATABASE = DSN00016  STATUS = RW                  
                   DBD LENGTH = 4028                                  
DSNT397I  -DB2A                                                       
NAME     TYPE PART  STATUS            PHYERRLO PHYERRHI CATALOG  PIECE
-------- ---- ----- ----------------- -------- -------- -------- -----
MYREMP2  TS    0001 RW                                                
MYREMP2  TS                                                           
******* DISPLAY OF DATABASE DSN00016 ENDED      **********************
DSN9022I  -DB2A DSNTDDIS 'DISPLAY DATABASE' NORMAL COMPLETION         
***

Lesson checkpoint

In this lesson, you learned how to complete the following tasks:

  • Run a utility from a JCL job
  • Create a template for your data sets by using the TEMPLATE utility
  • Check the status of a table space by issuing a DISPLAY DATABASE command