bea.com | products | dev2dev | support | askBEA |
![]() |
![]() |
|
![]() |
e-docs > WebLogic Java Adapter for Mainframe > Configuration and Administration Guide > Administering Transactions |
Configuration and Administration Guide
|
Administering Transactions
WebLogic Server provides J2EE transactional support using Java Transactional API (JTA). WebLogic Server is the transaction manager. The WebLogic JAM Gateway will register with the transaction manager, and become part of a transaction. When a request is made to a remote service, a foreign transaction manager becomes involved in the distributed transaction. The foreign transaction manager is one of the following:
Figure 8-1 Transactional Support
The two-phase commit protocol is a method of coordinating a single transaction across two or more resource managers, ensuring data integrity. A single transaction is coordinated by a transaction manager. When the transaction spans transaction managers, then an additional resource manager is required, the communications resource manager. The communication resource manager manages the two phase commit protocol to the foreign transaction manager. This is referred to as a distributed WebLogic Server transaction.
Configuring Logical Units with Transactional Support
When WebLogic JAM is started, it will always attempt to configure the mainframe domain as part of the distributed WebLogic Server transaction environment. If a CRM link is not configured to support transactions, WebLogic JAM will establish on startup that the link will not support transactions.
If the following message appears during link startup, that link is not configured to support transactions.
"WARN: Synclevl on link <link> negotiated down to 1"
In order for the link between the CRM and the back-end environments to support transactions, both environments must be configured for synclevel support.
Configure the CRM Logical Unit
To configure the CRM environment for synclevel, the CRM logical unit must be configured. The SYNCLVL parameter on the VTAM APPLID definition must be set to SYNCPT. For further information about setting VTAM APPLID parameters, refer to Configuring WebLogic JAM Connectivity.
Configure the Back-end Environment
The back-end application must be configured to support synclevel.
Transactions are supported across a link by default. There is no special configuration required.
The APPC/MVS logical unit must be configured. The SYNCLVL parameter on the VTAM APPLID definition must be set to SYNCPT. The ATTNLOSS parameter must be set to ALL.
The APPC/MVS logical unit must be configured. The SYNCLVL parameter on the VTAM APPLID definition must be set to SYNCPT. The ATTNLOSS parameter must be set to ALL.
For each of these environments, if RRS is used as the transaction manager, RRS must be active. However, if RRS is not active, there will be no notification when the link is started that the environment cannot support transactions.
Transaction Log Files
To ensure data integrity, a transaction manager maintains a transaction log. Each log entry tracks the state of a two-phase commit sequence. When two transaction managers are involved, the logs of both managers must be synchronized. In the SNA protocol, two transaction managers synchronize their logs by exchanging and comparing log names when a link is started or restarted.
In addition, the WebLogic JAM CRM maintains its own transaction logs.
JTA Log Files
WebLogic Server log files are stored under the config/<domain>/logs directory. The WebLogic administration console can be used to view these logs.
WebLogic JAM CRM Log Files
WebLogic JAM CRM log files are stored under the application directory of the CRM. The location of these files is determined by the setting of the APPDIR environment variable. APPDIR can specify a directory in a z/OS or OS/390 Unix environment, or a high-level qualifier of the log data set in the MVS environment.
The JAM CRM creates two types of log files, restart logs and blob logs. Both can be viewed using the CRMLOGS utility.
Restart Log File
The restart log stores a single entry for each link. Each entry contains the log names for the CRM and the back-end system for one link. These names are used to perform log comparisons between the two.
The file name is described as follows:
CRM.<crm name>.RSTRTLOG
Note: On an MVS system, there is a high-level qualifier preceding the file name.
Blob Log File
The blob log file maintains the state of the two-phase transmit protocol for each active transaction. The file name is described as follows:
CRM.<crm name>.BLOBLOG
Note: On an MVS system, there is a high-level qualifier preceding the file name.
Viewing CRM Log Files
Use the CRMLOGS command to view the contents of the CRM restart log and blob log. This is useful if in-flight transactions have been stopped and need to be recovered. For more information about recovering transactions, see Recovery.
To view the CRM log files:
Table 8-1 Command Line Option for CRMLOGS
or
Viewing the CRM Log Files in an MVS Environment
To view the CRM log files in an MVS environment, use JCL. A sample JCL is included with your WebLogic JAM installation in member.
Table 8-2 JCL set Commands for the Sample CRMLOGS
Listing 8-1 Sample JCL for CRMLOGS Command
//*****************************************************************
//* THIS JOB IS USED TO CHECK THE RECOVERY LOGS FOR *
//* OUTSTANDING TRANSACTION DATA. *
//* *
//* @(#)$Id: crmlogs.jcl,v 1.3 2000/05/17 16:20:27 jsmith Exp $
//* Copyright (c)2000 BEA Systems, Inc., all rights reserved. *
//***************************************************************
//* YOU MUST SET THE ENVIRONMENT VARIABLES NEEDED BY CRMLOGS *
//***************************************************************
//***************************************************************
//* LOGSCMD IS USED TO SET THE DESIRED CRM NAME *
//* OBJLIB IS THE LOAD LIBRARY CONTAINING THE PROGRAM OBJECTS *
//* RUNOPTS SETS ANY DESIRED LE RUNTIME OPTIONS (OPTIONAL) *
//* DATA IS THE DATA SET THAT CONTAINS THE ENVIRONMENT VARIABLES *
//* ENVFILE NAMES THE MEMBER THAT CONTAINS THE ENVIRONMENT VARS *
//* SIZE SETS THE REGION SIZE FOR THE CRM PROCESS *
//* ENV SETS THE ENVIRONMENT VARIABLES DD NAME *
//* TAILOR YOUR JCL FOR THE BELOW IF THESE LIBRARIES ARE NOT *
//* IN YOUR SYSTEM LINK LOAD LIBRARY CONCATENATION *
//* CEE IS THE HLQ FOR THE LE RUNTIME LIBRARY *
//* CBC IS THE HLQ FOR THE C/C++ RUNTIME LIBRARY *
//***************************************************************
// SET LOGSCMD=<crm name>
// SET OBJLIB=
// SET DATA=
// SET ENVFILE=
// SET RUNOPTS=
// SET SIZE=10M
// SET ENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
//* SET CEE=CEE,CBC=CBC
//CRMLOGS EXEC PGM=CRMLOGS,REGION=&SIZE,
// PARM='POSIX(ON) &ENV &RUNOPTS/&SNAGRP'
//STEPLIB DD DSN=&OBJLIB,DISP=SHR
//* DD DSN=&CEE..SCEERUN,DISP=SHR
//* DD DSN=&CBC..SCLBDLL,DISP=SHR
//MSGFILE DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//ENV DD DSN=&DATA(ENVFILE),DISP=SHR
//
Viewing CRM Log Files in an z/OS or OS/390 Unix Environment
You can view the CRM log files in a z/OS or OS/390 Unix environment by running CRMLOGS from a command line. To view the CRM log files from a command line enter the CRMLOGS command with the CRM name.
For example, to view CRM logs for CRM mycrm, enter the following at the command line.
CRMLOGS mycrm
Mainframe Application Log
Each type of back-end environment maintains a transaction log, and has established methods for viewing the log. For information on maintaining and viewing these logs, refer to the product documentation for your environment.
Restarting Links (cold/warm)
When restarting a transactional link, all parties involved in the distributed transaction must agree upon the integrity of this restart. This includes the identification required for SNA communication, and agreement by all parties on the recovery of any items that were in two-phase commit sequence when the link was stopped.
This information is kept in the logs that were described in the previous section, and include the WebLogic Server logs, the mainframe application logs and theWebLogic JAM CRM restart and blob logs.
There are two ways to restart a transactional link with regards to its integrity: cold start and warm start.
Starting / restarting a link without ensuring the integrity of the restart.
Ensuring the integrity of the link before starting/restarting a link.
Cold Start
When a link is started for the first time, the CRM log files are created. The SNA communication between the WebLogic JAM CRM and the mainframe application (CICS, IMS or APPC/MVS) requires that both sides exchange and hold on to their log names. The CRM creates a restart log to hold this information. The information must match the information that is held by the remote mainframe region on each subsequent restart. In addition, the CRM creates a blob log to hold all two-phase commit sequence information for each transactional request.
When a link must be restarted, but does not require preserving the integrity of the previous start, (the log names will not be exchanged and no items will be recovered), then the link may be started with a cold start.
Starting a Link with a Cold Start
The following steps are required to start the link with a cold start:
Warning: This will affect all in-flight transactions within the WebLogic Server domain.
Warning: This will affect the start requirements for all links configured for the CRM.
Warning: Check with your administrator on how this will affect the other resources in the region.
Although a cold start is not recommended for a restart of a link, there are times when a cold start is necessary. Usually this is only done when manual intervention was used to recover in-flight transactional requests on the link, or when there is no recovery required to restart the link.
Warm Start
A warm start occurs when a link is restarted while ensuring the integrity of the previous start. The SNA communication between the WebLogic JAM CRM and the mainframe application (CICS, IMS or APPC/MVS) exchange log names to ensure that data integrity can be maintained on the restart. In addition, any in-flight transactions that are recorded in the WebLogic Server transaction logs, the CRM transaction blob log or the mainframe application transaction logs are recovered during the restart procedure.
A warm start is unsuccessful if the CRM link log names and the mainframe application log names are not accepted by either side in the exchange logs sequence. The link will be established, but will be unable to service transactional requests.
If all items in recovery are not recovered on the restart, the link will be established as a transactional link. However, the items that were not recovered remain "unrecovered", and the resources allocated to the transaction remain unavailable. Manual intervention must occur to recover the items.
Recovery
The transaction logs in the WebLogic JAM distributed transaction are used to maintain the two-phase commit state of a transactional request. The two-phase commit is the sequence of events that occurs between the transaction managers and resource managers when a commit or rollback begins.
If the transaction should fail before the sequence of events is complete, and the transaction managers are unable to communicate the failure successfully and release the transaction resources, then the transaction must be recovered. This typically happens only when a resource, a resource manger or a transaction manager becomes unavailable. When the unavailable entity becomes available again, then all participants in the transaction attempt to finalize or recover the transaction to its final state.
Initiating Recovery
To initiate recovery, the failed entity must be restarted, and the participating WebLogic Server or Servers must be stopped and restarted. The actual recovery occurs when all participants agree to commit or rollback the transaction resources and release the transaction resources. If the participants in the transaction are unable to agree how to handle the recovery, then the state of the transaction becomes heuristic. Manual intervention must occur to update the resources appropriately.
Notes: Until recovery is performed for a transaction, the transaction resources will be held and remain unavailable. This includes the SNA session resources.
To initiate recovery, the WebLogic Server or Servers which participated in the failed transactions must be restarted.
![]() |
![]() |
![]() |
![]() |
||
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |