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:

• CICS or CICS using RRS

• IMS using APPC/MVS and RRS

• Batch processes using APPC/MVS and RRS

  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.

• CICS environment

  Transactions are supported across a link by default. There is no special configuration required.

• IMS environment

  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.

• Batch environment

  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:

1. Determine the required arguments for the CRMLOGS command as shown in Table 8-1.

   Table 8-1 Command Line Option for CRMLOGS

   Keyword	Default	Optional/ Required	Description
   <crm name>	None	Required	The CRM name used on the CRM command line, and configured in the WebLogic Administration Console.

   
    

2. Follow the instructions for either:

• Viewing the CRM Log Files in an MVS Environment

or

• Viewing CRM Log Files in an z/OS or OS/390 Unix Environment

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.

1. Use the set commands shown in Table 8-2 to customize the sample JCL.

   Table 8-2 JCL set Commands for the Sample CRMLOGS

   Command Name	Description
   SET LOGSCMD	Sets the CRMLOGS command line parameters.
   SET OBJLIB	Indicates the name of the PDSE library where the CRMLOGS executable is installed.
   SET RUNOPTS	Specifies the optional runtime operands for the Language Environment (LE). This is usually used for debugging. See your system administrator for more information.
   SET DATA	Indicates the data set containing the ENVFILE.
   SET ENVFILE	Indicates the name of the PDS member that contains the environment variables for the CRMLOGS. A sample member, ENV, is delivered with your product.
   SET RUNOPTS	Specifies the optional runtime operands for the Language Environment (LE). This is usually used for debugging. See your system administrator for more information if this option is used.
   SET SIZE	Defines the region size for the running CRMLOGS task.
   SET ENV	Indicates the ENVFILE DD name. This value is pre-set.
   SET CEE	Specifies the high-level qualifier for the LE run-time library. Note: Uncomment the SET CEE line and tailor the STEPLIB concatenation if these libraries are not in your system link library concatenation.
   SET CBC	Specifies the high-level qualifier for the C/C++ runtime library. Note: Uncomment the SET CBC line and tailor the STEPLIB concatenation if these libraries are not in your system link library concatenation.

   
    

2. Run a CRMLOGS job using JCL written for your system. Listing8-1 shows a JCL for the CRMLOGS command.

   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.

• Cold Start

  Starting / restarting a link without ensuring the integrity of the restart.

• Warm Start

  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:

• Remove the WebLogic transaction logs.

  Warning: This will affect all in-flight transactions within the WebLogic Server domain.

• Remove the CRM blob and restart logs.

  Warning: This will affect the start requirements for all links configured for the CRM.

• Restart the mainframe region with a cold start, or maintain the mainframe application logs so that the link may be restarted cold.

  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.