6.1 APPC protected conversations

< Day Day Up >

APPC/MVS and Resource Recovery Services/MVS (RRS/MVS) introduce a new capability by providing system resource recovery services for APPC/MVS conversations. Some knowledge of resource recovery and its role is recommended to fully appreciate the value of APPC/MVS protected conversations. APPC/MVS protected conversations implements a communication resource manager on the z/OS platform and therefore enables z/OS to be a host for APPC conversations using the two-phase commit protocols.

From a cooperative application program's point of view, APPC/MVS protected conversations provide the capability for a cooperative application to have the updates in the cooperative applications coordinated. For example, each transaction program (TP) in the cooperative application can interact with database services and then request a coordinated commit or backout of resources that have been changed since the last point of consistency. RRS/MVS provides the ability for a cooperative application to invoke the commit and backout callable services. The role of APPC/MVS protected conversations in the two-phase commit protocol used to coordinate the update of local and remote resources, is to communicate the progress of the two-phase commit process to the distributed resource managers.

6.1.1 Functional description

You request APPC/MVS protected conversations through a VTAM® APPL definition statement for the APPC LU. The SYNCLVL keyword SYNCPT value must be specified for protected conversations. When you enable an APPC protected conversation, you must also define to System Logger a log stream for APPC/MVS use. APPC/MVS writes the results of a log name exchange with a partner LU into this log stream.

In fact, to provide resource recovery for protected conversations, APPC/MVS needs to know the names of local and partner LU log streams, and the negotiated syncpoint capabilities for each local/partner LU pair. This information needs to be available and accurate for successful resynchronization after a failure. To store this information, APPC/MVS uses a log stream.

APPC/MVS does not store conversation-specific information in the log stream. The log stream is used to store data related to unique partner LUs that have protected conversations with APPC/MVS. The log stream contains names of local and partner LU logs, and the negotiated syncpoint capabilities for each local/partner LU pair.

For each protected conversation, information is stored in RRS log streams during the two-phase commit process, but not in APPC/MVS log streams.

APPC/MVS can use both CF-Structure and DASD-only log streams. If you have workload using APPC/MVS protected conversation on multiple images within a sysplex, or if you plan to restart a workload using protected conversations on a different image, then you need to plan for a shared log stream using the CF as the interim media. If you are planning to use APPC/MVS from only one system, only one APPC/MVS will connect to the log stream, in which case you can use a DASD-only log stream if you wish. In this case, only APPC/MVS from this one system processes protected conversations. Other systems in a Parallel Sysplex can use APPC/MVS but they will fail to process any protected conversations since they will not be capable to connect to the log stream and will issue message ATB203I to document the return and reason codes received from the system logger IXGCONN service.

The APPC/MVS log stream is an active log stream and on an interval basis, APPC/MVS trims unneeded data from the log stream. There is no need to manage this log stream data using the System Logger parameters RETPD or AUTODELETE, or through any utility. It is recommended that this log stream is defined with no RETPD and AUTODELETE keyword to avoid the deletion of data still in use by APPC/MVS.

There is one IXGWRITE in the log stream for each unique partner LU that uses protected conversations. So, for example, if you have 50 partner LUs, of which 25 have established protected conversations, you would have at least 25 IXGWRITESs. As you can see, there is not very frequent activity on this log stream. When an LUDEL is performed, the element is removed from the APPC log stream. When this is done, APPC invokes the purge log name affinity processing, which communicates with all partner LUs that have established protected conversations with this LU in the past. If the partner LU gives the OK to purge the affinities, then APPC deletes an entry in the log stream corresponding to that protected partner LU and its corresponding local LU. So, depending on the number of protected partner LUs and the size of the structure, this will determine where the data resides (CF or on DASD).

Criticality/persistence of data

APPC/MVS keeps information about the conversation partners and their syncpoint in the log stream in order to be able to rebuild the conversation in case of a failure.

