HP OpenVMS Systems Documentation

The Log Manager Control Program (LMCP) utility creates and manages the transaction logs used by DECdtm services.

LMCP lets you create and manage the transaction logs used by DIGITAL's distributed transaction manager, DECdtm services.

Format

RUN SYS$SYSTEM:LMCP

Parameters

None

Description

To invoke LMCP, enter RUN SYS$SYSTEM:LMCP at the DCL command prompt. At the LMCP prompt, you can enter any of the LMCP commands described in the following section.

To exit from LMCP, enter the EXIT command at the LMCP prompt, or press Ctrl/Z.

The following table summarizes the LMCP commands:

Closes the transaction log and stops the TP_SERVER process.

Requires the SYSNAM privilege.

Format

CLOSE LOG

Description

Use the CLOSE LOG command to:

• Close the transaction log of the local node.
• Stop the TP_SERVER process on the local node.

The CLOSE LOG command fails if the node is currently executing transactions.

CONVERT LOG

Creates a new transaction log and copies records from an existing transaction log to the new one.

Use the CONVERT LOG command when you want to move a transaction log or change its size.

Caution If a node already has a transaction log, using the CONVERT LOG command to create a new one can corrupt data. For information about how to use the CONVERT LOG command safely, see the HP OpenVMS System Manager's Manual.

The CONVERT LOG command requires:

• The CMKRNL privilege
• Read access to the existing transaction log and the directory it is in
• Read and write access to the directory in which the new transaction log is to be created

Format

CONVERT LOG old-filespec new-filespec

Parameters

old-filespec

The file specification of the transaction log whose records are to be copied.

The CONVERT LOG command uses the following defaults:

• If you omit the disk and directory, the CONVERT LOG command looks for the transaction log in the directories pointed to by the logical SYS$JOURNAL, which must be defined in executive mode in the system logical name table.
• If you omit the file type, the CONVERT LOG command uses .LM$JOURNAL.

new-filespec

The file specification of the new transaction log to be created.

For DECdtm services to use the transaction log, the file must have a name of the form SYSTEM$node.LM$JOURNAL, where node is the name of the node.

The CONVERT LOG command uses the following defaults:

• If you omit the disk and directory, the CONVERT LOG command creates the new transaction log in the first accessible directory pointed to by the logical SYS$JOURNAL, which must be defined in executive mode in the system logical name table.
• If you omit the file type, the CONVERT LOG command uses .LM$JOURNAL.

Qualifiers

/OWNER=uic

Specifies the owner of the new transaction log.

Specify the owner using the standard UIC format, as described in the OpenVMS User's Manual.

/SIZE=size

Specifies the size of the new transaction log in blocks.

The minimum size is 100 blocks. If you omit this qualifier, the new transaction log is created with the default size of 4000 blocks.

Example

LMCP> CONVERT LOG/SIZE=6000 DISK$LOG2:[LOGFILES]SYSTEM$RED.LM$OLD -
_LMCP> DISK$LOG2:[LOGFILES]SYSTEM$RED.LM$JOURNAL
 
      

This example creates a 6000-block transaction log called SYSTEM$RED.LM$JOURNAL in directory DISK$LOG2:[LOGFILES]. It then copies records from the existing transaction log, SYSTEM$RED.LM$OLD in directory DISK$LOG2:[LOGFILES], into the new transaction log.

CREATE LOG

Creates a new transaction log.

Caution If a node already has a transaction log, using the CREATE LOG command to create a new one can corrupt data.

Requires read and write access to the directory in which the transaction log is to be created.

Format

CREATE LOG filespec

Parameter

filespec

The file specification of the transaction log to be created.

For DECdtm services to use the transaction log, the file must have a name of the form SYSTEM$node.LM$JOURNAL, where node is the name of the node.

The CREATE LOG command uses the following defaults:

