Document revision date: 15 July 2002

For every node you add to an OpenVMS Cluster, you must create a new transaction log. This section describes how to create a transaction log for a new node.

How to Perform This Task

Before you perform this task, the new node must be configured into the cluster. For instructions on how to configure a node into a cluster, refer to OpenVMS Cluster Systems.

1. Decide the size and location of the new node's transaction log, using the guidelines in Section 27.2. Remember that the disk must have enough contiguous space to hold the log.
2. Make sure that the disk on which you want to create the transaction log is mounted clusterwide.
3. Decide which directory you want to create the new transaction log in. You may want to create a new directory for the transaction log.
4. Make sure that SYS$JOURNAL points to the directory in which you want to create the new node's transaction log. If SYS$JOURNAL does not point to this directory, use SYSMAN to redefine SYS$JOURNAL clusterwide:

   DO DEFINE/SYSTEM/EXECUTIVE_MODE SYS$JOURNAL dirspec[,...]

   where dirspec is the full specification of a directory containing one or more transaction logs. List all the directories that contain transaction logs, including the directory in which you want to create the new node's transaction log. You can list the directories in any order.

5. If you redefined SYS$JOURNAL in step 4, edit the SYS$MANAGER:SYLOGICALS.COM command procedure to update the SYS$JOURNAL definition.
   If you created node-specific versions of SYLOGICALS.COM, edit all the versions.
6. Create the transaction log, using LMCP's CREATE LOG command:

   CREATE LOG [/SIZE=size] dirspecSYSTEM$node.LM$JOURNAL

   where:

   size	is the size of the transaction log in blocks. By default, the size of the transaction log is 4000 blocks.
   dirspec	is the full specification of the directory in which you want to create the transaction log.
   node	is the name of the new node.

Example

This example shows how to create a transaction log for a new node, whose SCSNODE name is WHITE.

In this example, the cluster members and the locations of their transaction logs are as follows:

Node	Directory Containing Log
BLUE	DISK$LOG3:[LOGFILES]
RED	DISK$LOG2:[LOGFILES]

Neither node has a node--specific version of SYLOGICALS.COM.

Decide the size and location of WHITE's transaction log:

Node	Size of Log (in Blocks)	Disk
WHITE	5000	DUA4

Mount the disk DUA4 clusterwide:

$ MOUNT/CLUSTER/SYSTEM DUA4: LOG4

Create a directory for the transaction log:

$ CREATE/DIRECTORY DISK$LOG4:[LOGFILES]

Redefine SYS$JOURNAL:

$ RUN SYS$SYSTEM:SYSMAN SYSMAN> SET ENVIRONMENT/CLUSTER SYSMAN> DO DEFINE/SYSTEM/EXECUTIVE_MODE SYS$JOURNAL - _SYSMAN> DISK$LOG2:[LOGFILES], DISK$LOG3[LOGFILES], DISK$LOG4:[LOGFILES] SYSMAN> EXIT

Edit the SYS$STARTUP:SYLOGICALS command procedure to update the SYS$JOURNAL definition. Then create the transaction log:

$ RUN SYS$SYSTEM:LMCP LMCP> CREATE LOG/SIZE=5000 DISK$LOG4:[LOGFILES]SYSTEM$WHITE.LM$JOURNAL LMCP> EXIT

27.11 Removing a Node

This section describes how to remove a node if you are using DECdtm services.

How to Perform This Task

If you have a standalone machine, perform steps 1 to 8 only.

1. Log in to the node that you want to remove.
2. Stop all the software that uses DECdtm services.
3. Find out whether the node's transaction log contains any active transactions, using LMCP's DUMP/ACTIVE command:

   DUMP/ACTIVE SYSTEM$node.LM$JOURNAL

   
   where node is the name of the node that you want to remove.
   This command displays details of all the active transactions. The last line gives the total number of active transactions.

4. If the transaction log contains active transactions, follow these steps:
   1. Run recovery procedures for all software that uses DECdtm services.
   2. Find out if the node's transaction log still contains active transactions, using LMCP's DUMP/ACTIVE command.
   3. If the transaction log still contains active transactions, contact your Compaq support representative.
5. Redefine SYS$JOURNAL to exclude the directory that contains the transaction log of the node you want to remove, unless the directory contains other transaction logs.

   DEFINE/SYSTEM/EXECUTIVE_MODE SYS$JOURNAL dirspec[,...]

   where dirspec is the full specification of a directory containing one or more transaction logs. List all the directories that contain any transaction logs other than the transaction log of the node you are removing. You can list the directories in any order.
   In a cluster, use SYSMAN to redefine SYS$JOURNAL clusterwide.

6. If you redefined SYS$JOURNAL in step 5, edit the SYS$MANAGER:SYLOGICALS.COM command procedure to update the SYS$JOURNAL definition.
   If you created node-specific versions of SYLOGICALS.COM, edit all the versions.
7. Archive the transaction log.
8. Shut down the node.
9. Restart the software that uses DECdtm services.
10. Reconfigure the cluster to remove the node.
    For information about how to reconfigure a cluster, refer to OpenVMS Cluster Systems.

