Activating the IAM VSAM interface

if you are using IAM/RLS, it can automatically activate the IAMVSAM interface during initialization. This activation effectively loads the IAM VSAM interface modules into the Pageable Link Pack Area (PLPA) area of virtual storage. The IAM VSAM interface modules act as a front end to various VSAM services, such as Open and Close. If the data set being processed is an IAM data set, then the interface gives control to the appropriate IAM routines. If the data set is not an IAM data set then control is directed to the normal VSAM processing routine. Once a data set is opened, I/O requests are handled directly by the access method responsible for the data set, either IAM or VSAM. The IAM VSAM interface causes no interference or overhead with the processing of I/O requests to real VSAM files.

• IAM IS NOT A REPLACEMENT FOR VSAM IN YOUR SYSTEM.
• IAM DOES NOT AFFECT THE NORMAL USE OF VSAM IN THE SYSTEM.
• VSAM CATALOG MANAGEMENT IS NOT CHANGED.

Coexistence with other software products

There are wide varieties of other software products that also intercept the various services done for VSAM data sets. IAM can coexist in systems with these other software products installed. Depending on the function of the product and the various interfaces used, there may be a start order dependency between the different products to make sure that the expected processing by each product occurs as anticipated. In general, if a product provides services and capabilities not applicable to IAM data sets, then they should be activated before IAM. Products that can be used for IAM data sets should be started after IAM. For example, VSAM buffering and performance products should be started before IAM. Other products, such as VSAM recovery and journaling software or VSAM space management packages that can be used for IAM data sets should be started after IAM.

There are some software products which require a specific setting in the IAM Global Options Table. These are identified in Setting-the-IAM-Global-options of this space and are shown in the table below.

Please be advised to check with the technical support of other products that will be working with or using IAM files to check on any options or maintenance that may be required or recommended for use with IAM.

Should you have any concerns or questions about IAM coexistence with other software products, contact the IAM technical support department at BMC Support.

ACF2 security

Customers that are using the ACF product for security need to add the following definitions to their ACF parameters, to make sure proper security for IAM files:

SET C(GSO)

INSERT SAFDEF.IAM MODE(GLOBAL) ID(IAM) RB(SVC019) RACROUTE(REQUEST=AUTH class="DATASET" REQSTOR=IAMAVSOC) REP

Top secret

Users of Top Secret, and possibly other security software, will need to specify CREATE authority on any jobs, CICS, IAM/RLS, or IAM/PLEX address space that may to extend an IAM data set on to a new secondary volume.

Resource protection

IAM utilizes a major QNAME of IAMENQ to provide share option and other ENQ protection across multiple systems. Such ENQs are issued with the specification of SYSTEMS for scope. Some products that handle the ENQ/DEQ for resources may need to have their parameters specified to make sure that IAMENQ is recognized as being a valid name for sharing resources between multiple systems. This is known to be necessary for CA-MIM, and may be needed for other products as well. An example of what needs to be specified for CA-MIM is shown below:

Control information required for CA-MIM with IAM

Start order of IAM

The start order recommendations of various products, as they relate to IAM along with an indication of there being an IAM Global Option setting required, are shown in the table below. Care must also be taken to make sure that the various products are not starting at the same time because not all products follow the required locking protocol, and for some of the control block updates, there is no established serialization protocol. The order of the various start commands in the SYS1.PARMLIB member COMMNDxx is no guarantee of the order in which the product will actually perform it's initialization since the commands are executed concurrently.

VIF start order with other software products

The best way to make sure the proper start order is by the use of automated operations software. Such software can determine that a process is complete by such means as checking for a specific WTO message, before initiating another process. For IAM the message to check for is the IAMW81 THE IAM SYSTEM MODULES ARE ACTIVE.

Another alternative is to start a multiple step PROC, which includes the IAMSTART procedure at the appropriate place. This will work providing that the steps prior to the IAMSTART terminate after the product initialization, as IAMSTART does.

Activating IAM

The IAMSAMP contains seven (7) members to control the IAM VSAM Interface in your system. If you are running IAM RLS, you can let IAM RLS activate the IAM VSAM interface, instead of using the IAMSTART proc. For further detail regarding the VIFSTART= parameter specified in the IAM RLS PARMLIB, see IAM/RLS Parameters. The default value is NO which is a change from earlier versions of IAM where the IAM RLS address space automatically activated the VIF.

IAMSAMP members to control the IAM VSAM interface

VIFSTART Job

The VIFSTART job can be used to activate the IAM VSAM Interface. This job requires both a STEPLIB and a SYSLIB DD statement, which specify the APF authorized IAM load library. If you already have a version of IAM active, refer to the section on Concurrent IAM and Test IAM below before starting the new version. Before executing this job, if you have any of the software products that are to be started after the IAM that are currently active, shut them down temporarily before starting IAM. After starting IAM, those software products can be restarted.