• If you omit the disk and directory, the CREATE LOG command creates the transaction log in the first accessible directory pointed to by the logical SYS$JOURNAL, which must be defined in executive mode in the system logical name table.
• If you omit the file type, the CREATE LOG command uses .LM$JOURNAL.

If you specify a disk and directory not pointed to by SYS$JOURNAL, a warning message is displayed. However, the transaction log is still created, but will not be used until either (a) SYS$JOURNAL is modified to point to the disk and directory where the log was created, or (b) you move the new transaction log to a directory pointed to by SYS$JOURNAL.

Qualifiers

/NEW_VERSION

Forces the CREATE LOG command to create a new version of an existing transaction log.

Caution Creating a new version of an existing transaction log can lead to data corruption. The data in the two transaction logs cannot be merged. Once it has started using the new transaction log, DECdtm services cannot access any transaction records in the old transaction log.

/OWNER=uic

Specifies the owner of the transaction log.

Specify the owner using the standard UIC format, as described in the OpenVMS User's Manual.

/SIZE=size

Specifies the size of the transaction log in blocks.

The minimum size is 100 blocks. If you omit this qualifier, the transaction log is created with the default size of 4000 blocks.

Example

LMCP> CREATE LOG/SIZE=5000 DISK$LOG1:[LOGFILES]SYSTEM$ORANGE.LM$JOURNAL
 
      

This example creates a 5000-block transaction log for node ORANGE in DISK$LOG1:[LOGFILES].

DUMP

Displays the contents of a transaction log.

Requires read access to the transaction log and the directory it is in.

Format

DUMP filespec

Parameter

filespec

The file specification of the transaction log whose contents you want to display.

The DUMP command uses the following defaults:

• If you omit the disk and directory, the DUMP command looks for the transaction log in the directories pointed to by the logical SYS$JOURNAL, which must be defined in executive mode in the system logical name table.
• If you omit the file type, the DUMP command uses .LM$JOURNAL.

Qualifiers

/ACTIVE

Selects records only for transactions that have not yet been forgotten.

/FORMAT (default)
/NOFORMAT

Determines whether the contents of the transaction log are displayed as formatted records. Specify both the /NOFORMAT and the /HEX qualifiers to display the contents of the transaction log in hexadecimal only.

If the /NOFORMAT qualifier is specified without the /HEX qualifier, only the transaction log header is displayed.

/HEX
/NOHEX (default)

Specifies that the contents of the transaction log are displayed as both ASCII characters and hexadecimal longwords. Specify both the /NOFORMAT and /HEX qualifiers to display the contents of the transaction log in hexadecimal only.

/LOGID=logid

Selects records only for transactions that have participants whose logid field matches the specified value.

The logid is in the Log ID field, to the right of the Type field. The value you specify must be exactly as it appears in the display, including hyphens.

Note that you can use this qualifier only with the /RM qualifier.

/OUTPUT[=filespec]

Requires read and write access to the directory in which the output file is to be created.

Specifies where the output from the DUMP command is sent. If you omit this qualifier, output is sent to the current SYS$OUTPUT device (usually your terminal). To send the output to a file, use the /OUTPUT qualifier. If you do not supply a file specification, the output is sent to the file LMCP_DUMP.LIS in your default directory.

/RM=name

Selects records only for transactions that have participants whose names begin with the specified value.

The participant name is shown in the Name field, and is output in both ASCII and hexadecimal.

If the participant name includes undisplayable characters, you can select records for that participant by using the hexadecimal form of its name. When specifying the hexadecimal form of the name, you must convert it by reversing the pairs in the hexadecimal number. For example, the participant name is:

Name (11): "SYSTEM$RED" (4445 52244D45 54535953)

The value you specify for the /RM qualifier is:

/RM=%X53595354454D24524544

/STATE=COMMITTED
/STATE=PREPARED

Selects records only for transactions in either the Committed or Prepared states.

/TID=transaction_id

Selects records only for the specified transaction.