Example

This example shows how to remove the node BLUE. In this example, the cluster members and the locations of their transaction logs are as follows:

Node	Directory Containing Log
BLUE	DISK$LOG3:[LOGFILES]
RED	DISK$LOG2:[LOGFILES]
WHITE	DISK$LOG4:[LOGFILES]

None of the nodes has a node--specific version of the SYLOGICALS.COM command procedure.

Log in to node BLUE.

Stop all the software that uses DECdtm services. Then find out if BLUE's transaction log contains any active transactions:

$ RUN SYS$SYSTEM:LMCP LMCP> DUMP/ACTIVE SYSTEM$BLUE.LM$JOURNAL Dump of log file DISK$LOG3:[LOGFILES]SYSTEM$BLUE.LM$JOURNAL . . . Total of 0 transactions active, 0 prepared and 0 committed. LMCP> EXIT

Redefine SYS$JOURNAL:

$ RUN SYS$SYSTEM:SYSMAN SYSMAN> SET ENVIRONMENT/CLUSTER SYSMAN> DO DEFINE/SYSTEM/EXECUTIVE_MODE SYS$JOURNAL - _SYSMAN> DISK$LOG2:[LOGFILES], DISK$LOG4:[LOGFILES] SYSMAN> EXIT

Edit the SYS$MANAGER:SYLOGICALS.COM command procedure to update the SYS$JOURNAL definition.

Archive BLUE's transaction log. Then shut down node BLUE:

$ @SYS$SYSTEM:SHUTDOWN.COM . . . Should an automatic system reboot be performed [NO]? NO

Restart the software that uses DECdtm services. Then reconfigure the cluster:

$ @SYS$STARTUP:CLUSTER_CONFIG.COM Cluster Configuration Procedure 1. ADD a node to a cluster. 2. REMOVE a node from the cluster. 3. CHANGE a cluster member's characteristics. 4. CREATE a duplicate system disk for BLUE. Enter choice [1]: 2 . . . Updating network database... The configuration procedure has completed successfully.

27.12 Disabling DECdtm Services

By default, DECdtm services start automatically when you boot the computer. The DECdtm process, TP_SERVER, then checks for a transaction log, and continues checking until it finds one.

Disable DECdtm services if you do not use, and do not plan to use, any software that uses DECdtm services. This saves memory and CPU time.

In an OpenVMS Cluster, disable DECdtm services on all the nodes in the cluster.

How to Perform This Task

1. For each node:
   1. Log in to the node.
   2. Stop the TP_SERVER process using LMCP's CLOSE LOG command:

      $ RUN SYS$SYSTEM:LMCP LMCP> CLOSE LOG

      
      The CLOSE LOG command stops the TP_SERVER process, providing no software is using DECdtm services.
      If the CLOSE LOG command fails, do not continue this task. If you have already stopped the TP_SERVER process on other nodes in a cluster system, restart the process using the SYS$STARTUP:DECDTM$STARTUP.COM command procedure.

2. Add the following line to the SYS$MANAGER:SYLOGICALS.COM command procedure:

   $ ! $ DEFINE/SYSTEM/EXECUTIVE_MODE SYS$DECDTM_INHIBIT yes $ !

   
   If you created node-specific versions of SYLOGICALS.COM, edit all the versions.
   This stops the TP_SERVER process being created the next time you boot the system.

Enable DECdtm services only if you have previously disabled them and you now want to run software that uses DECdtm services.

How to Perform This Task

1. Deassign the logical name SYS$DECDTM_INHIBIT:

   $ DEASSIGN/SYSTEM/EXECUTIVE_MODE SYS$DECDTM_INHIBIT

   
   In an OpenVMS Cluster, use SYSMAN to deassign SYS$DECDTM_INHIBIT clusterwide.

2. Start up the DECdtm services process, TP_SERVER:

   $ @SYS$STARTUP:DECDTM$STARTUP.COM

   
   In an OpenVMS Cluster, use SYSMAN to start up the TP_SERVER process clusterwide.

3. Edit the SYS$MANAGER:SYLOGICALS.COM command procedure to delete the SYS$DECDTM_INHIBIT definition. This ensures that DECdtm services start automatically when you boot the system.

Example

This example shows how to enable DECdtm services in a cluster environment.

Deassign SYS$DECDTM_INHIBIT, then start up the TP_SERVER process.

$ RUN SYS$SYSTEM:SYSMAN SYSMAN> SET ENVIRONMENT/CLUSTER SYSMAN> DO DEASSIGN/SYSTEM/EXECUTIVE_MODE SYS$DECDTM_INHIBIT SYSMAN> DO @SYS$STARTUP.DECDTM$STARTUP.COM SYSMAN> EXIT

Edit the SYS$MANAGER:SYLOGICALS.COM command procedure to delete the SYS$DECDTM_INHIBIT definition.

27.14 Using the XA Gateway (Alpha Only)

