Configuration for CA-7

IBM® AD Connect for Mainframe is configured to access CA7 by using the CA7 CCI P-P (program to program) interface. However, for extremely large batch schedules, it can consume large amounts of memory on loading. For these cases, it is preferable to use the AD-CA7 batch interface. In addition, if you want to perform an incremental update to retrieve only the CA7 data that has changed, since the initial bulk load (or last incremental update), it is necessary to use the AD-CA7 batch interface.

If you configured your AD installation to use the CA7 batch interface in earlier versions of IBM AD, be advised that beginning with IBM AD V5.1.0, the configuration process has changed and you need to review the remainder of this section. This change is necessary to allow for incremental updates from CA7 and to fully support this feature on systems running either JES2 or JES3.

The IBM AD Connect for Mainframe started task implements the CA7 batch interface by submitting a customized batch job to the internal reader. The batch job runs the necessary CA7 utilities and writes the data to a dataset. When complete, the final job step posts the AD Connect for Mainframe started task to indicate that the data is now available.

For this process to work, you must customize two sample jobs, provided in the SIAYSAMP dataset of the SMP/E distribution for IBM AD Connect for Mainframe. These jobs are saved in a suitable JCL library that can be read by the IBM AD Connect for Mainframe started task.

JCL Customization Process

All required samples are contained in the SMP/E *.SIAYSAMP library, as part of the SMP/E distribution of FMID HALT510, which includes two sample jobs and three Restructured Extended Executor (REXX) sample programs.

The three REXX programs, IAYRXCA7, IAYRXCAC and IAYDSNDL, don't need to be modified in any way. They can remain in the SIAYSAMP library or can be copied to another suitable library. All SYSEXEC DD names in the JCL sample need to be set to reference the location of these REXX programs. These changes are outlined in the following JCL customization steps.

Important:
  • Make sure to tailor the JCL according to your site standards. Be advised that the SYSIN data might change according to your site standards.
  • Make sure that this job is running on the same LPAR as the AD Connect for Mainframe started task. If your shop is configured in such a way that the job might be scheduled on another system, make sure that you use the SYSTEM=* parameter in the job card, as shown in the example. The * indicates the system that submitted the job. It does not represent a wildcard substitution for any system.
  • Comments can be added or deleted to either of the sample jobs, but the size of either job must not exceed 80 lines (records).
  • Do not add a job terminator card '//' to the end of any of the customized jobs.
  • Do not turn on ISPF PACK for any customized job.
  • Remove the '<===Change(n)' markers when done.
The following two samples jobs need to be configured for your site:
  1. The IAYCA7X job

    When configured, this job is submitted by the AD Connect for Mainframe started task whenever a bulk load of all CA7 data is requested by the IBM AD Build Client or IBM AD Analyze server.

  2. The IAYCA712 job

    When configured, this job is submitted by the AD Connect for Mainframe started task whenever an incremental update of CA7 data is requested by the IBM AD Build Client or IBM AD Analyze server. The incremental update extracts only the changes that are made since the last incremental update, or the initial bulk load.

Specific configurations steps for the IAYCA7X job:
Note: Each step that is listed below is keyed by a change number (n). The sample JCL contains a change marker of the form <===Change(n) and indicates the location of the corresponding change.
  1. Modify the job card to meet your site/system requirements.
  2. Set JOBLIB to the IBM AD Connect for Mainframe SMP/E *.SIAYAUTH library.
  3. Set the symbolic SYSINDSN parameter to a PDS/E library where this job can write a temporary CA7 report control card. Any suitable library can be used, but the member name must be set to CA7T1%TK as shown in the sample. Ensure that the IBM AD Connect for Mainframe started task has UPDATE access to this library.
  4. Set the symbolic CA7PRINT parameter to a sequential dataset name. Any suitable dataset name can be user, but the final %TK prefix must be retained. The AD Connect for Mainframe started task replaces all instances of %TK with a unique task number (up to MAXTASK) so that each subtask can run in parallel with a unique dataset name. Ensure that the IBM AD Connect for Mainframe started task has UPDATE access to this sequential dataset.
  5. SYSEXEC DD needs to point to a library, which contains the IBM AD REXX samples. You can use the IBM AD Connect for Mainframe SMP/E *.SIAYSAMP library if you want, since no user modifications need to be made to the REXX samples.
  6. SYSEXEC DD needs to point to a library, which contains the IBM AD REXX samples. You can use the IBM AD Connect for Mainframe SMP/E *.SIAYSAMP library if you want, since no user modifications need to be made to the REXX samples.
  7. STEPLIB needs to point to your CA7 CAL2LOAD library, which contains the SASSBSTR program.
  8. Set UCC7CMDS DD to your CA7 communications dataset.
  9. Set BATCHIN DD to your CA7 BATCHIN dataset.
  10. Set BATCHOUT DD to your CA7 BATCHOUT dataset.
  11. SYSPRINT must refer to the sequential dataset referenced by the symbolic CA7PRINT parameter, set previously in step (4). The dataset name cannot be set to the symbolic CA7PRINT parameter at this location because the AD Connect for Mainframe started task must extract the full dataset name while reads the JCL member. It occurs before JES substitutes the symbols. The DSN field must remain on the same line as SYSPRINT DD.
  12. Change the MASTER user ID to a valid CA7 user, authorized to issue the LIOB command.