The transaction_id is shown in the Transaction ID field. The value you specify must be exactly as it appears in the display, including hyphens.

Description

Use the DUMP command to display the contents of a transaction log. Example 15-1 is a sample of a transaction log, with the important fields identified.

Example 15-1 Sample Transaction Log

Log Manager Control Program V1.1 Dump of transaction log DISK$LOGFILE:SYSTEM$BLUE.LM$JOURNAL;1 End of file block 4002 / Allocated 4002 Log Version 1.0 Transaction log UID: 647327A0-2674-11C9-8001-AA00040069F8 (1) Penultimate Checkpoint: 000000000239 0039 Last Checkpoint: 00000000042E 002E Dump of transaction log DISK$LOGFILE:SYSTEM$BLUE.LM$JOURNAL;1 Present Length: 134 (00000086) Last Length: 0 (00000000) VBN Offset: 0 (00000000) Virtual Block: 2 (00000002) (2) Section: 3 (00000003) Record number 1 (00000001),(3) 114 (0072) bytes (4) Transaction state (1): PREPARED (5) Transaction ID: 1D017140-2676-11C9-9F34-08002B174360 (6) (8-JUL-2002 14:08:29.14) DECdtm Services Log Format V1.1 (7) Type ( 2): CHILD (8) Log ID: F1469720-4A0C-11CC-8001-AA000400B7A5 (9) Name (13): "SYSTEM$WESTRN" (4E 52545345 57244D45 54535953) (10) Type ( 8): CHILD NODE (8) Log ID: F1469720-4A0C-11CC-8001-AA000400B7A5 (9) Name (6): "WESTRN" (4E52 54534557) (10) Type ( 3): LOCAL RM (8) Log ID: 037100C0-0019-0003-0100-000000000000 (9) Name (6): "ORANGE" (4547 4E41524F) (10)

In this example, the significant fields are:

1. Transaction log header --- information about the transaction log's attributes.
2. Section header --- the section header of multiple transaction records.
3. Record number --- the record number, in both decimal and hexadecimal.
4. Record size --- the record size in both decimal and hexadecimal.
5. Transaction state --- the type of the record. This can be:
   • Prepared
     This type of record is logged when the transaction enters the Prepared state. Note that this type of record is not logged at the node on which the transaction was started.
   • Committed
     This type of record is logged when the transaction enters the Committed state.
   • Forgotten
     This type of record is logged:
     • When the transaction is aborted, if a record of type Prepared was logged for the transaction.
     • For a transaction that commits, when no participants require the local DECdtm transaction manager to remember that the outcome of the transaction is commit.
     
     Note that DECdtm uses the presumed abort logging protocol.
   • Checkpoint
     Unlike the other types of record, this is not associated with a particular transaction. It is used internally by the DECdtm transaction manager to compress space in the transaction log.
6. Transaction ID --- the unique transaction identifier (TID) generated by the DECdtm transaction manager.
7. DECdtm Services Log Format --- the version number of the transaction log format.
8. Type --- information about the participant in the transaction. This can be:
   • Child --- an immediate child transaction manager. This transaction manager may query the local DECdtm transaction manager to determine the outcome of the transaction.
   • Child Node --- the name of the node that an immediate child transaction manager is on.
   • Parent --- the immediate parent transaction manager. The local DECdtm transaction manager may query this transaction manager to determine the outcome of the transaction.
   • Parent Node --- the name of the node that an immediate parent transaction manager is on.
   • Local RM --- a resource manager on the local node.
9. Log ID --- the identifier of the participant's log. For type Child, Child Node, Parent, or Parent Node, this is the identifier of the DECdtm transaction log. For a local resource manager, this is the identifier of its private log.
10. Name --- the name of the participant in the transaction, in both ASCII and hexadecimal.

Example

LMCP> DUMP/RM="RMS$" DISK$LOGFILE:SYSTEM$BLUE.LM$JOURNAL
 
      