For this reason, APPC/MVS data is critical to the installation, and recovery from a loss of the data can be a complex process. To avoid a potential loss of data, we recommend that you use unconditional duplexing with this log stream. Duplexing the log stream should not cause a performance impact to the application since APPC/MVS doesn't update the log stream very frequently.

Losing data in the APPC/MVS log stream means that APPC/MVS loses all knowledge of all partners' log information and syncpoint capabilities. Refer to 6.1.4, "Recovery" on page 205 for more information on the impact of losing the APPC/MVS log stream data and the steps that need to be followed to restart the application.

Log stream sizing

To size the interim media for the APPC/MVS log stream, you can use the following formula:

For each local LU that supports SYNCLVL=SYNCPT, calculate the maximum anticipated number of partner LUs that will communicate using protected conversations.
After identifying the number of partners for each local LU, add all the values together.
Multiple the resulting number by 300 bytes.

This is the minimum storage that should be allocated for the interim media for the APPC/MVS log stream. Refer to Example 6-1 for an example calculation.

Example 6-1: APPC/MVS storage calculation sample

 There are 8 local LUs on system #@$1, 3 of which are defined with SYNCLVL=SYNCPT    (defined in VTAMLST)    - SYNPTLU1 communicates with up to 15000 partner LUs, but only 20% of those parterns    communicate using protected conversations.    - SYNPTLU2 communicates with up to 5000 partner LUs and all of them could use protected    conversations.    - SYNPTLU3 communicates with 2000 partner LUs, of which about 50% use protected    conversations. Based on the above information, the minimum size for the interim storage for the APPC/MVS log stream is: (3000+5000+1000) x 300 bytes = 2,700,000 bytes.

6.1.2 Definition

Subsystem definitions

There are no definitions to be done within APPC/MVS. If any protected conversations are started, APPC connects to a fixed name log stream: ATBAPPC.LU.LOGNAMES.

APPC/MVS log stream structure definition in the CFRM Policy

If your installation decided to use coupling facility log streams for APPC/MVS, you need to make sure that the corresponding CF structure is defined in the CFRM policy and that the CFRM policy is activated in the sysplex through the SETXCF command. Example 6-2 contains a sample to define the CF structures for the APPC/MVS log stream. You should set SIZE to be roughly twice the size you determined in "Log stream sizing" on page 201.

Example 6-2: Sample of structure definition for APPC/MVS log stream

 //APPCSTR JOB CLASS=A,MSGCLASS=A //POLICY EXEC PGM=IXCMIAPU //SYSPRINT DD SYSOUT=A //SYSIN DD *    DATA TYPE(CFRM)    STRUCTURE NAME(APPC_LOG)       SIZE(8192)       INITSIZE(4096)       PREFLIST(FACIL01,FACIL02)

This step is not required as you are using DASD-only log stream.

Logger definitions

Even though you can use DASD-only log streams, most installations configure the APPC/MVS log stream as a CF-Structure log stream. For this reason, the following samples use a CF-Structure configuration. Refer to "APPC/MVS log stream structure definition in the CFRM Policy" on page 202 for more information on the CFRM parameters for the APPC/MVS log stream structure.

Example 6-3: APPC/MVS log stream definitions

 //DEFINE EXEC PGM=IXCMIAPU //SYSPRINT DD SYSOUT=A //SYSIN DD *    DATA TYPE (LOGR)    DEFINE STRUCTURE NAME(APPC_LOG)       LOGSNUM(1)       MAXBUFSIZE(65276)       AVGBUFSIZE(248)    DEFINE LOGSTREAM NAME(ATBAPPC.LU.LOGNAMES)       STRUCTNAME(APPC_LOG)       HIGHOFFLOAD(80)       LOWOFFLOAD(40)       DUPLEXMODE(UNCOND)       STG_DUPLEX(YES)       LS_DATACLAS(LOGR24K)       STG_DATACLAS(LOGR4K)       LS_SIZE(1024)       HLQ(IXGLOGR)       RETPD(0)       AUTODELETE(NO)