Example of the VIFSTART job from the IAMSAMP

VIFSTATS job

The VIFSTATS job can be used to verify the status of the IAM VSAM Interface on your system. If you have multiple versions of IAM, always run the VIFSTATS with a STEPLIB to the most recent version. This is because older versions of IAM may not be able to properly display information on the newer versions. This job will provide WTO messages indicating the status of all levels of the IAM VSAM Interface on your system. The JOBLOG also includes messages indicating the names of the various modules IAM has placed in the PLPA, along with their entry point and level. If you have installed the IAM ISPF panels, this same information can be displayed on your terminal using the U.V options from the IAM primary panel.

Example of VIFSTATS job from the IAMSAMP

Deactivating IAM

The IAM VSAM Interface can be deactivated with the VIFSTOP job. This job will not remove the IAM VSAM Interface modules from the PLPA, but will deactivate them. Should you absolutely need to remove the IAM modules from PLPA without doing an IPL, contact BMC support for the procedure to follow.

NOTE: To reactivate IAM use the VIFSTART procedure.

WARNING: If you deactivate IAM in a production environment, all OPEN, CLOSE and IDCAMS processing against IAM files will fail.

VIFSTOP job

Example of VIFSTOP Job from the IAMSAMP

IAMSTART procedure

Also provided in the IAMSAMP is an example of a PROC that can be copied into a system PROCLIB, so that the IAM VSAM Interface can be automatically or manually started by the operator START command. This PROC is set up with one operand, LIB= that can be used to override the default STEPLIB and SYSLIB DD statements, which are required to be in the PROC. The STEPLIB can be removed if the PROC is only used to start the version of IAM that is in the system LINKLIST.

Example of IAMSTART procedure from the IAMSAMP

Activating IAM at IPL time

After you have completed your testing, or possibly before, you will want to start IAM automatically at each IPL. To have the IAM automatically activated with each IPL, use the following procedure:

1. In member IAMSTART of the IAMSAMP, change the library name specified in the ‘LIB=' statement to reflect your IAM load library.
2. Copy the member ‘IAMSTART' into SYS1.PROCLIB (or the procedure library used by your installation for system level user procs). This is the startup procedure for IAM.
3. Copy the member IAMCOMM from the IAMSAMP into the SYS1.PARMLIB member COMMND00 (or the COMMNDxx member used by your installation). This will create a record that will result in a system start command being issued for the IAM start up procedure at IPL time. The record in that member should look like the following statement:
   
   COM='START IAMSTART'

You have now completed the installation of a dynamic IAM system level VSAM interface that will automatically be activated each time the operating system is IPL'd.

Testing IAM Version 11.1.00 with prior versions of IAM active

If you are a current customer of IAM, you can install and test new versions of IAM without affecting any of your existing jobs. Programs can continue to use the prior versions until you choose to have them use the new version. Follow the appropriate testing procedure described below. Normally, your production version of IAM will be in a LINKLIST library. The new test version should be installed in a separate APF authorized library. If the library containing the new version is in the LINKLIST, it must be after the current version while testing is in progress.

One consideration with testing multiple levels of IAM is that the only version that can be used to define IAM data sets in JCL is the version of IAM that is in the LINKLIST. This is because the JOBLIB or STEPLIB specified in the JCL for the job to be executed is not used by the system initiator when it is performing allocation of the data set.

Running multiple IAM

If you are installing a new version of IAM, such as Version 10.01 while Version 9.4 (or earlier version) is your production IAM, you can run multiple levels of IAM for your testing. The major rule to be followed is that the oldest version of IAM must be started first. There are two different ways to run multiple levels of IAM. The first way is called Concurrent IAM, and is generally used when testing new versions of the product. The second way is called Test IAM, and is normally used when testing different maintenance levels of the same version of IAM. When running multiple versions of IAM, the primary production version matches the version of IAM that is in the system LINKLIST. The other versions are accessed through a JOBLIB or STEPLIB pointing to the alternate IAM load library.

Concurrent IAM

Concurrent IAM works by comparing the loaded IAM module level with the level of the IAM VSAM interface using an internal level identifier for the IAM VSAM interface. When a VSAM function is intercepted by IAM, such as DEFINE, LISTCAT, OPEN, or CLOSE, IAM will load the appropriate IAM routine to process the request. If the internal level in the loaded IAM routine matches the IAM currently processing the request, then processing will proceed. If the internal level is not the same, then the current IAM percolates control to the prior level of IAM. If no match is found, VSAM will attempt to process the file, which will most likely result in a failure.

