How to setup CA Disk interface CA Vantage and JES2 exit6?
Article ID: 51953
Updated On:
Products
Issue/Introduction
Description:
Simple steps to configure auto restore processing and Jes2 exits, test the Jes2 exit installation and auto restore command.
Solution:
IMPORTANT: This article contains information about modifying the registry.
Before you modify the registry, make sure to create back up of the registry and ensure that you understand how to restore the registry if a problem may occur.
For more information about how to back up, restore, and edit the registry, please review the relevant Microsoft Knowledge Base articles on support.microsoft.com.
CA Disk Auto Restore Manager (ARM) (CA Vantage User's Guide 3-16)
Part 1.
Configure for CA Disk
To configure CA Disk, review the following sections and perform the tasks as needed.
Run job J08DISK from the Install library
Monitor Subfiles of the CA Disk Files Data Set
To view and analyze all the subfiles of your CA Disk Files Data Sets or FILES Databases, you must identify them to CA Vantage. If you have converted any of your CA Disk FILES Data Sets to FILES Databases, the name of the FILES Data Set is used to locate the associated FILES Database, that is, you only have to identify FILES Data Set names. The CA Disk system will dynamically determine the conversion status of the FILES Data Set and access the FILES Databases where appropriate.
Specify all the names within a <FILELIST> section in the CONFIG member of PARMLIB. If the CONFIG member does not exist in your PARMLIB, simply copy it from the SAMPLES library.
To use <FILELIST>, perform the following steps:
- Edit PARMLIB member CONFIG, and create a <FILELIST> section at the end.
- Supply the names of your Files Data Sets.
If the list is all unconverted FILES Data Sets or if it is all converted FILES Data Sets (FILES Databases), the list is processed in the order specified. If the list contains a mixture of unconverted and converted entries (FILES Data Sets and FILES Databases), the list is split into two internal lists with the FILES Databases being accessed first and the FILES Data Sets being accessed second. The order of each of those internal lists is based on the order of the original list. The list would look something like the following. A maximum of 255 are supported.
<FILELIST>
CA.DISK.FILES1
CA.DISK.FILES2 - Specify sysparm FILELIST (<FILELIST>) to activate the section. Use the Config Client to specify this system parameter.
- Specify sysparm SUDMS to activate the CA Disk interface. Use the Config Client to specify this system parameter. Alternatively, if you have no more than 15 Files data sets, you can use system parameters FILES1 to FILES15 to specify their names. But if you have more than 15, you must use the FILELIST option. The order of this list of FILES is handled just like the list created by using FILELIST.
For more information about Input Lists, see the chapter "Configuring Multiple Systems" in this guide, as well as the topic "Input Lists" in the Reference Guide.
Note: If you use CA Disk for Unix System Services, simply include its files data sets as entries as described above, whichever method you decide to use.
Part 2
Auto Restore Processing
CA Disk provides a native Auto Restore function that initiates a started task, DMSAR, each time a data set under its archive control is referenced. The DMSAR task restores the needed data set while the requester (an online user or a batch job) waits. When the restore is complete, the DMSAR task terminates.
The Auto Restore Manager (ARM) enhances this process in two ways:
ARM can start one or more DMSAR servers, optionally dedicating them to either tape or disk restore work, and leave them active, that is, waiting for more work. These features increase auto restore performance.
ARM also provides a JES2 Exit that makes batch processing more efficient when the batch JCL references archived data sets. Instead of letting the job tie up an initiator while the needed data sets are restored one by one, the JES2 Exit support holds the job, and routes all the needed restores to ARM at once (where multiple servers restore the data sets more efficiently by grouping the restores so that all data sets on an archive volume are processed together, reducing the number of required tape mounts and the time required). ARM then releases the job when all restores are completed. Use of the JES2 Exit is optional but strongly recommended.
ARM provides the system parameter ARDSQTAP which causes outstanding requests for the same tape volume to be processed sequentially by the same DMSAR server. This increases efficiency by reducing the number of tape mounts.
Configure the Basic ARM
To configure the Auto Restore Manager (ARM), use the Config Client to specify the appropriate system parameters.
Activate ARM and Receiver/Dispatcher Components
ARM also requires that the Receiver/Dispatcher component be active. To activate the ARM and the Receiver/Dispatcher components at system startup, uncomment the following statements in the CONFIG member of your PARMLIB, but do not change their order.
*COMP=RCDSP UNCOMMENT IF ARM/ALLOMGR USED (SUARH=Y OR SUPLS=Y) *COMP=ARM UNCOMMENT IF ARM IS USED (SUARH=Y)
Note: If you uncomment the COMP=ARM statement but fail to uncomment the COMP=RCDSP, auto restores will fail because the requests can not be received, and a soft loop will occur at system shutdown, issuing the following message:
VAN0902I Comp=ARM Shutdown in Progress. Waiting for Normal Completion or Forced Termination.
Specify sysparms SUARH (Y) and QUEUE in VKGPAMRS - member VPPD0H contains default sysparms CA DISK Interface
Run Job J01QFILE from the Install libraray
Identify ARM to CA Disk
To identify ARM to CA Disk perform the following steps:
- In the CA Disk PARMLIB, set system parameter SAMSYSNM to the name of the CA Vantage subsystem. That is, ensure that the CA Disk system parameter SAMSYSNM has the same value as CA Vantage system parameter SUBSYSN. The CA Vantage default value is (SAMS). Because the name must be four characters long, use quotation marks if the last character is a blank.
- To identify the subsystem to the CA Disk catalog management hook, issue the commands:
S DMSAR,DMSAR=REMOVE
(if the CA Disk auto restore hook is already active)
S DMSAR,DMSAR=INSTALL
SYSPROG - Configure the Supplied JES2 Exit
The supplied exit is for JES2 Exit 6, and is implemented as a standard JES2 exit, allowing the scanning of internal text. Before installing the exit, see the IBM manual, System Programming Library: JES2 User Modifications and Macros, to read about JES2 exits and considerations for their use.
To configure the JES2 Exit, do the following:
- Tailor the JES2 Exit Source Code (Optional)
Normally there is no need for you to modify the source code (programs KNGJX006 and KNGED009 in the SAMSRC library). However, KNGED009 uses user-field DTEUSER3 in the Converter DTE to store and retain information that is needed between calls to the Exit. If this field is already being used by other installation exits on your system, you must change the source code to use one of the other user-fields (1-4). Contact your JES2 systems programmer to make this determination. KNGJX006 is a small module loaded by JES2. When CA Vantage is active, KNGJX006 calls KNGED009.
KNGED009 is a larger module loaded by CA Vantage. KNGED009 performs the actual work.
When you update to a new release of CA Vantage, you must reassemble KNGED009 but not KNGJX006. When you change the level of JES2 macros, you must reassemble both programs. - Assemble and Link the JES2 Exit6 Code
Verify that the SMP/E installation has assembled and linked the two exit programs
without errors:
KNGJX006 into DSN=sys2.%%SMPPFX%%.SAMLINK
KNGED009 into DSN=%%SMPPFX%%.LOADLIB
If you modified the source code, you must assemble and link the modified programs again. SMP/E jobs to do the reassemblies and links can be found in members KNGJX006 and KNGED009 in the INSTALL library. If you have system parameter ARACALTR set to (Y), then see further explanation for this Sysparm in the Reference Guide. In addition, depending on how your security system is configured, modifications to the RACROUTE macro in KNGED009 may be required. - Ensure that the SAMLINK library is in your system's linklist (the appropriate LNKLSTxx member in SYS1.PARMLIB). Be sure that the SAMLINK data set is APF authorized.
Note: In prior releases you may have moved KNGJX006 into the JES2 LOADLIB or another linklist data set. If so, it is recommended that you find and delete the old copy. Executing the exit from the SAMLINK linklist library makes future upgrades through SMP/E easy and reliable. - Specify the new exit in the JES2 start-up parameters
The default JES2 start-up parameters are in the data set pointed to by the //HASPPARM DD statement in the JES2 procedure in SYS1.PROCLIB.
Add the following statements to your system's JES2 start-up parameters:
LOADMOD (KNGJX006)
EXIT006 ROUTINE=(KNGJE006),ENABLE
If your installation already has a JES2 Exit6 installed, say USER06, you can add the CA Vantage Exit6 to the list, as in the following example:
LOADMOD(USER06)
LOADMOD(KNGJX006)
EXIT006 ROUTINE=(USER06,KNGJE006),ENABLE
The CA Vantage JES2 Exit6 should be called last so that it sees changes to the internal text made by prior exits. - Activate the new JES2 Exit
To do this, you must restart the JES2 system. Follow your installation procedures for restarting JES2.
Observe the following points:
Whenever you use SMP/E to assemble and link a new version of the exit into the SAMLINK library, it will not be active until you restart JES2.
The exit never invokes any restores until CA Vantage is started (with ARM active). - Provide filters in PARMLIB member ARJES2XT to improve efficiency.
The JES2 exit must potentially find all data sets referenced in the JCL, and check the catalog to see which have been archived. You can eliminate some of this checking by specifying filter lists in member ARJES2XT in the CA Vantage PARMLIB. Create ARJES2XT by copying it from the SAMPLES library.
You can reduce the amount of checking in three ways (three filter lists). You can skip entire jobs based upon pattern job names to include or exclude. You can skip the checking for all data sets in a job step based upon pattern names for the program being executed. Or you can skip the checking based upon pattern names for the data sets themselves.
In other words, you can customize the ARJES2XT PARMLIB member with include and exclude lists for JOBNAMES, PGMNAMES and DSNAMES. The exit will check to see if a data set has been archived only if all three filter lists indicate it should be included for checking. That is, an exclude at any level; job, program, or data set name, results in the check being skipped.
Find the JOBNAME PROCESSING LIST, PGMNAME PROCESSING LIST, and DSNAME PROCESSING LIST within PARMLIB member ARJES2XT, and supply appropriate patterns to be included and/or excluded. Each entry can specify an explicit (complete) name or a pattern name. Follow the instructions within the member itself.
For a series of jobs that must run in sequence, it is usually best to ensure that all of the jobs are either included or excluded, but not mixed. If only some of the jobs in the series are included, the order may be affected.
Observe the following points:
PARMLIB member ARJES2XT contains a fourth list too. It contains the names of the pseudo-volumes CA Disk recognizes for archived data sets. Normally you will not need to modify this list. However, if you run CA Disk version 9.0 or higher, but also use DFSMShsm to migrate some data sets, remove MIGRAT from the VOLSER PROCESSING list in this member. You can use a member name different from ARJES2XT if you want to. But if you do, you must provide system parameter ARJESMBR (mbrname) to identify it to CA Vantage. - Activate your new or changed filters in ARJES2XT.
When changes are necessary, update the member and issue the following operator command:
F SAMS,ARM,REFRESH - Jobs, Steps and Data Sets Automatically Excluded (information only).
The supplied JES2 EXIT6 code (programs KNGJX006 and KNGED009) automatically excludes certain jobs, job steps, and data sets from auto restore processing within the JES2 Exit. These automatic exclusions are described below.
Automatic Job Exclusions
The exit does not process a job if:
TYPRUN=SCAN is used on the JOB statement
TYPRUN=COPY is used on the JOB statement
A ddname of ARNOJ2X6 is found within the job JCL
Automatic Job Step Exclusions
The exit does not process a job step if:
COND=ONLY is used on the EXEC statement. (Such data sets are not needed unless a previous job step abends.)
IEFBR14 is being executed with the COND keyword.
Automatic Data Set Exclusions
The exit does not process a data set on a DD statement if: DISP=NEW is specified (Only data sets with dispositions of OLD, SHR, or MOD are processed.)
DDNAME=, DYNAM, or SYSIN is specified
DUMMY is the first parameter
DSN=NULLFILE
DSN=* (A refer back. The data set name will have been checked already.)
VOL=SER is specified (Uncataloged data sets are not checked.)
DISP=(,CATLG) or (,PASS) was specified in a previous DD statement. (The data set was cataloged or passed from a prior job step DD statement.)
Note: A data set referenced on a VOL=REF=dsname or DCB=dsname is not excluded from processing. These could reference archived data sets, so the catalog must be searched to determine whether they need to be restored. - Automatic Exclusions Due to Errors (information only)
The exit does not process any data set that is:
Referenced by JCL in which converter errors that fail the job (JCTCNVRC) have been detected.
Referenced by JCL in which other severe errors have already been detected by this JES2 exit.
Referenced by JCL before any restart step specified by the job statement.
Test the JES2 Exit
To test the installation of the CA Vantage JES2 Exit, start CA Vantage, and then submit a job that refers to an archived data set. Make sure that the job name, program name, and data set name are not excluded by the processing list. The following should take place:
The job is placed in hold status.
Either an existing DMSAR receives the restore request, or, if the maximum number of tasks is not already running, a new DMSAR is started.
After the data set has been restored, the job is released by CA Vantage.
Disable/Enable the JES2 Exit6 Interface
You can disable the JES2 Exit6 processing in two ways:
Disable the exit within JES2 itself
$T EXIT6,DISABLE
No-op its processing
Rename PARMLIB member ARJES2XT and restart CA Vantage.
If this member with your exclusion filters is not found, all processing within the exit is bypassed. (System parameter ARJESMBR provides the name of the member with your filters. It defaults to member ARJES2XT. If you use a different member, simply rename it, or change sysparm ARJESMBR to specify a non-existing member.)
To enable the exit again, reverse the process you used above:
Enable the exit within JES2 itself
$T EXIT6,ENABLE
Activate exit processing
Rename the member back to ARJES2XT and restart CA Vantage.
When the member is found, all processing within the exit will start.
S DMSAR,DMSAR=REMOVE
(if the CA Disk auto restore hook is already active)
S DMSAR,DMSAR=INSTALL
Auto Restore Command:
Deactivate/Activate ARM
To deactivate ARM for a short period of time, issue the command:
F SAMS,ARM,DRAIN
To reactivate it again (after being drained), issue:
F SAMS,ARM,START
To deactivate ARM permanently:
Specify system parameter SUARH (N)
F SAMS,STOP (to shut the system down)
S SAMS (to start it up again)
Suspend/Resume ARM
To suspend ARM processing of requests for a short period of time, and deallocate the FILES data sets, issue the command:
F SAMS,ARM,SUSPEND
To resume processing of queued/pending requests, issue:
F SAMS,ARM,RESUME
The SUSPEND command frees the FILES data sets such that CA Disk IXMAINT jobs can perform maintenance. When maintenance is finished, the RESUME command causes CA Vantage to reallocate the FILES and resume processing the restore requests.
SYSPARMS consideration:
The list of VKGPARMS entries involved to activate DMSAR/ARM processing correctly:
ARDSQTAP (N) - Stack all requests for the same tape together
ARDEDSRV (N) - Separate DASD & tape servers
ARDSKSRV (1) - Controls total number of DASD archive tasks
ARTAPSRV (1) - Controls total number of tape archive tasks
FILES1 (CADISK.FILES) - Specify the production Disk Files data set
MAXTASKS (1) - Maximum of all started tasks combined
SUBSYSN (XAD1) - Identify the Vantage task name to Disk
SUARH (Y) - Activate interface to Auto Restore Handler
SUDMS (Y) - Activate Auto Restore Manager (ARM)
Why it was involved:
ARDSEQTAP - This made DMSAR keep a tape for extended periods of time. At its worst point, every lpar was waiting for hours use one tape a single DMSAR wouldn't release. A corresponding Disk sysparm, DYNUKEEPN was set for the same reason.
ARDEDSRV - This makes both the ARDSKSRV & ARTAPSRV dedicated, resulting in both DSKSRV & TAPSRV settings to take full effect. Since we observed all DMSAR's calling for tape (caused by the FILES1 missing), reduction to a maximum of 1 DMSAR per restore type (2 total) was initially made. To reduce to a maximum of 1, this was switched to N and MAXTASKS (1) took effect.
FILES1 - When not specified, Vantage assumed archive files are stored on DASD. This caused ARDSKSRV to take effect and use tape when an archive was actually on tape. If ARTAPSERV started too, there are the two tapes in use at once.
SUBSYSN - Disk can only specify this name once, since each individual system was uniquely labeled, Disk couldn't 'talk to' ARM. A corresponding change to Disk parm 'SAMSYSNMSAMS' was made pointing to the Vantage default of SAMS.
ARDSKSRV & ARTAPSRV - When ARDEDSRV is Y, this total of these is the maximum number of DMSAR's that will run at the same time. By setting ARDEDSRV to Y, a maximum of 1 DASD based auto restore & 1 tape based auto restore will run at the same time. Switching ARDEDSRV to Y will maintain the '1 tape drive max per system' requirement and improve auto restore throughput by processing dasd based restores independent of the tape based restores.
MAXTASKS - When ARDEDSRV is N, this controls the maximum number of DMSAR's that will run at the same time regardless of whether they are dasd or tape based.
SUARH & SUDMS - Added in many VKGPARMS where they were missing. The default value (N) on either of these deactivates ARM and DMSAR runs independent of Vantage.
Environment
Component: VANT
Feedback