LOGSNUM: The LOGSNUM parameter controls the maximum number of log streams that may be allocated in the associated structure. We recommend specifying a LOGSNUM of 1, meaning that only one log stream will be placed in the structure.

MAXBUFSIZE: APPC/MVS requires a buffer size of 65276 bytes. If you use a MAXBUFSIZE value that is less than 65276, APPC/MVS issues message ATB209I and does not allow APPC/MVS LUs to handle any protected conversations until the buffer size is corrected and the LUs restarted.

AVGBUFSIZE: The APPC/MVS log stream contains one log block for each of the following:

Each local/partner LU pair that has established a protected conversation.
Each LU pair, if any, that has outstanding resynchronization work.

All log blocks are the same size: 248 bytes. Use 248 as the value for the average size of APPC/MVS log blocks.

HIGHOFFLOAD: The HIGHOFFLOAD value specifies how full the log stream interim storage should get before an offload process is initiated. We recommend using value not higher than 80%.

LOWOFFLOAD: The LOWOFFLOAD value defines the amount of data that is to be retained in the log stream interim storage following an offload process. In the APPC/MVS environment, the LOWOFFLOAD value should be between 40 to 60%.

STG_DUPLEX(YES) and DUPLEXMODE(UNCOND): If you suffer a loss of data in the APPC/MVS log stream, manual intervention is required to resolve the situation. To avoid this, we recommend defining the APPC/MVS log stream with STG_DUPLEX(YES) and DUPLEXMODE(UNCOND). Because APPC/MVS writes infrequently to its log, the performance impact should be minimal.

STG_DATACLAS: Make sure you use an SMS data class that has share options of 3,3. Using share options other than this can result in failures when System Logger tries to use the staging data set.

You must use a data class that specifies a CI Size of 4 K.

LS_DATACLAS: Make sure you use an SMS data class that has share options of 3,3. Using share options other than this can result in failures when System Logger tries to use the offload data set.

For optimal performance for the offload data sets, we recommend using a data class that specifies a CI Size of 24 K.

STG_SIZE: The STG_SIZE specifies the size, in 4K blocks, of the staging data sets for the log stream. You can omit this parameter and system logger will allocate a staging data set that will be equivalent to the coupling facility storage. In this case the staging data set is always in sync with the size of the coupling facility structure. Remember that having a staging data set smaller than the coupling facility structure might cause an offload even though the structure storage has not been totally used because the data set gets filled up earlier than the coupling facility storage.

LS_SIZE: The LS_SIZE specifies the size, in 4K blocks, of the offload data sets for the log stream. You can use an initial value of 1024 and then update depending on their usage.

Attention:

Be sure you either specify an LS_SIZE value on the log stream definition or you use an LS_DATACLAS where you have space allocation defined. If LS_SIZE is not specified in the log stream definition, and an extent size is not specified in the data class pointed to by LS_DATACLAS, the value is taken from the ALLOCxx Parmlib member or set via an ACS (Automatic Class Selection) routine. The default value in ALLOCxx is 2 tracks. Refer to the z/OS MVS Initialization and Tuning Reference, SA22-7592.

Both methods are valid, it depends on your installation and on the variety of the log streams. If you do not have a big variety of offload data set, you can use SMS dataclas to manage the allocation space and simply omit the LS_SIZE parameter. If your installation has multiple different type of offload data set that will generate too many SMS Dataclas, than you might want to consider to use LS_SIZE on each log stream.

.HLQ: The HLQ specifies the high level qualifier for both the offload data sets and the staging data sets. If you do not specify a HLQ value, a default HLQ of IXGLOGR is used.

AUTODELETE and RETPD: It is very important that AUTODELETE(NO) and RETPD(0) are specified (or use the AUTODELETE and RETPD parameter defaults which are NO and 0, respectively) for the ATBAPPC.LU.LOGNAMES log stream. Using values other than these could result in data being deleted before APPC/MVS is finished with it, or in data being kept for far longer than necessary.:

