HP 3000 Manuals HP 3000 Manuals
LOGTRAN
Makes the database calls needed to maintain the database log files and
optionally performs database transaction locking.
Syntax
LOGTRAN(modifier) base, log-message[,option-list];
LOGTRAN is used to define a static or dynamic logical transaction for
database transaction logging or locking purposes. If this verb is to be
used for database logging and recovery, several steps must first be
completed before the statement can be used. If this verb is to be used
for transaction locking, no preliminary steps need to be taken. See the
discussions of transaction logging in the TurboIMAGE reference manuals
for more information regarding static and dynamic transactions.
Transact file access verbs lock at the start of execution for a statement
and unlock before the next statement. Therefore, other processes can
modify the data during a logical transaction covered by LOGTRAN if the
transaction comprises more than one statement. It is therefore always
advisable to lock the transaction being logged.
If LOGTRAN is used for locking, it should be used consistently throughout
all programs, and databases and data sets should be locked and unlocked
in the same order by all programs. LOGTRAN locking should not be mixed
with Transact's automatic locking. Automatic locks should be disabled by
SET(OPTION) NOLOCK, and automatic error handling should be disabled by
specifying the STATUS option. Multiple LOGTRAN locks can only be issued
on different data sets in a database with an intervening LOGTRAN(END) or
LOGTRAN(XEND) verb on that database. See "Database and File Locking" in
Chapter 6 for more information.
Statement Parts
modifier Specifies the type of operation.
BEGIN Starts a static transaction and writes a record
to the log file if user logging is enabled.
Optionally, BEGIN locks the data sets specified
in SET(LIST). The LOCK option should be
specified unless the PROC statement is used for
locking.
The LOGTRAN(BEGIN) statement must always be
paired with a LOGTRAN(END) statement to mark the
beginning and end of a static transaction for a
given database. No other LOGTRAN(BEGIN) or
LOGTRAN(END) statement referencing the same
database access path can appear between a pair
of LOGTRAN(BEGIN) and LOGTRAN(END) statements.
MEMO Writes a log record in the log file to provide
more information about the logical transaction
if user logging is enabled.
END Ends a static transaction and writes a record to
the log file if user logging is enabled.
Unlocks the database locked by its corresponding
LOGTRAN(BEGIN) statement.
The LOGTRAN(END) statement must always be
preceded by a LOGTRAN(BEGIN) statement. No
other LOGTRAN(BEGIN) or LOGTRAN(END) statement
referencing the same database access path can
appear between a pair of LOGTRAN(BEGIN) and
LOGTRAN(END) statements.
_______________________________________________
NOTE The following modifiers, XBEGIN, XEND, and
XUNDO, apply to Transact/iX only. They
support the TurboIMAGE/XL dynamic
roll-back feature that provides MPE/iX
transaction management logging.
_______________________________________________
XBEGIN Starts a dynamic transaction and writes a record
to the log file if user logging is enabled.
Optionally, XBEGIN locks the data sets specified
in SETLIST. The lock option should be specified
unless the PROC statement is used for locking.
Nesting of dynamic or static transactions within
a dynamic transaction is not allowed when using
the same database access path. The
LOGTRAN(XBEGIN) statement must always be paired
with a LOGTRAN(XEND) statement to mark the
beginning and end of a dynamic transaction. No
other LOGTRAN(BEGIN), LOGTRAN(END),
LOGTRAN(XBEGIN), or LOGTRAN(XEND) statement
can appear between a matching pair of
LOGTRAN(XBEGIN) and LOGTRAN(XEND) statements for
a specific database access path.
XEND Ends a dynamic transaction and writes a record
to the log file if user logging is enabled.
Unlocks the database locked by its corresponding
LOGTRAN(XBEGIN) statement. The LOGTRAN(XEND)
statement must always be preceded by a
LOGTRAN(XBEGIN) statement to mark the beginning
and end of a dynamic transaction. No other
LOGTRAN(BEGIN), LOGTRAN(END), LOGTRAN(XBEGIN),
or LOGTRAN(XEND) statement can appear between a
matching pair of LOGTRAN(XBEGIN) or
LOGTRAN(XEND) statements for a specific database
access path. Also, LOGTRAN(XEND) cannot be
called after a call has been made to
LOGTRAN(XUNDO).
XUNDO Rolls back the modifications associated with a
dynamic transaction and writes a record to the
log file if user logging is enabled.
Unlocks the database locked by its corresponding
LOGTRAN(XBEGIN) statement.
The LOGTRAN(XUNDO) statement must always be
preceded by a LOGTRAN(XBEGIN) statement to mark
the beginning of a dynamic transaction.
LOGTRAN(XUNDO) cannot be called to roll back a
transaction started by a LOGTRAN(BEGIN)
statement. Also, LOGTRAN(XUNDO) cannot be
called after a call has been made to
LOGTRAN(XEND) for that specific database access
path.
base The database to be logged. It must be one of the following:
$HOME This special name indicates that the home
database is to be logged.
_______________________________________________
NOTE Using the actual home base name in the
LOGTRAN statement causes a compiler error.
_______________________________________________
base-name The name of the database to be logged (when the
database is other than the home base).
log- The log-message parameter is required for all LOGTRAN verbs.
message It must be one of the following:
(item-name The name of a data item that contains the
[(subscript)]) text string (up to 512 bytes long) to be
written to the log file. This item must
begin on a 16-bit word boundary. The
item-name can be subscripted if an array item
is being referenced. (See "Array
Subscripting" in Chapter 3.)
"message- The text string (up to 512 bytes long) to be
string" written on the log file.
option- One or more of the following, separated by commas.
list
LOCK(setlist) This option causes the data sets specified in
the setlist to be locked. This option is only
valid with the LOGTRAN(BEGIN) or LOGTRAN(XBEGIN)
statements, with the locks remaining in effect
until the corresponding LOGTRAN(END),
LOGTRAN(XEND) or LOGTRAN(XUNDO) is encountered.
The setlist is of the form:
(setname[cond][,setname[cond]...)
setname The name of the data set to be
locked. If the entire database is
to be locked the user can
substitute @ for setname.
cond The lock condition, either COND
for conditional lock or UNCOND for
unconditional locking. COND is
the default.
_______________________________________________
NOTE When locking multiple data sets, Multiple
Rin (MR) capability must be in effect.
You should also list data sets in the
order in which they appear in the database
for added compatibility with non-Transact
Applications. (See the TurboIMAGE/XL
Database Management System Reference
Manual for more information.)
_______________________________________________
NOMSG Suppresses the standard error message produced
as a result of a database error. It is
recommended that STATUS is used with this
option.
STATUS Suppresses the actions defined in Chapter 7
under "Automatic Error Handling." You will need
to add code to check the value of STATUS. When
STATUS is specified, the effect of a LOGTRAN
statement is described by the 32-bit integer
value in the status register:
Status Meaning
Register
Value
0 The LOGTRAN operation was
successful.
<> 0 This is the database error code.
(See the TurboIMAGE/XL Database
Management System Reference Manual.)
See "Using the STATUS Option" in Chapter 7 for
more information.
Examples
The first example begins a transaction and locks the entire PERSON
database conditionally.
LOGTRAN(BEGIN) PERSON, "BEGIN LOGGING DATABASE", LOCK(@);
This example begins a transaction, locks the data set NAME
unconditionally, and locks the data set ADDRESS unconditionally.
LOGTRAN(BEGIN) $HOME, (MSG), LOCK(NAME(UNCOND), ADDRESS(UNCOND));
This example begins a transaction and locks the home base conditionally.
LOGTRAN(BEGIN) $HOME, (MSG), LOCK(@(COND));
This example ends a transaction and unlocks any data sets in $HOME that
have been locked.
LOGTRAN(END) $HOME, (MSG);
This example begins a dynamic transaction and locks the entire home
database conditionally.
LOGTRAN(XBEGIN) $HOME, "BEGIN DYNAMIC TXN LOGGING", LOCK(@);
The next example begins a dynamic transaction for the PEOPLE database and
locks the NAME data set conditionally and the ADDRESS data set
unconditionally.
LOGTRAN(XBEGIN) PEOPLE, (MSG), LOCK(NAME, ADDRESS(UNCOND));
This example shows how to begin a dynamic transaction with programmer's
control of locking. This would be done if the Transact locking scheme
for LOGTRAN(XBEGIN) was not adequate.
SET(OPTION) NOLOCK;
LET (MODE) = 1;
:
:
:
PROC DBLOCK(BASE(CUSTOMERS),
SET(NAMES),
(MODE),
STATUS(DB));
MOVE (CSTATUS) = STATUS(DB);
IF (CSTATUS) <> 0 THEN
GO TO LOCK-ERROR;
LOGTRAN(XBEGIN) $HOME, (MSG);
This example ends a transaction and unlocks any data sets or database
locked by the corresponding LOGTRAN(XBEGIN).
LOGTRAN(XEND) $HOME, "END OF DYNAMIC TXN LOGGING";
The next example shows how to end a dynamic transaction with programmer's
control of locking. It assumes that the LOCK option on LOGTRAN(XBEGIN)
was NOT used.
SET(OPTION) NOLOCK;
LET (MODE) = 1;
:
:
:
LOGTRAN(XEND) $HOME, (MSG);
PROC DBUNLOCK(BASE(CUSTOMERS),
SET(NAMES),
(MODE),
STATUS(DB));
MOVE (CSTATUS) = STATUS(DB);
IF (CSTATUS) <> 0 THEN
GO TO UNLOCK-ERROR;
The next example shows how to end a dynamic transaction when the contents
of the logging buffer in memory should be written to disk (Mode 2 of
DBXEND). This would be used for critical transactions. It is assumed
that locks are held throughout the transaction and that unlocking is the
responsibility of the programmer.
NOTE The DBXEND call must precede the call to DBUNLOCK or TurboIMAGE
will return an error.
SET(OPTION) NOLOCK;
LET (MODE) = 2;
:
:
PROC DBUNLOCK(BASE(CUSTOMERS),
(MSG),
(MODE),
STATUS(DB),
(NUMBYTES));
MOVE (CSTATUS) = STATUS(DB);
IF (CSTATUS) <> 0 THEN
GO TO DBXEND-ERROR;
The last example rolls back a transaction that was previously started by
LOGTRAN(XBEGIN).
LOGTRAN(XUNDO) EMPLOYEES, (MSG);