For reference, the following represents a copy of the IAYCA7X sample job that is contained in the SMP/E *.SIAYSAMP distribution library for IBM AD Connect for Mainframe:
//IAYCA7X  JOB NOTIFY=&SYSUID             <===Change(1)                   
//*********************************************************************   
//*                                                                   *   
//* Licensed materials - Property of IBM                              *   
//* 5737-B16 Copyright IBM Corp. 2017, 2018                           *   
//* All rights reserved                                               *   
//* US Government users restricted rights  -  Use, duplication or     *   
//* disclosure restricted by GSA ADP schedule contract with IBM Corp. *   
//*                                                                   *   
//*-------------------------------------------------------------------*   
//* CA7 SASSBSTR BATCH TERMINAL INTERFACE JCL                         *   
//*-------------------------------------------------------------------*   
//* !!! THIS JCL NEEDS TO BE CUSTOMIZED BEFORE USE !!!                *   
//*-------------------------------------------------------------------*   
//* Please refer to file $README in the SIAYSAMP library for a        *   
//* description of each customization step, '<===Change(n)'           *   
//*********************************************************************   
//JOBLIB  DD DISP=SHR,DSN=IAYV510.SIAYAUTH   <===Change(2)                
// SET SYSINDSN='IAYV510.SAMP.JCL(CA7T1%TK)' <===Change(3)                
// SET CA7PRINT='IBMUSER.CA7.REPORT.FILE%TK' <===Change(4)                
//*---------------------------------------------------------------------  
//* This step will call Rexx program IAYDSNDL to clean up work datasets   
//* from the previous run.                                                
//*---------------------------------------------------------------------  
//STEP005 EXEC PGM=IKJEFT01,PARM='IAYDSNDL &CA7PRINT'                     
//SYSEXEC  DD DISP=SHR,DSN=IAYV510.SIAYSAMP           <===Change(5)       
//SYSTSPRT DD  SYSOUT=*                                                   
//SYSTSIN  DD  DUMMY                                                      
//*---------------------------------------------------------------------  
//* This step will call Rexx program IAYRXCA7 to build the CA7 control    
//* cards and call CA7 report utility program SASSBSTR.                   
//*---------------------------------------------------------------------  
//STEP010 EXEC PGM=IKJEFT01,PARM='IAYRXCA7 &SYSINDSN'                     
//SYSEXEC  DD DISP=SHR,DSN=IAYV510.SIAYSAMP        <===Change (6)         
//*                                                                       
//STEPLIB  DD DISP=SHR,DSN=CA7V12.CAL2LOAD         <===Change (7)         
//*      
//UCC7CMDS DD DISP=SHR,DSN=CA7V12.COMMDS           <===Change (8)       
//BATCHIN  DD DISP=SHR,DSN=YOUR.CA7.BATCHI#1       <===Change (9)       
//BATCHOUT DD DISP=SHR,DSN=YOUR.CA7.BATCHO#1       <===Change (10)      
//SYSPRINT DD DISP=(NEW,CATLG),DSN=IBMUSER.CA7.REPORT.FILE%TK, <=Chg(11)
// SPACE=(TRK,(50,20),RLSE),DCB=(RECFM=FBA,LRECL=133)                   
//SYSTSPRT DD SYSOUT=*                                                  
//SYSTSIN  DD DUMMY                                                     
//SYSUDUMP DD SYSOUT=*                                                  
//*                                                                     
//CA7SYSIN DD *,DLM=##  <===Change(12) (replace ID MASTER if necessary) 
/LOGON MASTER                                                           
LJOB,JOB=*,LIST=ALL                                                     
/LOGOFF                                                                 
##
Specific configurations steps for the IAYCA712 job:
Note: Each step that is listed below is keyed by a change number (n). The sample JCL contains a change marker of the form <===Change(n) and indicates the location of the corresponding change.
  1. Modify the job card to meet your site/system requirements.
  2. Set JOBLIB to the IBM AD Connect for Mainframe SMP/E *.SIAYAUTH library.
  3. Set PROCS JCLLIB to reference the CA7 PROC LIB where the CA7LOG procedure is stored.
  4. Set the symbolic SYSINDSN parameter to a PDS/E library where this job can write a temporary CA7 report control card. Any suitable library can be used, but the member name must be set to CA7T1%TK as shown in the sample. Ensure that the IBM AD Connect for Mainframe started task has UPDATE access to this library.
  5. Set the symbolic CA7PRINT parameter to a sequential dataset name. Any suitable dataset name can be user, but the final %TK prefix must be retained. The AD Connect for Mainframe started task replaces all instances of %TK with a unique task number (up to MAXTASK) so that each subtask can run in parallel with a unique dataset name. Ensure that the IBM AD Connect for Mainframe started task has UPDATE access to this sequential dataset.
  6. SYSEXEC DD needs to point to a library, which contains the IBM AD REXX samples. You can use the IBM AD Connect for Mainframe SMP/E *.SIAYSAMP library if you want, since no user modifications need to be made to the REXX samples.
  7. SYSEXEC DD needs to point to a library, which contains the IBM AD REXX samples. You can use the IBM AD Connect for Mainframe SMP/E *.SIAYSAMP library if you want, since no user modifications need to be made to the REXX samples.
  8. SYSPRINT must refer to the sequential dataset referenced by the symbolic CA7PRINT parameter, set previously in step (4). The dataset name cannot be set to the symbolic CA7PRINT parameter at this location because the AD Connect for Mainframe started task must extract the full dataset name while reads the JCL member. It occurs before JES substitutes the symbols.

    The DSN field must remain on the same line as SYSPRINT DD. Other SYSPRINT DD fields may be moved as needed.

  9. Set UCC7HIST DD to reference a concatenation of the following datasets:
    1. The current generation of the CA7 history dataset.
    2. The CA7 primary log dataset.
    3. The CA7 secondary log dataset.
  10. Set UCC7ARCH DD to reference the current generation of the CA7 archive dataset.