DECdtm/XA provides support for coordinating and managing transactions that use XA. By using an XA Gateway, DECdtm/XA can join other Resource Managers (RM) in transactions that are managed by another Transaction Manager (TM). This section describes how to configure and use DECdtm XA Gateway support.

To use DECdtm/XA and ensure proper startup and shutdown of DECdtm/XA services, the following command files must be invoked:

• SYS$STARTUP:DDTM$XA_STARTUP.COM
• SYS$STARTUP:DDTM$XA_SHUTDOWN.COM

Add the command @SYS$STARTUP:DDTM$XA_STARTUP.COM to the startup database or to the command file SYS$MANAGER:SYSTARTUP_VMS.COM.

Add the command @SYS$STARTUP:DDTM$XA_SHUTDOWN.COM to the command file SYS$MANAGER:SYSHUTDWN.COM.

Perform the following steps to verify that DECdtm XA services are operating properly:

1. Use the XGCP utility to create a gateway log file with the same name as the local OpenVMS node. See Section 27.14.1 and the OpenVMS System Management Utilities Reference Manual for details.
2. Run SYS$TEST:DECDTM_XG_IVP.EXE.
3. Use the XGCP utility to stop and restart the gateway server. This step is essential if you choose to configure the gateway with a name different than that of the local OpenVMS node. For more information on the XGCP utility, see the OpenVMS System Management Utilities Reference Manual.

The XA Gateway is configured into each transaction processing (TP) process as an XA-compliant resource manager. The XA Gateway handles XA calls from the XA transaction manager (TM) and maps them into calls to DECdtm system services. This allows DECdtm to send the appropriate events to any DECdtm compliant Resource Manager (RM) used in a TP process.

The operation of the XA Gateway is transparent to the RM; DECdtm RMs do not need any modification to be used with the XA Gateway.

The XA Gateway uses a log file to record the mapping between XA transactions and DECdtm transactions. The log file is managed by the gateway server process DDTM$XG_SERVER.

Create the gateway log file with the XGCP utility (see the OpenVMS System Management Utilities Reference Manual). The size of the gateway log file depends on the number of concurrently active transactions. Up to 600 bytes are required for each active transaction, depending on the size of the transaction ID (TID) used by the XA TM. The gateway log file expands automatically when required.

The gateway log file resides in the directory specified by the logical name SYS$JOURNAL and has a name of the form SYSTEM$name.DDTM$XG_JOURNAL. For optimum performance, move each gateway log file and each DECdtm log file to a separate physical device, and define SYS$JOURNAL as a search list for the set of physical devices.

The XA Gateway requires an association on each OpenVMS Cluster node between an XA transaction manager and the XA Gateway log file. This association is managed by specifying a gateway name as follows:

• Use the XGCP utility to create a gateway log file with the gateway name (see the OpenVMS System Management Utilities Reference Manual).
• The gateway name is specified in the xa_open information string when the Gateway RM is configured in applications run under the control of an XA TM. (XA RM configuration is described in OpenVMS Programming Concepts Manual, Volume II.)
• The first XA application run by the XA TM binds the gateway name to the local node of the OpenVMS Cluster. The gateway name remains bound to that node until the gateway server is stopped.

All XA applications that run on the local node must be configured with the same gateway name. XA applications using the same name cannot run on other OpenVMS Cluster nodes. Therefore, you normally define one gateway name and create one gateway log file for each node of an OpenVMS Cluster.

You can change the association of a gateway name and bind the gateway name to a different OpenVMS Cluster node, provided that the node can access the gateway log file. To change the association of a gateway name, perform the following steps:

1. Stop all XA applications on the original node.
2. Use the XGCP utility to stop the gateway server on the original node.
3. Stop all XA applications on the new node.
4. Stop the gateway server on the new node and then restart the gateway server.
5. Run the original XA applications on the new node.

Gateway log files are not large and it is better never to delete them. If you do delete an unwanted gateway log file, first use the DECdtm XGCP utility to verify that the gateway is not still a participant in any prepared transactions. The gateway participant name is DDTM$XG/name.

The gateway server uses the following system logical names:

• SYS$DECDTM_XG_REQS
  Number of concurrent requests processed by the server, in the range 100 to 100,000. This determines the size of the global section that DDTM$XG uses for communication with the server, and the quotas required by the server. The parameter is specified by defining the logical name SYS$DECDTM_XG_REQS. Changes to the parameter do not take effect until after the server and all client processes have been stopped.
  If the value of this parameter is exceeded during operation, client requests are blocked instead of being processed in parallel.
• SYS$DECDTM_XA_TRANS
  Estimated number of concurrent XA transactions, in the range 1000 to 1,000,000. This determines the size of indexing tables used internally in the server. The parameter is specified by defining the logical name SYS$DECDTM_XA_TRANS. Changes to this parameter do not take effect until after the server has been stopped.
  If the value of this parameter is exceeded during operation, server CPU use will increase. However, the effect is unlikely to be noticeable until the value of this parameter is exceeded by a factor of 10 or more.

	privacy and legal statement
6017PRO_107.HTML