This example displays the contents of the transaction log for node BLUE, selecting only transactions in which RMS Journaling for OpenVMS is participating.

Dump of transaction log DISK$LOGFILE:SYSTEM$BLUE.LM$JOURNAL;1 End of file block 4002 / Allocated 4002 Log Version 1.0 Transaction log UID: 6A034B20-6FCC-0095-D7E4-EAA500000000 Penultimate Checkpoint: 00000000382E 002E Last Checkpoint: 000000003C2E 002E Dump of transaction log DISK$LOGFILE:SYSTEM$BLUE.LM$JOURNAL;1 Present Length: 46 (0000002E) Last Length: 512 (00000200) VBN Offset: 30 (0000001E) Virtual Block: 32 (00000020) Section: 1 (00000001) Record number 2 (00000002), 5 (0005) bytes Transaction state (3): CHECKPOINT Checkpoint record contains no active transactions. Record number 1 (00000001), 21 (0015) bytes Transaction state (0): FORGOTTEN Transaction ID: 271D9FC0-7082-0095-98E7-EAA500000000 Dump of transaction log DISK$LOGFILE:SYSTEM$BLUE.LM$JOURNAL;1 Present Length: 113 (00000071) Last Length: 512 (00000200) VBN Offset: 29 (0000001D) Virtual Block: 31 (0000001F) Section: 2 (00000002) Record number 1 (00000001), 93 (005D) bytes Transaction state (2): COMMITTED Transaction ID: 271D9FC0-7082-0095-98E7-EAA500000000 (3-MAR-2002 13:53:03.42) DECdtm Services Log Format V1.1 Type ( 2): CHILD Log ID: EF006060-CF37-11C9-8001-AA000400DEFA Name (10): "SYSTEM$ORANGE" (45 474E4152 4F244D45 54535953) Type ( 8): CHILD NODE Log ID: EF006060-CF37-11C9-8001-AA000400DEFA Name ( 6): "ORANGE" (4547 4E41524F) Type ( 3): LOCAL RM Log ID: 28C5D180-7082-0095-0000-000000000000 Name (22): "RMS$USER1.......`....." (0000 00178B60 00000000 00000031 52455355 24534D52) . . . Total of 1 transactions active, 0 prepared and 1 committed

EXIT

Exits LMCP.

Format

EXIT

HELP

Provides help on LMCP commands.

Format

HELP [help-topic [help-subtopic]]

Parameter

help-topic

Specifies the command that you want help for.

help-subtopic

Specifies the parameter or qualifier that you want help for.

REPAIR

Changes the state of transactions.

Caution The REPAIR command can corrupt data. Use it only if none of the resource managers participating in the transaction provides a means of changing transaction states.

The REPAIR command requires:

• The CMKRNL privilege
• Read and write access to the transaction log and the directory it is in

Format

REPAIR filespec

Parameter

filespec

The file specification of the transaction log containing the transactions whose states you want to change.

The REPAIR command has the following requirements:

• The logical SYS$JOURNAL must be defined in executive mode in the system logical name table.
• The transaction log must be in a directory pointed to by the logical SYS$JOURNAL.
• The file type of the transaction log must be .LM$JOURNAL.

The REPAIR command uses the following defaults:

• If you omit the disk and directory, the REPAIR command looks for the transaction log in the directories pointed to by the logical SYS$JOURNAL.
• If you omit the file type, the REPAIR command uses .LM$JOURNAL.

Qualifiers

/LOGID=logid

Selects records only for transactions that have participants whose logid field matches the specified value.

The logid is in the Log ID field, to the right of the Type field in the output from the DUMP command. The value you specify must be exactly as it appears in the display, including hyphens.

Note that you can use this qualifier only with the /RM qualifier.

/RM=name

Selects records only for transactions that have participants whose names begin with the specified value.

The participant name is shown in the Name field in the output from DUMP, and is output in both ASCII and hexadecimal.

