IAM/PLEX Parameters
There are three sources of parameters for controlling IAM/PLEX usage. These include the IAM/PLEX start up parameters, specified by a parmlib mechanism on the IPARMLIB DD statement, the IAM Overrides, and the IAM Global Options Table. The IAM/PLEX parmlib parameters are completely discussed in this. There is also a discussion of relevantIAM Overrides with IAM/PLEX in this, the full IAM Override documentation is provided in IAM-Overrides of this space. The main global option affecting IAM/PLEX has to do with the specification of automatic eligibility for IAM/PLEX processing, which is discussed in IAM-PLEX-Automatic-Data-Set-Eligibility.
IAM/PLEX PARMLIB
The parameters that can be specified for the IAM/PLEX address space are presented below. These parameters are passed to IAM/PLEX via a parmlib mechanism, which is specified via the IPARMLIB DD statement. If you use the example IAM/PLEX procedure, then the IAM/PLEX parmlib member is specified using the MBR= operand. Each IAM/PLEX instance must have its own parmlib member to specify a unique RLSID and the RLSGROUP that the IAM/PLEX instance belongs to.
The parmlib is read to establish the parameter settings during IAM/PLEX initialization. Additionally, users can issue the “CHANGEPARM” command, which will cause an active IAM/PLEX address space to re-read the parmlib member, and cause an immediate update for many of the values. Any special considerations with changing the various parameter values will be discussed in the description of the individual parameters below.
The parmlib data set must be an 80-column card image data set, with parameters and values coded in columns 1 through 71. Each card image can contain a single parameter with its values. Multiple parameters can be specified on a single card, but must be separated by a comma and no spaces.
Comment cards can be included, and are indicated by an “*” in the first column of the card. Examples of parmlib are provided in the ICL (Installation Control Library). Customers may use the ICL for the parmlib data set, if so desired.
IAM/PLEX Parameters
Parameter | Description |
|---|---|
CICSJOURNAL= | Specifies whether IAM should journal the before images for updates performed by CICS transactions. Valid values are YES or NO. The default value is NO, because CICS normally handles transaction backout and before image journaling itself. If the Record Lock Recovery is being used, then it will automatically default to YES. |
CICSLOCK= | Specifies the action that IAM/PLEX will take when record lock contention is encountered for a CICS transaction. Three sub-parameters can be provided. The first instructs IAM/PLEX what action to take when the owner of the lock is another CICS transaction. The second instructs IAM/PLEX what action to take when the owner of the lock is other than a CICS transaction, such as a batch job or TSO user. The third tells IAM/PLEX that if it is going to fail the request due to lock contention, it is just to pass a logical error code back to the caller, or abend the transaction. One of the following keywords can be provided to indicate what action IAM/PLEX will take when the owner of the record lock is a CICS transaction: CICSWAIT specifies that the requestor of the lock will wait until the record lock is available when the owner is a CICS transaction. CICSTIMEOUT specifies that the requestor of the lock will wait for a short time as specified by the CICSTIMEOUT parameter (see below), if the owner of the lock is a CICS transaction. If the lock is still not available, then the request will fail. CICSNOWAIT specifies that the request for the record lock will fail if the owner is a CICS transaction. One of the following keywords can be provided to indicate what action IAM/PLEX will take when the owner of the record lock is other than a CICS transaction, such as a batch job or TSO user: WAIT specifies that the requestor of the lock will wait until the record lock is available when the owner is not a CICS transaction. TIMEOUT specifies that the requestor of the lock will wait for a short time as specified by the CICSTIMEOUT parameter (see below). If the lock is still not available, then the request will fail. NOWAIT specifies that the request for the record lock will immediately fail when the owner is not a CICS transaction. One of the following keywords can be provided to indicate whether IAM should fail the CICS transaction with an ABEND, or just fail the request following standard VSAM protocol with a logical error code: ABEND specifies that IAM will abend the CICS transaction. This requires the installation and activation of an IAM provided CICS Global User Exit, as described later. The transaction will abend with a code of AKC3. NOABEND specifies that IAM will fail the request with a logical error code. The default values are: CICSLOCK=(CICSWAIT,TIMEOUT,NOABEND) |
CICSTIMEOUT= | Specifies the maximum time, in seconds that a CICS transaction will wait for a record lock if CICSTIMEOUT or TIMEOUT has been specified for the CICSLOCK parameter. Default is 30 seconds, maximum is 9999. |
DJB= | This parameter provides a way to control Dynamic Job Backout. The following values are accepted: YES – Specifies that Dynamic Job Backout will be automatically invoked for any job steps that abend, and have recoverable IAM files accessed through IAM/PLEX. Changes made to recoverable IAM files for the abending job step will be removed from the affected files, back to either the most recent batch syncpoint taken by the job step, or if no syncpoints were taken, then to the beginning of the job step. NO – Specifies that Dynamic Job Backout will not be automatically invoked, unless the failing job step has opened a recoverable IAM file through IAM/PLEX with the DJB=YES IAM override. DISABLED – Dynamic Job Backout support is disabled, and will not be invoked even with a DJB=YES IAM override. The default value is NO. |
JRNBUFF= | Optional parameter that specifies the number of buffers that IAM/PLEX will use for journaling. Valid values are from 2 to 255. Low activity systems can use fewer buffers, while more active systems will benefit from additional buffers. The default value is 32. |
LOCK= | Specifies the action that IAM/PLEX will take when record lock contention is encountered for a requestor other than a CICS transaction, such as a batch job or TSO user. Three sub-parameters can be provided. The first instructs IAM/PLEX what action to take when the owner of the lock is a CICS transaction. The second instructs IAM/PLEX what action to take when the owner of the lock is other than a CICS transaction, such as a batch job or TSO user. The third tells IAM/PLEX that if it is going to fail the request due to lock contention is it to pass a logical error code back to the caller, or abend the job or TSO user. One of the following keywords can be provided to indicate what action IAM/PLEX will take when the owner of the record lock is a CICS transaction: CICSWAIT specifies that the requestor of the lock will wait until the record lock is available when the owner is a CICS transaction. CICSTIMEOUT specifies that the requestor of the lock will wait for a short time as specified by the LOCKTIMEOUT parameter (see below), if the owner of the lock is a CICS transaction. If the lock is still not available, then the request will fail. CICSNOWAIT specifies that the request for the record lock will fail if the owner is a CICS transaction. One of the following keywords can be provided to indicate what action IAM/PLEX will take when the owner of the record lock is other than a CICS transaction, such as a batch job or TSO user: WAIT specifies that the requestor of the lock will wait until the record lock is available when the owner is not a CICS transaction. TIMEOUT specifies that the requestor of the lock will wait for a short time as specified by the LOCKTIMEOUT parameter (see below). If the lock is still not available, then the request will fail. NOWAIT specifies that the request for the record lock will immediately fail when the owner is not a CICS transaction. One of the following keywords can be provided to indicate whether IAM should fail the requestor with an ABEND, or just fail the request following standard VSAM protocol with a logical error code: ABEND specifies that IAM will abend the batch job or TSO user. The abend code will be a U0185. NOABEND specifies that IAM will fail the request with a logical error code. The default values are: LOCK=(CICSWAIT,TIMEOUT,NOABEND) |
LOCKCHKPT= | Specifies the number of minutes between checkpoints on the lock recovery data set. Valid values are 1 to 60. Refer to IAM-PLEX-Record-Lock-Recoveryfor information on this parameter. The default value is 5 minutes. |
LOCKMEM= | 64BIT specifies that 64 bit storage will be used for the record lock table. If used a MEMLIMIT value may need to be specified on the EXEC statement in the IAM/PLEX proc at startup. If no 64-bit storage is available, then IAM/PLEX will default to using 31 bit storage for the record lock table. 31BIT specifies that 31 bit storage will be used for the record lock table and is the default if no LOCKMEM parameter is provided or if no 64-bit addressable storage is available. |
LOCKSTART= | Specifies the type of start to be done for the Lock Recovery Process. Valid values are: COLD will result in no attempt to restore the record locks and force the reformatting of the lock recovery data set. WARM will result in restoring the record lock environment for recoverable files to what it had been at the time when the IAM/PLEX region became unavailable. The default value is WARM. |
LOCKTIMEOUT= | Specifies the time, in seconds, that a batch job or TSO user will wait for a record lock to become available if the CICSTIMEOUT and / or TIMEOUT value have been specified for the LOCK= parameter. The default value is 30 seconds, maximum is 9999. |
LOGSTRM= | Specifies the name of the IAM log stream to be used for journaling, when the System Logger is going to be used. This value must match the log stream name defined by IXCMIAPU. This value is only used if the SYSLOGGER=YES parameter has been specified. In single system mode the default value, if not specified, is IAMLOGR.sysname, where sysname is the value provided at IPL time in the IEASYSxx member for SYSNAME. In SYSPLEX mode the default value is IAMLOGR.groupname, where groupname is the 8 character RLSGROUP name provided in the parmlib member when the IAM/PLEX address space starts. Using the System Logger is mandatory when using journaling with IAM/PLEX. |
MAXBUFNO= | Specifies a value to be used as the default MAXBUFNO for IAM files opened under IAM/PLEX. If not specified, the default will be the normal IAM default from the IAM Global Options Table. Valid values are from 1 to 2048. This value may be overridden for specific files by an IAMACCESS override cards that have been included with IAM/PLEX. If this value is changed when the parameters are re-read by the CHANGEPARM command, it will take effect for data sets opened subsequent to the change. Currently opened data sets will not have their MAXBUFNO value changed. |
MAXIOTASK= | Specifies the maximum number of file I/O tasks to be permitted. This represents the maximum number of concurrent I/O requests that the IAM/PLEX address space will be able to be actively processing at any point in time. Additional I/O requests will be delayed pending the availability of an I/O task to process it. Values from 8 to 255 can be specified. Default value is 64. |
MAXJOBS= | Specifies the maximum number of jobs that can have IAM files opened under the IAM/PLEX address space. This is primarily used for setting up the record locking tables. Specifying too small a value may cause increased overhead for the IAM lock manager if the actual number of jobs exceeds this limit. Values from 1 to 9999999 can be specified. Default value is 1024. Changing this value will only take effect when IAM/PLEX is restarted. |
MAXLOCKS= | Specifies the approximate maximum number of record locks that are anticipated to be needed at any particular point in time. This value will be used to determine the size of the lock lookup hash table. Batch jobs will not be able to exceed holding this number of locks concurrently. Specifying too small a value may cause increased overhead for the IAM lock manager. Values from 1 to 67108859 can be specified. When using LOCKMEM=31BIT, the default value is 133103 and should not be made larger than 2129903. When LOCKMEM=64BIT, the default is 2129903. Changing this value will only take effect when IAM/PLEX is restarted. |
MAXTRANS= | Specifies the approximate maximum number of concurrently active transactions that a CICS system can have. Too small a value may cause increased overhead for theIAM lock manager. Values from 1 to 9999999 can be specified. The default value is 512. Changing this value through the CHANGEPARM command will take effect for CICS regions that are started subsequent to the change. |
MESSAGES= | Specifies what messages should be printed to the IAM/PLEX RLSLOGDD file. Valid values are ALL, INFO, or ERROR. ALL is primarily intended for problem diagnosis, as various messages will be written indicating many frequent events. INFO will provide a detailed activity log, including when data sets are opened and closed. ERROR will limit the RLSLOGDD messages to only those issued in error situations. This value can be dynamically changed via operator command. Default value is INFO. |
MINBUFNO= | Specifies a default minimum number of buffers per IAM file. Valid values are from 1 to 2048. The default value is 1, unless otherwise overridden by an IAMOVRID specification. If this value is changed when the parameters are reread by the CHANGEPARM command, it will take effect for data sets opened subsequent to the change. Currently opened data sets will not have their MINBUFNO value changed. |
MINIOTASK= | Specifies the minimum, and also starting, number of tasks in the IAM/PLEX address space that will be used to process I/O requests. Values from 1 to 255 can be specified. Default value is 4, which is recommended with the changes that were made to the IAM/PLEX I/O task dispatching. |
REMOTERLS | Specifies that this IAM/PLEX instance is a TARGET region only and cannot be connected for routing open/close or I/O requests to other members of an RLSGROUP in the SYSPLEX. |
RLSID= | Specifies the four character identifier for this IAM/PLEX instance. Each IAM/PLEX instance in a SYSPLEX will need to have its own unique identifier. If not specified, the value from the IAM Global Options Table will be used. |
RLSGROUP= | Specifies the 8 character identifier for the RLSGROUP the IAM/PLEX instance is to connect. If not specified then IAM/PLEX will run in a single system or non SYSPLEX mode, equivalent to an IAM/RLS instance. |
STATS= | When specified as ON, RLSINFO reports are generated automatically every 30 minutes if any statistics have changed during that period. You can always generate the report manually via the operator command. The RLSINFO DD statement must also be present in the IAM/RLS procedure to start the IAM/PLEX address space. The default value is OFF. |
SYSLOGGER= | Specifies either YES or NO, to indicate whether the z/OS System Logger is to be used instead of the sequential data sets. This option is required when the RLSGROUP parameter is provided and journaling is desired in the SYSPLEX environment. Refer to the IAM-PLEX-Journaling on journaling for more information on using this capability. If YES is specified, you can also specify the LOGSTRM= parameter, indicating the name of the log stream. If no LOGSTRM is specified the log stream name will default to IAMLOGR.systemname in single system mode or to IAMLOGR.rlsgroupname in SYSPLEX mode. When specified as YES, all of the LOGDSNx parameters are ignored. The default value is NO. |
SYSOUT= | Optional parameter specifying the SYSOUT class to be used for printed output directed to the RLSLOGDD. This parameter is ignored if an RLSLOGDD DD card is in the IAM/PLEX started proc. If an RLSLOGDD DD card is not included in the IAM/PLEX proc, then the SYSOUT class specified by this parameter will be used. If no value is specified, then the default SYSOUT class (equivalent to SYSOUT=*) for the started task will be used. Users can spin off the RLSLOGDD SYSOUT with the IAM/PLEX LOGSWITCH command. |
VIFSTART= | Specifies either YES or NO. Specify YES to have IAMPLEX on this LPAR start the IAM VSAM Interface (VIF) the first IAMPLEX startup after system IPL. This allows you to not need a separate IAMSTART procedure to start the IAM VIF. The default value is NO, to not have IAMPLEX start the IAM VIF and that you will run IAMSTART as a separate Started Task earlier in the IPL sequence. |
Examples of IAM PARMLIB Parameters
Example of parmlib input for IAM/PLEX address space is shown below:
Example of IAM/PLEX Parmlib Parameters. Member PLXPRM1 in ICL
MESSAGES=INFO
CICSLOCK=(CICSTIMEOUT,TIMEOUT,NOABEND)
LOCK=(CICSWAIT,TIMEOUT,ABEND)
CICSTIMEOUT=10
LOCKTIMEOUT=90
SYSLOGGER=YES
SYSOUT=X
JRNBUFF=128
RLSID=RLS1 Set RLSID of RLS1 for this IAM/PLEX
RLSGROUP=RLSGRP01 Connect to RLSGROUP: RLSGRP01
LOCKCHKPT=5 Record lock recovery checkpoint 5 minutes
LOCKSTART=WARM Perform lock recovery on startup
LOCKMEM=64BIT Use 64-bit storage for record locks
STATS=ON
Abending CICS Transactions
If ABEND was specified for the CICSLOCK parameter, then to cause the abends to occur, the IAM provided CICS Global User Exit (GLUE) must be activated. This IAM provided Global User Exit (GLUE) will purge transactions that receive an indication from IAM/PLEX to do so. This indication will only be presented when the action specified for the IAM/PLEX CICSLOCK parameter is set to ABEND. The transaction will abend with a code of AKC3. For information on setting this up, refer to IAM-PLEX-CICS-Considerations, CICS Considerations.
IAM Overrides
IAM ACCESS Overrides can be specified for the IAM/PLEX instance. The overrides can be a member of a card image PDS, such as the IAMICL. Some of the IAM ACCESS overrides that may be useful to IAM/PLEX are BUFSPACE, CONSISTENT, JRNAD, MINBUFNO, MAXBUFNO and REREAD. The IAMCREATE overrides are not relevant to IAM/PLEX because no file creations will take place under the IAM/PLEX instance.
The BUFSPACE, MINBUFNO or MAXBUFNO can be used on a data set by data set basis, to either use more or less buffering than what is being defaulted to under IAM/PLEX. The need to alter the buffering values should be minimal. This is because IAM/PLEX offers a MAXBUFNO value to be specified as a default for all files opened under IAM/PLEX as a start up parameter that was previously described.
The JRNAD override can be used to enable journaling for all IAM files accessed under IAM/PLEX, by providing an ACCESS DD=&ALLDD, JRNAD=BOTH. Be sure to specify JRNAD on any additional ACCESS override cards provided for specific data sets, as they will not pick up the value from the &ALLDD override. Using the override may be the preferred way to control journaling for IAM/PLEX, rather than on an individual file basis. The journaling can be turned off for specific data sets by an additional ACCESS override indicating the data set name.
If you are using the IAM overrides with IAM/PLEX, then you will most likely want to specify the REREAD keyword on each of the override cards. Specification of REREAD will cause IAMto read the IAM overrides every time an IAM file is opened, rather than only for the first data set opened, and saving the results in storage. While this is additional overhead, it will allow you to change the overrides without having to stop and restart IAM/PLEX for the new overrides to take effect.
Shown below is an example of overrides for an IAM/PLEX instance:
Example of IAM/PLEX Override Parameters. Member PLXOVRID in ICL
ACCESS DD=RLOKJRNL,INDEXSPACE=64BIT,NORLS,JRNAD=NONE,REREAD