Security definitions

The APPC/MVS log stream can be protected in the Security Access Facility (SAF) LOGSTRM class. The userid associated with the APPC/MVS address space must have UPDATE access to the log stream. The RACF statements to define the profile and grant access to it are shown in Example 6-4.

Example 6-4: Sample log stream security definitions

 RDEFINE LOGSTRM ATBAPPC.LU.LOGNAMES UACC(READ) PERMIT ATBAPPC.LU.LOGNAMES CLASS(LOGSTRM) ID(APPC/MVS_userid) ACCESS(UPDATE) SETROPTS CLASSACT(LOGSTRM)

The log stream name defined to RACF is the name specified on the NAME parameter of the DEFINE LOGSTREAM statement in the LOGR policy

6.1.3 Operational considerations

The following is a consideration when operating in the APPC/MVS environment:

Enq/Deq with OEM product

Verify that the PTF for APAR OA01793 is applied if you are using an OEM serialization product. In installations with OEM serialization products, where the qname list was not set up properly, the Global ENQ request made by APPC/MVS is treated as a Local ENQ, resulting in both APPC/MVSs making update request to System Logger and the last request being returned with an invalid version condition and message ATB217I being issued with ABENDEC7.

This APAR will result in the ENQ on SYSZAPPC (APPC_PPLU_LOG) being treated as RNL(NO).

Adding the APPC log stream after IPL time

If the LU is defined to accept protected conversations, via the SYNCLVL=SYNCPT and ATNLOSS=ALL in the VTAM APPL definitions, APPC/MVS attempts to connect to the APPC log stream at initialization of the LU (when LU is added for the first time, either via starting APPC or issuing the SET APPC=xx command). If the log stream does not exist, an operator message ATB208I is issued saying that the LU is active but not accepting protected conversations. The only remedy for this condition is to either issue an LUDEL and then an LUADD for the LU or start RRS if it was not started or, recycle RRS if it was already active.

The LU will not accept any protected conversations if the log stream is not defined. The program that attempted the protected conversation will get a Sync level not supported return code. DISPLAY APPC,LU,ALL will show SYNCPT=Y if the LU is syncpt-capable.

6.1.4 Recovery

You are not required to use staging data sets for APPC/MVS log data. However, if a system or CF failure causes the loss of APPC/MVS log data, warm/cold mismatches between local and partner LUs will result. To resolve such mismatches, you might have to:

Bring down APPC/MVS
Use RRS ISPF panels to remove the expressions of interest that APPC/MVS LUs have in units of recovery
Restart APPC/MVS

This manual intervention might be more costly than the potential performance impact of using staging data sets. Because APPC/MVS writes infrequently to its log, the performance impact should be minimal, and the use of STG_DUPLEX(YES) and DUPLEXMODE(UNCOND) ensures that no data will be lost even if you lose both the z/OS system and the CF containing the APC/MVS log stream.

6.1.5 Performance

After your initial log streams allocation, performance data is produced in a number of forms that can be useful to determine if any adjustments are necessary to your installation:

SMF 88 data produced by the System Logger
SMF 70–78 data produced by various z/OS components

There are several tools which aide in the analysis of log stream performance problems:

IXGRPT1 formats and reports the SMF 88 data produced by the System Logger
ERBRMFPP reports on the data captured in the SMF 70 -78 records

APPC/MVS doesn't have a lot of activity. For this reason performance are rarely an issue for this log stream.

The main fields in SMF88 that you should pay attention for this log stream are the OFFLOAD, DASD SHIFT, STRUCTURE FULL, ENTRY FULL and STAGING THRESHOLD. Refer to "SMF Type 88 records and IXGRPT1 program" on page 281 for a description of these fields and what to do in case of one of this condition happens in your installation.

< Day Day Up >