If the participant name includes undisplayable characters, you can select records for that participant by using the hexadecimal form of its name. When specifying the hexadecimal form of the name, you must convert it by reversing the pairs in the hexadecimal number. For example, the participant name is:

Name (11): "SYSTEM$RED" (4445 52244D45 54535953)

The value you specify for the /RM qualifier is:

/RM=%X53595354454D24524544

/STATE=COMMITTED
/STATE=PREPARED

Selects records only for transactions in either the Committed or Prepared states.

/TID=transaction_id

Selects records only for the specified transaction.

The transaction_id is shown in the Transaction ID field in the output from the DUMP command. The value you specify must be exactly as it appears in the display, including hyphens.

Description

Use the REPAIR command to change the state of transactions.

Caution The REPAIR command can corrupt data. Use it only if none of the resource managers participating in the transaction provides a means of changing transaction states.

Use this command only if none of the resource managers participating in the transaction provides a means of changing the transaction state.

Change the transaction state only when you already know the outcome of the transaction and need to manually update the transaction log immediately. You might want to do this because, for example, you have lost the network link to a remote node.

When you use the REPAIR command you use qualifiers to specify which transactions you want to change. By default, the REPAIR command selects all transactions.

Once you have selected the transactions to change, enter the REPAIR subcommand mode. Within this mode, the prompt changes to REPAIR>, and you have an additional set of subcommands. Use these subcommands either to manually change the state of the transaction or to select the next transaction that matches your selection criteria. The subcommands are as follows:

Subcommand	Action
ABORT	Specifies that a Prepared transaction is to be aborted by removing its record from the transaction log. This writes a record of type Forgotten for the transaction. Note that DECdtm services use the presumed abort logging protocol.
COMMIT	Specifies that a Prepared transaction is to be committed. This writes a record of type Committed for the transaction.
EXIT	Returns to the LMCP prompt.
FORGET	Specifies that a Committed transaction can be removed from the transaction log. This writes a record of type Forgotten for the transaction.
NEXT	Displays the next transaction that matches your selection criteria.

LMCP displays each of the selected transactions in turn, so that you can change them. For each selected transaction, you can either use the ABORT, COMMIT, and FORGET subcommands to change the state of the transaction, or use the NEXT subcommand to select the next transaction.

To exit from the REPAIR subcommand mode, enter the EXIT subcommand or press Ctrl/Z.

Example

LMCP> REPAIR/STATE=PREPARED DISK$JOURNALS:[LOGFILES]SYSTEM$ORANGE
 
      

In this example, transactions to be modified are selected from the transaction log for node ORANGE. The transactions selected are those in the Prepared state.

The first transaction is committed by manually changing its state from Prepared to Committed, then the NEXT subcommand is used to advance to the next selected transaction.

Dump of transaction log DISK$JOURNALS:[LOGFILES]SYSTEM$ORANGE;1 End of file block 4002 / Allocated 4002 Log Version 1.0 Transaction log UID: 98A43B80-81B7-11CC-A27A-08002B1744C3 Penultimate Checkpoint: 00000407B9AC 07AC Last Checkpoint: 00000407C3B7 07B7 Transaction state (1): PREPARED Transaction ID: 9F7DF804-CBC4-11CC-863D-08002B17450A (18-OCT-2002 16:11:03.67) DECdtm Services Log Format V1.1 Type ( 3): LOCAL RM Log ID: 00000000-0000-0000-0000-000000000000 Name (1): "B" (42) Type ( 4): PARENT Log ID: AEC2FB64-C617-11CC-B458-08002B17450A Name (13): "SYSTEM$BLUE" (45554C 42244D45 54535953) Type (16): PARENT NODE Log ID: AEC2FB64-C617-11CC-B458-08002B17450A Name (6): "BLUE" (45554C42)) REPAIR> COMMIT REPAIR> NEXT . . .