Note: Ensure that the AD Connect for Mainframe started task has READ access to the CA7 datasets referenced in steps (8) and (9).
For reference, the following represents a copy of the IAYCA712 sample job that is contained in the SMP/E *.SIAYSAMP distribution library for IBM AD Connect for Mainframe:
//IAYCA712 JOB NOTIFY=&SYSUID             <===Change(1)                   
//*********************************************************************   
//*                                                                   *   
//* Licensed materials - Property of IBM                              *   
//* 5737-B16 Copyright IBM Corp. 2017, 2018                           *   
//* All rights reserved                                               *   
//* US Government users restricted rights  -  Use, duplication or     *   
//* disclosure restricted by GSA ADP schedule contract with IBM Corp. *   
//*                                                                   *   
//*-------------------------------------------------------------------*   
//* CA7 HISTORY REPORTING JCL -used for incremental updates           *   
//*-------------------------------------------------------------------*   
//* !!! THIS JCL NEEDS TO BE CUSTOMIZED BEFORE USE !!!                *   
//*-------------------------------------------------------------------*   
//* Please refer to file $README in the SIAYSAMP library for a        *   
//* description of each customization step, '<===Change(n)'           *   
//*********************************************************************   
//JOBLIB  DD DISP=SHR,DSN=IAYV510.SIAYAUTH   <===Change(2)                
//PROCS  JCLLIB ORDER=CA7V12.SYSGEN.JCLLIB   <===Change(3)                
//*                                                                       
// SET SYSINDSN='IAYV510.SAMP.JCL(CA7TC%TK)'      <===Change(4)           
// SET CA7PRINT='IBMUSER.CA7.REPORT12.FILE%TK'    <===Change(5)           
//*---------------------------------------------------------------------  
//* This step will call Rexx program IAYDSNDL to clean up work datasets   
//* from the previous run.                                                
//*---------------------------------------------------------------------  
//STEP005 EXEC PGM=IKJEFT01,PARM='IAYDSNDL &CA7PRINT'                     
//SYSEXEC  DD DISP=SHR,DSN=IAYV510.SIAYSAMP         <===Change(6)         
//SYSTSPRT DD  SYSOUT=*                                                   
//SYSTSIN  DD  DUMMY                                                      
//*---------------------------------------------------------------------  
//* This step will call Rexx program IAYRXCAC to build the CA7 control    
//* cards.                                                                
//* Ensure that the AD Connect started task has READ access to the CA7    
//* datasets referenced in steps (9) and (10).                            
//*---------------------------------------------------------------------  
//STEP010 EXEC PGM=IKJEFT01,PARM='IAYRXCAC &SYSINDSN'                     
//SYSEXEC  DD DISP=SHR,DSN=IAYV510.SIAYSAMP         <===Change(7)         
//SYSTSPRT DD SYSOUT=*                                                    
//SYSTSIN  DD DUMMY                                                       
//SYSPRINT DD DSN=IBMUSER.CA7.REPORT12.FILE%TK,     <===Change(8)         
//            DISP=(NEW,CATLG),                                           
//            SPACE=(TRK,(50,20),RLSE),DCB=(RECFM=FBA,LRECL=133)          
//CA7SYSIN DD *                                                           
SASSHR                                                                    
/*                                                                        
//*---------------------------------------------------------------------  
//* This step will call CA7 history report program SASSHIS8.              
//*---------------------------------------------------------------------  
//REPORT EXEC  CA7LOG,PG=SASSHIS8,PA='O,100000'                           
//SASSRA01 DD  SYSOUT=*,DCB=BLKSIZE=133                                   
//SASSRA02 DD  SYSOUT=*,DCB=BLKSIZE=133                                   
//SASSRA03 DD  SYSOUT=*,DCB=BLKSIZE=133                                   
//COMMANDS DD  DSN=&&COMMANDS,DISP=(,PASS),                               
//             DCB=(RECFM=FB,LRECL=80,BLKSIZE=0),                         
//             UNIT=3390,SPACE=(CYL,(1,1))                                
//HR25REPT DD  DSN=&&HR25REPT,DISP=(,PASS),                               
//             DCB=(RECFM=FB,LRECL=82,BLKSIZE=0),                         
//             UNIT=3390,SPACE=(TRK,(1,1),RLSE)                           
//HR25CSV  DD  DSN=&&HR25CSV,DISP=(,PASS),                                
//             DCB=(RECFM=VB,LRECL=3000,BLKSIZE=0),                       
//             UNIT=3390,SPACE=(TRK,(1,1),RLSE)                           
//UCC7HIST DD  DISP=SHR,DSN=CA7.LOG.HISTORY(+0)     <===Change(9)         
//         DD  DISP=SHR,DSN=CA7V12.LOGP                                   
//         DD  DISP=SHR,DSN=CA7V12.LOGS                                   
//UCC7ARCH DD  DISP=SHR,                                                  
//             DSN=CA7V12.LOGARCH(+0)               <===Change(10)        
//SYSLIST  DD DISP=OLD,DSN=&CA7PRINT                                      
//*                                                                       
//SYSIN DD DISP=SHR,DSN=&SYSINDSN
For reference, the following represents a copy of the IAYDSNDL sample job that is contained in the SMP/E *.SIAYSAMP distribution library for IBM AD Connect for Mainframe:
Note: Early builds of FMID HALT510 did not contain REXX program IAYDSNDL. If IAYDSNDL is not present in SMP/E *.SIAYSAMP distribution library and you require job data from CA7, create this member in the SYSEXEC library that is referenced in sample jobs IAYCA7X and IAYCA712.
/* rexx */                                                                
/**********************************************************************/  
/*  IAYDSNDL                                                          */  
/*  Licensed materials - Property of IBM                              */  
/*  5737-B16 Copyright IBM Corp. 2017, 2018                           */  
/*  All rights reserved                                               */  
/*  US Government users restricted rights  -  Use, duplication or     */  
/*  disclosure restricted by GSA ADP schedule contract with IBM Corp. */  
/*                                                                    */  
/**********************************************************************/  
                                                                          
arg dsname                                                                
                                                                          
   dsname = strip(dsname)                                                 
   upper dsname                                                           
   if dsname = '' then                                                    
      return 7                                                            
                                                                          
   xx = SYSDSN("'"dsname"'")                                              
   if xx = 'OK' then                                                      
      "DELETE ('"dsname"') "                                              
   return 0                                                               
                                                                          
exit 0