The Concurrent IAM VSAM can be started using the VIFSTART job or the IAMSTART PROC pointing to the new IAM load library. The one restriction is that the oldest version of IAM must be started first, and the newest version started last. Control over which version of IAM will be used is then based on the JOBLIB or STEPLIB being used by the job step. With Concurrent IAM, there is no concern about the job names, as there is with the Test IAM procedure. IAM V10.01 and above can be concurrently run with any prior levels of IAM. Please note that running IAM Version 10.01 with IAM Version 8.1 will cause the support for IAM files to use the XTIOT, Uncaptured UCBs, and DSAB above the line to be inactive.

Test IAM

IAM provides the capability to have a TEST version of the IAM VSAM Interface active. The TEST version can be used to test new versions and new maintenance levels of IAM, while having prior versions or maintenance levels of the IAM active. The TEST IAM interface utilizes a jobname screening mechanism to determine eligibility for using the TEST version. When activating a TEST version of IAM, a PARM of TEST is specified, followed by JOBNAME=jobname. The jobname must match the specified value to utilize the TEST version. The jobs that are utilizing the TEST version of IAM must have a JOBLIB OR STEPLIB to the new IAM load library. A jobname prefix mask can be specified, by coding the prefix followed by an *. For example, specifying JOBNAME=myid*, all jobs that begin with the literal "myid" will be qualified for the test version. Up to five different jobnames or jobname groups can be specified. Multiple job names are specified by enclosing the names within parenthesis. The jobnames can be easily modified by rerunning the startup of the TEST version with a different values for the JOBNAME parameter. Specifying JOBNAME=* will make all jobs eligible for the TEST version.

VIFTEST job

In the IAMSAMP, there is an example job stream to start a TEST version of IAM, as member VIFTEST. The VIFTEST JCL is as follows:

Example of starting a test VIF

As stated above, to change the name of the jobs eligible for the TEST IAM version, simply rerun the above job with a new value specified for JOBNAME=.

Deactivating test IAM

To deactivate the TEST IAM version, use the following JCL:

Example of JCL to stop a test VIF

Test IAM considerations

There are a few considerations when using a TEST IAM. The TEST IAM capability merely screens which jobs are eligible for being processed by the new IAM. To be a valid test, the job must have access to the new IAM load modules via JOBLIB or a STEPLIB. The TEST IAM does not have the capability to dynamically select or force the library from which the IAM modules are loaded. This can cause failures or unexpected results if this capability is not appropriately used.

If the other versions of IAM that are active have different internal level values, then the TEST IAM behaves like a Concurrent IAM, with the exception that only those jobs whose name matches the specified JOBNAME value will be considered for the TEST IAM. For example, if a job has a JOBLIB or STEPLIB with the new IAM load library, but does not have a jobname match, it will end up processing with the real VSAM code, which will most likely cause an IEC161I error message. However, if there is a jobname match but the IAM modules that are accessed by that job are from the prior version, then the prior version of IAM will be used.

When using a TEST IAM to test a new maintenance level, where the internal level values are the same, the TEST IAM controls which version of the IAM will handle the job. For jobs whose name matches the specified value, they will be handled by the new IAM. Jobs whose names do not match the specified value will be processed by the other (production) IAM. It is the users responsibility to make sure that the correct version of the IAM libraries are used by the TEST and non-TEST jobs. This is easily controlled if the production version is in the system LINKLIST, and the TEST version is accessed by JOBLIB or STEPLIB. If the test job name matches the job name specified for the TEST IAM, and the job has a JOBLIB or STEPLIB for the new library, it will be processed entirely by the new version. If a job name does match the TEST VIF parameter, but the job does not have the test JOBLIB or STEPLIB, it will then execute using the new VIF modules, but the old processing modules. If a job name does not match the TEST IAM parameter, but has the new JOBLIB or STEPLIB, it will execute using the old IAM VSAM Interface modules and the new processing modules. Either one of these sequences may cause an invalid test, or even fail to properly execute.

Activating multiple IAM during IPL

When testing a new version or maintenance level of IAM, it will generally be desirable to have the multiple levels of IAM started during IPL. This can be most easily accomplished by modifying the IAMSTART PROC to have multiple steps, each one starting a different version of IAM. Remember that the older versions of IAM must be started before the newer versions. Below is an example of the IAMSTART PROC modified to start up two concurrent versions of the IAM.

Starting multiple IAM versions during IPL

Activating multiple IAM versions with a test IAM

You can also start up multiple levels of IAM including one as a test IAM. Below is an example of a PROC to do that. Remember that if you need to change the value of the JOBNAME all you need to do is to rerun the test IAM start with different jobnames specified.

Example of procedure to start multiple IAM versions with one as a test IAM

Where to go from here

See Testing-IAM.