1 – Before
Before=date-time
Specifies the ending time and date for transactions to be
extracted. Based on the Select qualifier, transactions that
committed or started prior to the specified Before date are
selected. Information changed due to transactions that committed
or started after the Before date is not included in the output.
2 – Continuous
Continuous
Nocontinuous
Causes the LogMiner process to attach to the database and begin
extracting records in "near-real" time. When the Continuous
qualifier is specified, the RMU Unload After_Journal command
extracts records from the online after-image journal files of the
database until it is stopped via an external source (for example,
Ctrl/y, STOP/ID, $FORCEX, or database shutdown).
A database must be explicitly enabled for the Continuous LogMiner
feature. To enable the Continuous LogMiner feature, use the RMU
Set Logminer command with the Enable and Continuous qualifiers;
to disable use of the Continuous LogMiner feature, use the RMU
Set Logminer command with the Enable and Nocontinuous qualifiers.
The output from the Continuous LogMiner process is a continuous
stream of information. The intended use of the Continuous
LogMiner feature is to write the changes into an OpenVMS
mailbox or pipe, or to call a user-supplied callback routine.
Writing output to a disk file is completely functional with the
Continuous LogMiner feature, however, no built-in functionality
exists to prevent the files from growing indefinitely.
It is important that the callback routine or processing of
the mailbox be very responsive. If the user-supplied callback
routine blocks, or if the mailbox is not being read fast enough
and fills, the RMU Unload After_Journal command will stall. The
Continuous LogMiner process prevents backing up the after-image
journal that it is currently extracting along with all subsequent
journals. If the Continuous LogMiner process is blocked from
executing for long enough, it is possible that all available
journals will fill and will not be backed up.
When a database is enabled for the Continuous LogMiner feature,
an AIJ "High Water" lock (AIJHWM) is utilized to help coordinate
and maintain the current .aij end-of-file location. The lock
value block for the AIJHWM lock contains the location of the
highest written .aij block. The RMU Unload After_Journal command
with the Continuous qualifier polls the AIJHWM lock to determine
if data has been written to the .aij file and to find the highest
written block. If a database is not enabled for the Continuous
LogMiner feature, there is no change in locking behavior; the
AIJHWM lock is not maintained and thus the Continuous qualifier
of the RMU Unload After_Journal command is not allowed.
In order to maintain the .aij end-of-file location lock,
processes that write to the after-image journal file must use
the lock to serialize writing to the journal. When the Continuous
LogMiner feature is not enabled, processes instead coordinate
allocating space in the after-image journal file and can write
to the file without holding a lock. The Continuous LogMiner
process requires that the AIJHWM lock be held during the .aij
I/O operation. In some cases, this can reduce overall throughput
to the .aij file as it serves to reduce multiple over-lapped I/O
write operations by multiple processes.
The Save_Metadata and Restore_Metadata qualifiers are
incompatible with the Continuous qualifier.
3 – Extend Size
Extend_size=integer
Specifies the file allocation and extension quantity for output
data files. The default extension size is 1000 blocks. Using a
larger value can help reduce output file fragmentation and can
improve performance when large amounts of data are extracted.
4 – Format
Format=options
If the Format qualifier is not specified, Oracle RMU outputs data
to a fixed-length binary flat file.
The format options are:
o Format=Binary
If you specify the Format=Binary option, Oracle RMU does not
perform any data conversion; data is output in a flat file
format with all data in the original binary state.
Output Fields describes the output fields and data types of an
output record in Binary format.
Table 19 Output Fields
Byte
Field Name Data Type LengthDescription
ACTION CHAR (1) 1 Indicates record state.
"M" indicates an insert or
modify action. "D" indicates a
delete action. "E" indicates
stream end-of-file (EOF)
when a callback routine is
being used. "P" indicates
a value from the command
line Parameter qualifier
when a callback routine is
being used (see Parameter
qualifier). "C" indicates
transaction commit information
when the Include=Action=Commit
qualifier is specified.
RELATION_ CHAR (31) 31 Table name. Space padded to 31
NAME characters.
RECORD_TYPE INTEGER 4 The Oracle Rdb internal
(Longword) relation identifier.
DATA_LEN SMALLINT 2 Length, in bytes, of the data
(Word) record content.
NBV_LEN SMALLINT 2 Length, in bits, of the null
(Word) bit vector content.
DBK BIGINT 8 Records logical database key.
(Quadword) The database key is a 3-field
structure containing a 16-
bit line number, a 32-bit
page number and a 16-bit area
number.
START_TAD DATE VMS 8 Date/time of the start of the
(Quadword) transaction.
COMMIT_TAD DATE VMS 8 Date/time of the commitment of
(Quadword) the transaction.
TSN BIGINT 8 Transaction sequence number of
(Quadword) the transaction that performed
the record operation.
RECORD_ SMALLINT 2 Record version.
VERSION (Word)
Record Data Varies Actual data record field
contents.
Record NBV BIT VECTOR Null bit vector. There is
(array of one bit for each field in the
bits) data record. If a bit value
is 1, the corresponding field
is NULL; if a bit value is
0, the corresponding field
is not NULL and contains an
actual data value. The null
bit vector begins on a byte
boundary. Any extra bits in
the final byte of the vector
after the final null bit are
unused.
o Format=Dump
If you specify the Format=Dump option, Oracle RMU produces an
output format suitable for viewing. Each line of Dump format
output contains the column name (including LogMiner prefix
columns) and up to 200 bytes of the column data. Unprintable
characters are replaced with periods (.), and numbers and
dates are converted to text. NULL columns are indicated
with the string "NULL". This format is intended to assist
in debugging; the actual output contents and formatting will
change in the future.
o Format=Text
If you specify the Format=Text option, Oracle RMU converts
all data to printable text in fixed-length columns before
unloading it. VARCHAR(n) strings are padded with blanks when
the specified string has fewer characters than n so that the
resulting string is n characters long.
o Format=(Delimited_Text [,delimiter-options])
If you specify the Format=Delimited_Text option, Oracle RMU
applies delimiters to all data before unloading it.
DATE VMS dates are output in the collatable time format, which
is yyyymmddhhmmsscc. For example, March 20, 1993 is output as:
1993032000000000.
Delimiter options are:
- Prefix=string
Specifies a prefix string that begins any column value in
the ASCII output file. If you omit this option, the column
prefix is a quotation mark (").
- Separator=string
Specifies a string that separates column values of a row.
If you omit this option, the column separator is a single
comma (,).
- Suffix=string
Specifies a suffix string that ends any column value in
the ASCII output file. If you omit this option, the column
suffix is a quotation mark (").
- Terminator=string
Specifies the row terminator that completes all the column
values corresponding to a row. If you omit this option, the
row terminator is the end of the line.
- Null=string
Specifies a string that, when found in the database column,
is unloaded as "NULL" in the output file.
The Null option can be specified on the command line as any
one of the following:
* A quoted string
* An empty set of double quotes ("")
* No string
The string that represents the null character must be
quoted on the Oracle RMU command line. You cannot specify a
blank space or spaces as the null character. You cannot use
the same character for the Null value and other Delimited_
Text options.
NOTE
The values for each of the strings specified in the
delimiter options must be enclosed within quotation
marks. Oracle RMU strips these quotation marks while
interpreting the values. If you want to specify a
quotation mark (") as a delimiter, specify a string
of four quotation marks. Oracle RMU interprets four
quotation marks as your request to use one quotation
mark as a delimiter. For example, Suffix = """".
Oracle RMU reads these quotation marks as follows:
o The first quotation mark is stripped from the string.
o The second and third quotation mark are interpreted
as your request for one quotation mark (") as a
delimiter.
o The fourth quotation mark is stripped.
This results in one quotation mark being used as a
delimiter.
Furthermore, if you want to specify a quotation mark as
part of the delimited string, you must use two quotation
marks for each quotation mark that you want to appear in
the string. For example, Suffix = "**""**" causes Oracle
RMU to use a delimiter of **"**.
5 – Ignore
Ignore=Old_Version[=table-list]
Specifies optional conditions or items to ignore.
The RMU Unload After_Journal command treats non-current record
versions in the AIJ file as a fatal error condition. That is,
attempting to extract a record that has a record version not the
same as the table's current maximum version results in a fatal
error.
There are, however, some very rare cases where a verb rollback
of a modification of a record may result in an old version of a
record being written to the after-image journal even though the
transaction did not actually complete a successful modification
to the record. The RMU Unload After_Journal command detects the
old record version and aborts with a fatal error in this unlikely
case.
When the Ignore=Old_Version qualifier is present, the RMU Unload
After_Journal command displays a warning message for each
record that has a non-current record version and the record
is not written to the output stream. The Old_Version qualifier
accepts an optional list of table names to indicate that only the
specified tables are permitted to have non-current record version
errors ignored.
6 – Include
Include=Action=include-type
Specifies if deleted or modified records or transaction commit
information is to be extracted from the after-image journal. The
following keywords can be specified:
o Commit
NoCommit
If you specify Commit, a transaction commit record is
written to each output stream as the final record for each
transaction. The commit information record is written to
output streams after all other records for the transaction
have been written. The default is NoCommit.
Because output streams are created with a default file name
of the table being extracted, it is important to specify a
unique file name on each occurrence of the output stream.
The definition of "unique" is such that when you write to a
non-file-oriented output device (such as a pipe or mailbox),
you must be certain to specify a specific file name on each
output destination. This means that rather than specifying
Output=MBA1234: for each output stream, you should use
Output=MBA1234:MBX, or any file name that is the same on all
occurrences of MBA1234:.
Failure to use a specific file name can result in additional,
and unexpected, commit records being returned. However, this
is generally a restriction only when using a stream-oriented
output device (as opposed to a disk file).
The binary record format is based on the standard LogMiner
output format. However, some fields are not used in the commit
action record. The binary format and contents of this record
are shown in Commit Record Contents. This record type is
written for all output data formats.
Table 20 Commit Record Contents
Length (in
Field bytes) Contents
ACTION 1 "C"
RELATION 31 Zero
RECORD_TYPE 4 Zero
DATA_LEN 2 Length of RM_TID_LEN, AERCP_LEN, RM_
TID, AERCP
NBV_LEN 2 Zero
TID 4 Transaction (Attach) ID
PID 4 Process ID
START_TAD 8 Transaction Start Time/Date
COMMIT_TAD 8 Transaction Commit Time/Date
TSN 8 Transaction ID
RM_TID_LEN 4 Length of the Global TID
AERCP_LEN 4 Length of the AERCP information
RM_TID RM_TID_LEN Global TID
AERCP AERCP_LEN Restart Control Information
RDB$LM_ 12 USERNAME
USERNAME
When the original transaction took part in a distributed,
two-phase transaction, the RM_TID component is the Global
transaction manager (XA or DDTM) unique transaction ID.
Otherwise, this field contains binary zeroes.
The AIJ Extract Recovery Control Point (AERCP) information is
used to uniquely identify this transaction within the scope
of the database and after-image journal files. It contains
the .aij sequence number, VBN and TSN of the last "Micro Quiet
Point", and is used by the Continuous LogMiner process to
restart a particular point in the journal sequence.
o Delete
NoDelete
If you specify Delete, pre-deletion record contents are
extracted from the aij file. If you specify NoDelete, no
pre-deletion record contents are extracted. The default is
Delete.
o Modify
NoModify
If you specify Modify, modified or added record contents are
extracted from the .aij file. If you specify NoModify, then no
modified or added record contents are extracted. The default
is Modify.
7 – IO Buffers
IO_Buffers=integer
Specifies the number of I/O buffers used for output data files.
The default number of buffers is two, which is generally
adequate. With sufficiently fast I/O subsystem hardware,
additional buffers may improve performance. However, using a
larger number of buffers will also consume additional virtual
memory and process working set.
8 – Log
Log
Nolog
Specifies that the extraction of the .aij file is be reported
to SYS$OUTPUT or the destination specified with the Output
qualifier. When activity is logged, the output from the Log
qualifier provides the number of transactions committed or rolled
back. The default is the setting of the DCL VERIFY flag, which is
controlled by the DCL SET VERIFY command.
9 – Options
Options=options-list
The following options can be specified:
o File=file-spec
An options file contains a list of tables and output
destinations. The options file can be used instead of, or
along with, the Table qualifier to specify the tables to be
extracted. Each line of the options file must specify a table
name prefixed with "Table=". After the table name, the output
destination is specified as either "Output=", or "Callback_
Module=" and "Callback_Routine=", for example:
TABLE=tblname,OUTPUT=outfile
TABLE=tblname,CALLBACK_MODULE=image,CALLBACK_ROUTINE=routine
You can use the Record_Definition=file-spec option from the
Table qualifier to create a record definition file for the
output data. The default file type is .rrd; the default file
name is the name of the table.
You can use the Table_Definition=file-spec option from
the Table qualifier to create a file that contains an SQL
statement that creates a table to hold transaction data. The
default file type is .sql; the default file name is the name
of the table.
Each option in the Options=File qualifier must be fully
specified (no abbreviations are allowed) and followed with
an equal sign (=) and a value string. The value string must
be followed by a comma or the end of a line. Continuation
lines can be specified by using a trailing dash. Comments are
indicated by using the exclamation point (!) character.
You can use the asterisk (*) and the percent sign (%)
wildcard characters in the table name specification to select
all tables that satisfy the components you specify. The
asterisk matches zero or more characters; the percent sign
matches a single character.
For table name specifications that contain wild card
characters, if the first character of the string is a pound
sign (#), the wildcard specification is changed to a "not
matching" comparison. This allows exclusion of tables based
on a wildcard specification. The pound sign designation is
only evaluated when the table name specification contains an
asterisk or percent sign.
For example, a table name specification of "#FOO%" indicates
that all table names that are four characters long and do not
start with the string "FOO" are to be selected.
o Shared_Read
Specifies that the input after-image journal backup files are
to be opened with an RMS shared locking specification.
o Dump
Specifies that the contents of an input metadata file are to
be formatted and displayed. Typically, this information is
used as a debugging tool.
10 – Order AIJ Files
Order_AIJ_Files
NoOrder_AIJ_Files
By default, after-image journal files are processed in the order
that they are presented to the RMU Unload After_Journal command.
The Order_AIJ_Files qualifier specifies that the input after-
image journal files are to be processed in increasing order by
sequence number. This can be of benefit when you use wildcard (*
or %) processing of a number of input files. The .aij files are
each opened, the first block is read (to determine the sequence
number), and the files are closed prior to the sorting operation.
11 – Output
Output=file-spec
Redirects the log and trace output (selected with the Log and
Trace qualifiers) to the named file. If this qualifier is not
specified, the output generated by the Log and Trace qualifiers,
which can be voluminous, is displayed to SYS$OUTPUT.
12 – Parameter
Parameter=character-strings
Specifies one or more character strings that are concatenated
together and passed to the callback routine upon startup.
For each table that is associated with a user-supplied callback
routine, the callback routine is called with two parameters: the
length of the Parameter record and a pointer to the Parameter
record. The binary format and contents of this record are shown
in Parameter Record Contents.
Table 21 Parameter Record Contents
Length (in
Field bytes) Contents
ACTION 1 "P"
RELATION 31 Relation name
RECORD_TYPE 4 Zero
DATA_LEN 2 Length of parameter string
NBV_LEN 2 Zero
LDBK 8 Zero
START_TAD 8 Zero
COMMIT_TAD 8 Zero
TSN 8 Zero
DATA ? Variable length parameter string
content
13 – Quick Sort Limit
Quick_Sort_Limit=integer
Specifies the maximum number of records that will be sorted with
the in-memory "quick sort" algorithm.
The default value is 5000 records. The minimum value that can be
specified is 10 and the maximum value is 100,000.
Larger values specified for the /Quick_Sort_Limit qualifier may
reduce sort work file IO at the expense of additional CPU time
and/or memory consumption. A value that is too small may result
in additional disk file IO. In general, the default value should
be accepted.
14 – Restart
Restart=restart-point
Specifies an AIJ Extract Restart Control Point (AERCP) that
indicates the location to begin the extraction. The AERCP
indicates the transaction sequence number (TSN) of the last
extracted transaction along with a location in the .aij file
where a known "Micro-quiet point" exists.
When the Restart qualifier is not specified and no input after-
image journal files are specified on the command line, the
Continuous LogMiner process starts extracting at the beginning
of the earliest modified online after-image journal file.
When formatted for text display, the AERCP structure consists of
the six fields (the MBZ field is excluded) displayed as unsigned
integers separated by dashes; for example, "1-28-12-7-3202-3202".
15 – Restore Metadata
Restore_Metadata=file-spec
Specifies that the RMU Unload After_Journal command is to read
database metadata information from the specified file. The
Database parameter is required but the database itself is not
accessed when the Restore_Metadata qualifier is specified. The
default file type is .metadata. The Continuous qualifier is not
allowed when the Restore_Metadata qualifier is present.
Because the database is not available when the Restore_Metadata
qualifier is specified, certain database-specific actions cannot
be taken. For example, checks for after-image journaling are
disabled. Because the static copy of the metadata information is
not updated as database structure and table changes are made, it
is important to make sure that the metadata file is saved after
database DML operations.
When the Restore_Metadata qualifier is specified, additional
checks are made to ensure that the after-image journal files
were created using the same database that was used to create the
metadata file. These checks provide additional security and help
prevent accidental mismatching of files.
16 – Save Metadata
Save_Metadata=file-spec
Specifies that the RMU Unload After_Journal command is to
write metadata information to the named file. The Continuous,
Restore_Metadata, Table, and Options=file qualifiers and the
aij-file-name parameter are not allowed when the Save_Metadata
qualifier is present. The default file type is .metadata.
17 – Select
Select=selection-type
Specifies if the date and time of the Before and Since qualifiers
refer to transaction start time or transaction commit time.
The following options can be specified as the selection-type of
the Select qualifier:
o Commit_Transaction
Specifies that the Before and Since qualifiers select
transactions based on the time of the transaction commit.
o Start_Transaction
Specifies that the Before and Since qualifiers select
transactions based on the time of the transaction start.
The default for date selection is Commit_Transaction.
18 – Since
Since=date-time
Specifies the starting time for transactions to be extracted.
Depending on the value specified in the Select qualifier,
transactions that committed or started on or after the specified
Since date are selected. Information from transactions that
committed or started prior to the specified Since date is not
included in the output.
19 – Sort Workfiles
Sort_Workfiles=integer
Specifies the number of sort work files. The default number
of sort work files is two. When large transactions are being
extracted, using additional sort work files may improve
performance by distributing I/O loads over multiple disk devices.
Use the SORTWORKn (where n is a number from 0 to 9) logical names
to specify the location of the sort work files.
20 – Statistics Interval
Statistics_Interval=integer
Specifies that statistics are to be displayed at regular
intervals so that you can evaluate the progress of the unload
operation.
The displayed statistics include:
o Elapsed time
o CPU time
o Buffered I/O
o Direct I/O
o Page faults
o Number of records unloaded for a table
o Total number of records extracted for all tables
If the Statistics_Interval qualifier is specified, the default
interval is 60 seconds. The minimum value is one second. If the
unload operation completes successfully before the first time
interval has passed, you will receive an informational message
on the number of files unloaded. If the unload operation is
unsuccessful before the first time interval has passed, you will
receive error messages and statistics on the number of records
unloaded.
At any time during the unload operation, you can press Ctrl/T to
display the current statistics.
21 – Symbols
Symbols
Nosymbols
Specifies whether DCL symbols are to be created, indicating
information about records extracted for each table.
If a large enough number of tables is being unloaded, too many
associated symbols are created, and the CLI symbol table space
can become exhausted. The error message "LIB-F-INSCLIMEM,
insufficient CLI memory" is returned in this case. Specify the
Nosymbols qualifier to prevent creation of the symbols.
The default is Symbols, which causes the symbols to be created.
22 – Table
Table=(Name=table-name, table-options)
Specifies the name of a table to be unloaded and an output
destination. The table-name must be a table within the database.
Views, indexes, and system relations may not be unloaded from the
after-image journal file.
The asterisk (*) and the percent sign (%) wildcard characters
can be used in the table name specification to select all tables
that satisfy the components you specify. The asterisk matches
zero or more characters and the percent sign matches a single
character.
For table name specifications that contain wild card characters,
if the first character of the string is a pound sign (#),
the wildcard specification is changed to a "not matching"
comparison. This allows exclusion of tables based on a wildcard
specification. The pound sign designation is only evaluated when
the table name specification contains an asterisk or percent
sign.
For exmple, a table name specification of "#FOO%" indicates that
all table names that are four characters long and do not start
with the string "FOO" are to be selected.
The following table-options can be specified with the Table
qualifier:
o Callback_Module=image-name, Callback_Routine=routine-name
The LogMiner process uses the OpenVMS library routine
LIB$FIND_IMAGE_SYMBOL to activate the specified shareable
image and locate the specified entry point routine name. This
routine is called with each extracted record. A final call is
made with the Action field set to "E" to indicate the end of
the output stream. These options must be specified together.
o Control
Use the Control table option to produce output files that
can be used by SQL*Loader to load the extracted data into an
Oracle database. This option must be used in conjunction with
fixed text format for the data file. The Control table option
can be specified on either the command line or in an options
file.
o Output=file-spec
If an Output file specification is present, unloaded records
are written to the specified location.
o Record_Definition=file-spec
The Record_Definition=file-spec option can be used to create a
record definition file for the output data. The default file
type is .rrd; the default file name is the name of the table.
o Table_Definition=file-spec
You can use the Table_Definition=file-spec option to create
a file that contains an SQL statement that creates a table
to hold transaction data. The default file type is .sql; the
default file name is the name of the table.
Unlike other qualifiers where only the final occurrence of the
qualifier is used by an application, the Table qualifier can
be specified multiple times for the RMU Unload After_Journal
command. Each occurrence of the Table qualifier must specify a
different table.
23 – Trace
Trace
Notrace
Specifies that the unloading of the .aij file be traced. The
default is Notrace. When the unload operation is traced, the
output from the Trace qualifier identifies transactions in the
.aij file by TSNs and describes what Oracle RMU did with each
transaction during the unload process. You can specify the Log
qualifier with the Trace qualifier.