The transaction identifier (txid) groups operations into transactions as they are written to the Oracle GoldenGate trail file. The Oracle GoldenGate message capture adapter supports only contiguous, non-interleaved transactions. The transaction identifier can be any unique value that increases for each transaction. A system generated value can generally be used.

The sequence identifier (seqid) identifies each operation internally. This can be used during recovery processing to identify operations that have already been written to the Oracle GoldenGate trail. The sequence identifier can be any unique value that increases for each operation. The length should be fixed.

The JMS Message ID can be used as a sequence identifier if the message identifier for that provider increases and is unique. However, there are cases (for example, using clustering, failed transactions) where JMS does not guarantee message order or when the ID may be unique but not be increasing. The system generated Sequence ID can be used, but it can cause duplicate messages under some recovery situations. The recommended approach is to have the JMS client that adds messages to the queue set the Message ID, a header property, or some data element to an application-generated unique value that is increasing.

The timestamp (timestamp) is used as the commit timestamp of operations within the Oracle GoldenGate trail. It should be increasing but this is not required, and it does not have to be unique between transactions or operations. It can be any date format that can be parsed.

The table name is used to identify the logical table to which the column data belongs. The adapter requires a two part table name in the form SCHEMA_NAME.TABLE_NAME. This can either be defined separately (schema and table) or as a combination of schema and table (schemaandtable).

A single field may contain both schema and table name, they may be in separate fields, or the schema may be included in the software code so only the table name is required. How the schema and table names can be specified depends on the parser. In any case the two part logical table name is used to write records in the Oracle GoldenGate trail and to generate the source definitions file that describes the trail.

The operation type (optype) is used to determine whether an operation is an insert, update or delete when written to the Oracle GoldenGate trail. The operation type value for any specific operation is matched against the values defined for each operation type.

The data written to the Oracle GoldenGate trail for each operation type depends on the Extract configuration:

• Inserts

  • The after values of all columns are written to the trail.

• Updates

  • Default – The after values of keys are written. The after values of columns that have changed are written if the before values are present and can be compared. If before values are not present then all columns are written.

  • NOCOMPRESSUPDATES – The after values of all columns are written to the trail.

  • GETUPDATEBEFORES – The before and after values of columns that have changed are written to the trail if the before values are present and can be compared. If before values are not present only after values are written.

  • If both NOCOMPRESSUPDATES and GETUPDATEBEFORES are included, the before and after values of all columns are written to the trail if before values are present

• Deletes

  • Default – The before values of all keys are written to the trail.

  • NOCOMPRESSDELETES – The before values of all columns are written to the trail.

Primary key update operations may also be generated if the before values of keys are present and do not match the after values.

All parsers retrieve column data from the message text and write it to the Oracle GoldenGate trail. In some cases the columns are read in index order as defined by the source definitions, in other cases they are accessed by name.

Depending on the configuration and original message text, both before and after or only after images of the column data may be available. For updates, the data for non-updated columns may or may not be available.

All column data is retrieved as text. It is converted internally into the correct data type for that column based on the source definitions. Any conversion problem will result in an error and the process will abend.

The relationship of transactions to messages can be:

• One transaction per message

  This is determined automatically by the scope of the message.

• Multiple transactions per message

  This is determined by the transaction indicator (txind). If there is no transaction indicator, the XML parser can create transactions based on a matching transaction rule.

• Multiple messages per transaction

  The transaction indicator (txind) is required to specify whether the operation is the beginning, middle, end or the whole transaction. The transaction indicator value for any specific operation is matched against the values defined for each transaction indicator type. A transaction is started if the indicator value is beginning or whole, continued if it is middle, and ended if it is end or whole.

The transaction name (txname) is optional data that can be used to associate an arbitrary name to a transaction. This can be added to the trail as a token using a GETENV function.

The transaction owner (txowner) is optional data that can be used to associate an arbitrary user name to a transaction. This can be added to the trail as a token using a GETENV function, or used to exclude certain transactions from processing using the EXCLUDEUSER Extract parameter.

More than one field can be used for a table name. For example, you can define the logical schema name through a static property such as:

fixed.schema=MYSCHEMA

You can then add a property that defines the data record as multiple fields from the copybook header definition.

A timestamp is parsed using the default format YYYY-MM-DD HH:MM:SS.FFF, with FFF depending on the size of the field.

Specify different incoming formats by entering a comment before the datetime field as shown in the next example.

The following properties determine the parsing rules for delimiting the record.

• fielddelim specifies one or more ASCII or hexadecimal characters as the value for the field delimiter

• recorddelim specifies one or more ASCII or hexadecimal characters as the value for the record delimiter

• quote specifies one or more ASCII or hexadecimal characters to use for quoted values

• nullindicator specifies one or more ASCII or hexadecimal characters to use for NULL values

You can define escape characters for the delimiters so they will be replaced if the characters are found in the text. For example if a backslash and apostrophe (\') are specified, then the input "They used Mike\'s truck" is translated to "They used Mike's truck". Or if two quotes ("") are specified, "They call him ""Big Al""" is translated to "They call him "Big Al"".

Data values may be present in the record without quotes, but the system only removes escape characters within quoted values. A non-quoted string that matches a null indicator is treated as null.

The following properties provide more information:

• hasbefores indicates before values are present for each record

• hasnames indicates column names are present for each record

• afterfirst indicates column after values come before column before values

• isgrouped indicates all column names, before values and after values are grouped together in three blocks, rather than alternately per column

The default format YYYY-DD-MM HH:MM:SS.FFF is used to parse dates. You can use properties to override this on a global, table or column level. Examples of changing the format are shown below.

delim.dateformat.default=MM/DD/YYYY-HH:MM:SS
delim.dateformat.MY.TABLE=DD/MMM/YYYY
delim.dateformat.MY.TABLE.COL1=MMYYYY

Specifies the type of logging that is to be used. The default implementation is the JDK option. This is the built-in Java logging called java.util.logging (JUL). The other logging options are log4j or logback. The syntax is:

gg.log={JDK|log4j|logback}

For example, to set the type of logging to log4j:

gg.log=log4j 

The log file is created in the report subdirectory of the installation. The default log file name includes the group name of the associated Extract and the file extension is log.

Specifies the overall log level for all modules. The syntax is:

gg.log.level={ERROR|WARN|INFO|DEBUG}

The log levels are defined as follows:

• ERROR – Only write messages if errors occur

• WARN – Write error and warning messages

• INFO – Write error, warning and informational messages

• DEBUG – Write all messages, including debug ones.

The default logging level is INFO. The messages in this case will be produced on startup, shutdown and periodically during operation. If the level is switched to DEBUG, large volumes of messages may occur which could impact performance. For example, the following sets the global logging level to INFO:

# global logging level
gg.log.level=INFO

Specifies the path to the log file. The syntax is:

gg.log.file=path_to_file

Where the path_to_file is the fully defined location of the log file. This allows a change to the name of the log, but you must include the Replicat name if you have more than one Replicat to avoid one overwriting the log of the other.

Specifies the classpath to the JARs used to implement logging.

gg.log.classpath=path_to_jars

Specifies the classpath and boot options that will be applied when the JVM starts up. The path needs colon (:) separators for UNIX/Linux and semicolons (;) for Windows.

The syntax is:

jvm.bootoptions=option[, option][. . .]

The options are the same as those passed to Java executed from the command line. They may include classpath, system properties, and JVM memory options (such as maximum memory or initial memory) that are valid for the version of Java being used. Valid options may vary based on the JVM version and provider.

For example (all on a single line):

jvm.bootoptions= -Djava.class.path=ggjava/ggjava.jar
-Dlog4j.configuration=my-log4j.properties

The log4j.configuration property could be a fully qualified URL to a log4j properties file; by default this file is searched for in the classpath. You may use your own log4j configuration, or one of the pre-configured log4j settings: log4j.properties (default level of logging), debug-log4j.properties (debug logging) or trace-log4j.properties (very verbose logging).

Specifies where the JMS report is written. The syntax is:

jms.report.output={report|log|both}

Where:

• report sends the JMS report to the Oracle GoldenGate report file. This is the default.

• log will write to the Java log file (if one is configured)

• both will send to both locations.

Specifies the frequency of report generation based on time.

jms.report.time=time_specification

The following examples write a report every 30 seconds, 45 minutes and eight hours.

jms.report.time=30sec
jms.report.time=45min
jms.report.time=8hr

Specifies the frequency of report generation based on number of records. The syntax is:

jms.report.records=number

The following example writes a report every 1000 records.

jms.report.records=1000

Specifies that a unique identifier with the indicated format is passed back from the JMS integration to the message capture VAM. This may be used by the VAM as a unique sequence ID for records.

jms.id={ogg|time|wmq|activemq|message_header|custom_java_class}

Where:

• ogg - returns the message header property GG_ID which is set by Oracle GoldenGate JMS delivery.

• time - uses a system timestamp as a starting point for the message ID

• wmq - reformats a WebSphere MQ Message ID for use with the VAM

• activemq - reformats an ActiveMQ Message ID for use with the VAM

• message_header - specifies your customized JMS message header to be included, such as JMSMessageID, JMSCorrelationID, or JMSTimestamp.

• custom_java_class - specifies a custom Java class that creates a string to be used as an ID.

For example:

jms.id=time
jms.id=JMSMessageID

The ID returned must be unique, incrementing, and fixed-width. If there are duplicate numbers, the duplicates are skipped. If the message ID changes length, the Extract process will abend.

Specifies the queue or topic name to be looked up using JNDI.

jms.destination=jndi_name

For example:

jms.destination=sampleQ

Specifies the connection factory name to be looked up using JNDI.

jms.connectionFactory=jndi_name

For example

jms.connectionFactory=ConnectionFactory

Sets the user name and password of the JMS connection, as specified by the JMS provider.

jms.user=user_name
jms.password=password

This is not used for JNDI security. To set JNDI authentication, see the JNDI java.naming.security properties.

For example:

jms.user=myuser
jms.password=mypasswd

Specifies the parser to use.

parser.type={fixed|delim|xml}

Where:

• fixed invokes the fixed width parser

• delim invokes the delimited parser

• xml invokes the XML parser

For example:

parser.type=delim

Specifies the type of file used as metadata for message capture. The two valid options are sourcedefs and copybook.

fixed.schematype={sourcedefs|copybook}

For example:

fixed.schematype=copybook

The value of this property determines the other properties that must be set in order to successfully parse the incoming data.

If the fixed.schematype=sourcedefs, this property specifies the location of the source definitions file that is to be used.

fixed.sourcedefs=file_location

For example:

fixed.sourcedefs=dirdef/hrdemo.def

If the fixed.schematype=copybook, this property specifies the location of the copybook file to be used by the message capture process.

fixed.copybook=file_location

For example:

fixed.copybook=test_copy_book.cpy

Specifies the name of the sourcedefs entry or copybook record that contains header information used to determine the data block structure:

fixed.header=record_name

For example:

fixed.header=HEADER

Specifies the name of the header field, JMS property, or system value that contains the seqid used to uniquely identify individual records. This value must be continually incrementing and the last character must be the least significant.

fixed.seqid={field_name|$jms_property|*seqid}

Where:

• field_name indicates the name of a header field containing the seqid

• jms_property uses the value of the specified JMS header property. A special value of this is $jmsid which uses the value returned by the mechanism chosen by the jms.id property

• seqid indicates a simple incrementing 64-bit integer generated by the system

For example:

fixed.seqid=$jmsid

Specifies the name of the field, JMS property, or system value that contains the timestamp.

fixed.timestamp={field_name|$jms_property|*ts}

For example:

fixed.timestamp=TIMESTAMP
fixed.timestamp=$JMSTimeStamp
fixed.timestamp=*ts

Specifies the format of the timestamp field.

fixed.timestamp.format=format

Where the format can include punctuation characters plus:

• YYYY – four digit year

• YY – two digit year

• M[M] – one or two digit month

• D[D] – one or two digit day

• HH – hours in twenty four hour notation

• MI – minutes

• SS – seconds

• Fn – n number of fractions

The default format is "YYYY-MM-DD:HH:MI:SS.FFF"

For example:

fixed.timestamp.format=YYYY-MM-DD-HH.MI.SS

Specifies the name of the field, JMS property, or system value that contains the txid used to uniquely identify transactions. This value must increment for each transaction.

fixed.txid={field_name|$jms_property|*txid}

For most cases using the system value of *txid is preferred.

For example:

fixed.txid=$JMSTxId
fixed.txid=*txid

Specifies the name of the field, JMS property, or static value that contains a user name associated with a transaction. This value may be used to exclude certain transactions from processing. This is an optional property.

fixed.txowner={field_name|$jms_property|"value"}

For example:

fixed.txowner=$MessageOwner
fixed.txowner="jsmith"

Specifies the name of the field, JMS property, or static value that contains an arbitrary name to be associated with a transaction. This is an optional property.

fixed.txname={field_name|$jms_property|"value"}

For example:

fixed.txname="fixedtx"

Specifies the name of the field, or JMS property that contains the operation type, which is validated against the fixed.optype values specified in the next sections.

fixed.header.optype={field_name|$jms_property}

For example:

fixed.header.optype=FUNCTION

This value identifies an insert operation. The default is I.

fixed.optype.insertval={value|\xhex_value}

For example:

fixed.optype.insertval=A

This value identifies an update operation. The default is U.

fixed.optype.updateval={value|\xhex_value}

For example:

fixed.optype.updateval=M

This value identifies a delete operation.The default is D.

fixed.optype.deleteval={value|\xhex_value}

For example:

fixed.optype.deleteval=R

Specifies the name of the table. This enables the parser to find the data record definition needed to translate the non-header data portion.

fixed.table=field_name|$jms_property[, . . .]

More than one comma delimited field name may be used to determine the name of the table Each field name corresponds to a field in the header record defined by the fixed.header property or JMS property. The values of these fields are concatenated to identify the data record.

For example:

fixed.table=$JMSTableName
fixed.table=SOURCE_Db,SOURCE_Db_Rec_Version

Specifies the static name of the schema when generating SCHEMA.TABLE table names.

fixed.schema="value"

For example:

fixed.schema="OGG"

Specifies the name of the field or JMS property that contains a transaction indicator that is validated against the transaction indicator values. If this is not defined, all operations within a single message will be seen to have occurred within a whole transaction. If defined, then it determines the beginning, middle and end of transactions. Transactions defined in this way can span messages. This is an optional property.

fixed.txind={field_name|$jms_property}

For example:

fixed.txind=$TX_IND

This value identifies an operation as the beginning of a transaction. The defaults is B.

fixed.txind.beginval={value|\xhex_value}

For example:

fixed.txind.beginval=0

This value identifies an operation as the middle of a transaction. The default is M.

fixed.txind.middleval={value|\xhex_value}

For example:

fixed.txind.middleval=1

This value identifies an operation as the end of a transaction. The default is E.

fixed.txind.endval={value|\xhex_value}

For example:

fixed.txind.endval=2

This value identifies an operation as a whole transaction. The default is W.

fixed.txind.wholeval={value|\xhex_value}

For example:

fixed.txind.wholeval=3

Specifies the location of the source definitions file to use.

delim.sourcedefs=file_location

For example:

delim.sourcedefs=dirdef/hrdemo.def

Specifies the list of values that come before the data and assigns names to each.

delim.header=name[,name2][. . .]

The names must be unique. They can be referenced in other delim properties or wherever header fields can be used.

For example:

delim.header=optype, tablename, ts
delim.timestamp=ts

Specifies the name of the header field, JMS property, or system value that contains the seqid used to uniquely identify individual records. This value must increment and the last character must be the least significant.

delim.seqid={field_name|$jms_property|*seqid}

Where:

• field_name indicates the name of a header field containing the seqid

• jms_property uses the value of the specified JMS header property, a special value of this is $jmsid which uses the value returned by the mechanism chosen by the jms.id property

• seqid indicates a simple continually incrementing 64-bit integer generated by the system

For example:

delim.seqid=$jmsid

Specifies the name of the JMS property, header field, or system value that contains the timestamp.

delim.timestamp={field_name|$jms_property|*ts}

For example:

delim.timestamp=TIMESTAMP
delim.timestamp=$JMSTimeStamp
delim.timestamp=*ts

Specifies the format of the timestamp field.

delim.timestamp.format=format

Where the format can include punctuation characters plus:

• YYYY – four digit year

• YY – two digit year

• M[M] – one or two digit month

• D[D] – one or two digit day

• HH – hours in twenty four hour notation

• MI – minutes

• SS – seconds

• Fn – n number of fractions

The default format is "YYYY-MM-DD:HH:MI:SS.FFF"

For example:

delim.timestamp.format=YYYY-MM-DD-HH.MI.SS

Specifies the name of the JMS property, header field, or system value that contains the txid used to uniquely identify transactions. This value must increment for each transaction.

delim.txid={field_name|$jms_property|*txid}

For most cases using the system value of *txid is preferred.

For example:

delim.txid=$JMSTxId
delim.txid=*txid

Specifies the name of the JMS property, header field, or static value that contains an arbitrary user name associated with a transaction. This value may be used to exclude certain transactions from processing. This is an optional property.

delim.txowner={field_name|$jms_property|"value"}

For example:

delim.txowner=$MessageOwner
delim.txowner="jsmith"

Specifies the name of the JMS property, header field, or static value that contains an arbitrary name to be associated with a transaction. This is an optional property.

delim.txname={field_name|$jms_property|"value"}

For example:

delim.txname="fixedtx"

Specifies the name of the JMS property or header field that contains the operation type. This is compared to the values for delim.optype.insertval, delim.optype.updateval and delim.optype.deleteval to determine the operation.

delim.optype={field_name|$jms_property}

For example:

delim.optype=optype

This value identifies an insert operation. The default is I.

delim.optype.insertval={value|\xhex_value}

For example:

delim.optype.insertval=A

This value identifies an update operation. The default is U.

delim.optype.updateval={value|\xhex_value}

For example:

delim.optype.updateval=M

This value identifies a delete operation. The default is D.

delim.optype.deleteval={value|\xhex_value}

For example:

delim.optype.deleteval=R

Specifies the name of the JMS property or header field that contains the schema and table name in the form SCHEMA.TABLE.

delim.schemaandtable={field_name|$jms_property}

For example:

delim.schemaandtable=$FullTableName

Specifies the name of the JMS property, header field, or hard-coded value that contains the schema name.

delim.schema={field_name|$jms_property|"value"}

For example:

delim.schema="OGG"

Specifies the name of the JMS property or header field that contains the table name.

delim.table={field_name|$jms_property}

For example:

delim.table=TABLE_NAME

Specifies the name of the JMS property or header field that contains the transaction indicator to be validated against beginval, middleval, endval or wholeval. All operations within a single message will be seen as within one transaction if this property is not set. If it is set it determines the beginning, middle and end of transactions. Transactions defined in this way can span messages. This is an optional property.

delim.txind={field_name|$jms_property}

For example:

delim.txind=txind

The value that identifies an operation as the beginning of a transaction. The default is B.

delim.txind.beginval={value|\xhex_value}

For example:

delim.txind.beginval=0

The value that identifies an operation as the middle of a transaction. The default is M.

delim.txind.middleval={value|\xhex_value}

For example:

delim.txind.middleval=1

The value that identifies an operation as the end of a transaction. The default is E.

delim.txind.endval={value|\xhex_value}

For example:

delim.txind.endval=2

The value that identifies an operation as a whole transaction. The default is W.

delim.txind.wholeval={value|\xhex_value}

For example:

delim.txind.wholeval=3

Specifies the delimiter value used to separate fields (columns) in the data. This value is defined through characters or hexadecimal values:

delim.fielddelim={value|\xhex_value}

For example:

delim.fielddelim=,
delim.fielddelim=\xc7

Specifies the delimiter value used to separate lines (records) in the data. This value is defined using characters or hexadecimal values.

delim.linedelim={value|\xhex_value}

For example:

delim.linedelim=||
delim.linedelim=\x0a

Specifies the value used to identify quoted data. This value is defined using characters or hexadecimal values.

delim.quote={value|\xhex_value}

For example:

delim.quote="

Specifies the value used to identify NULL data. This value is defined using characters or hexadecimal values.

delim.nullindicator={value|\xhex_value}

For example:

delim.nullindicator=NULL

Specifies the value that will replace the field delimiter when the field delimiter occurs in the input field. The syntax is:

delim.fielddelim.escaped={value|\xhex_value}

For example, given the following property settings:

delim.fielddelim=-
delim.fielddelim.escaped=$#$

If the data does not contain the hyphen delimiter within any of the field values:

one two three four

The resulting delimited data is:

one-two-three-four

If there are hyphen (-) delimiters within the field values:

one two three four-fifths two-fifths

The resulting delimited data is:

one-two-three-four$#$fifths-two$#$fifths

Specifies the value that will replace the line delimiter when the line delimiter occurs in the input data. The syntax is:

delim.linedelim.escaped={value|\xhex_value}

For example, given the following property settings:

delim.linedelim=\
delim.linedelim.escaped=%/%

If the input lines are:

These are the lines and they
do not contain the delimiter.

Because the lines do not contain the backslash (\), the result is:

These are the lines and they\
do not contain the delimiter.\

However, if the input lines do contain the delimiter:

These are the lines\data values
and they do contain the delimiter.

So the results are:

These are the lines%/%data values\
and they do contain the delimiter.\

Specifies the value that will replace a quote delimiter when the quote delimiter occurs in the input data. The syntax is:

delim.quote.escaped={value|\xhex_value}

For example, given the following property settings:

delim.quote="
delim.quote.escaped="'"

If the input data does not contain the quote (") delimiter:

It was a very original play.

The result is:

"It was a very original play."

However, if the input data does contain the quote delimiter:

It was an "uber-original" play.

The result is:

"It was an "'"uber-original"'" play."

Specifies the value that will replace a null indicator when a null indicator occurs in the input data. The syntax is:

delim.nullindicator.escaped={value|\xhex_value}

For example, given the following property settings:

delim.fielddelim=,
delim.nullindicator=NULL
delim.nullindicator.escaped=$NULL$

When the input data does not contain a NULL value or a NULL indicator:

1 2 3 4 5

The result is

1,2,3,4,5

When the input data contains a NULL value:

1 2 4 5

The result is

1,2,NULL,4,5

When the input data contains a NULL indicator:

1 2 NULL 4 5

The result is:

1,2,$NULL$,4,5

Specifies whether before values are present in the data.

delim.hasbefores={true|false}

The default is false. The parser expects to find before and after values of columns for all records if delim.hasbefores is set to true. The before values are used for updates and deletes, the after values for updates and inserts. The afterfirst property specifies whether the before images are before the after images or after them. If delim.hasbefores is false, then no before values are expected.

For example:

delim.hasbefores=true

Specifies whether column names are present in the data.

delim.hasnames={true|false}

The default is false. If true, the parser expects to find column names for all records. The parser validates the column names against the expected column names. If false, no column names are expected.

For example:

delim.hasnames=true

Specifies whether after values are positioned before or after the before values.

delim.afterfirst={true|false}

The default is false. If true, the parser expects to find the after values before the before values. If false, the after values are before the before values.

For example:

delim.afterfirst=true

Specifies whether the column names and before and after images should be expected grouped together for all columns or interleaved for each column.

delim.isgrouped={true|false}

The default is false. If true, the parser expects find a group of column names (if hasnames is true), followed by a group of before values (if hasbefores), followed by a group of after values (the afterfirst setting will reverse the before and after value order). If false, the parser will expect to find a column name (if hasnames), before value (if hasbefores) and after value for each column.

For example:

delim.isgrouped=true

Specifies the date format for column data. This is specified at a global level, table level or column level.The format used to parse the date is a subset of the formats used for parser.timestamp.format.

delim.dateformat=format
delim.dateformat.TABLE=format
delim.dateformat.TABLE.COLUMN=format

Where:

• format is the format defined for parser.timestamp.format.

• table is the fully qualified name of the table that is currently being processed.

• column is a column of the specified table.

For example:

delim.dateformat=YYYY-MM-DD HH:MI:SS
delim.dateformat.MY.TABLE=DD/MM/YY-HH.MI.SS
delim.dateformat.MY.TABLE.EXP_DATE=YYMM

Specifies the location of the source definitions file.

xml.sourcedefs=file_location

For example:

xml.sourcedefs=dirdef/hrdemo.def

Specifies the list of XML rules for parsing a message and converting to transactions, operations and columns:

xml.rules=xml_rule_name[, . . .]

The specified XML rules are processed in the order listed. All rules matching a particular XML document may result in the creation of transactions, operations and columns. The specified XML rules should be transaction or operation type rules.

For example:

xml.rules=dyntxrule, statoprule

Specifies the type of XML rule.

rulename.type={tx|op|col}

Where:

• tx indicates a transaction rule

• op indicates an operation rule

• col indicates a column rule

For example:

dyntxrule.type=tx
statoprule.type=op

Specifies an XPath expression used to determine whether the rule is activated for a particular document or not.

rulename.match=xpath_expression

If the XPath expression returns any nodes from the document, the rule matches and further processing occurs. If it does not return any nodes, the rule is ignored for that document.

The following example activates the dyntxrule if the document has a root element of Transaction

dyntxrule.match=/Transaction

Where statoprule is a sub rule of stattxtule, the following example activates the statoprule if the parent rule's matching nodes have child elements of NewMyTableEntry.

statoprule.match=./NewMyTableEntry

Specifies a list of rule names to check for matches if the parent rule is activated by its match.

rulename.subrules=xml_rule_name[, . . .]

The specified XML rules are processed in the order listed. All matching rules may result in the creation of transactions, operations and columns.

Valid sub-rules are determined by the parent type. Transaction rules can only have operation sub-rules. Operation rules can have operation or column sub-rules. Column rules cannot have sub-rules.

For example:

dyntxrule.subrules=dynoprule
statoprule.subrules=statkeycolrule, statcol1rule

Controls the transaction timestamp by instructing the adapter to 1) use the transaction commit timestamp contained in a specified XPath expression or JMS property or 2) use the current system time. This is an optional property.

txrule.timestamp={xpath_expression|$jms_property|*ts}

The timestamp for the transaction may be overridden at the operation level, or may only be present at the operation level. Any XPath expression must end with a value, accessor, such as @att or text().

For example:

dyntxrule.timestamp=@ts

Specifies the format of the timestamp field.

txrule.timestamp.format=format

Where the format can include punctuation characters plus:

• YYYY – four digit year

• YY – two digit year

• M[M] – one or two digit month

• D[D] – one or two digit day

• HH – hours in twenty four hour notation

• MI – minutes

• SS – seconds

• Fn – n number of fractions

The default format is "YYYY-MM-DD:HH:MI:SS.FFF"

For example:

dyntxrule.timestamp.format=YYYY-MM-DD-HH.MI.SS

Specifies the seqid for a particular transaction. This can be used when there are multiple transactions per message. Determines the XPath expression, JMS property, or system value that contains the transactions seqid. Any XPath expression must end with a value accessor such as @att or text().

txrule.seqid={xpath_expression|$jms_property|*seqid}

For example:

dyntxrule.seqid=@seqid

Specifies the XPath expression, JMS property, or system value that contains the txid used to unique identify transactions. This value must increment for each transaction.

txrule.txid={xpath_expression|$jms_property|*txid}

For most cases using the system value of *txid is preferred.

For example:

dyntxrule.txid=$JMSTxId
dyntxrule.txid=*txid

Specifies the XPath expression, JMS property, or static value that contains an arbitrary user name associated with a transaction. This value may be used to exclude certain transactions from processing.

txrule.txowner={xpath_expression|$jms_property|"value"}

For example:

dyntxrule.txowner=$MessageOwner
dyntxrule.txowner="jsmith"

Specifies the XPath expression, JMS property, or static value that contains an arbitrary name to be associated with a transaction. This is an optional property.

txrule.txname={xpath_expression|$jms_property|"value"}

For example:

dyntxrule.txname="fixedtx"

Controls the operation timestamp by instructing the adapter to 1) use the transaction commit timestamp contained in a specified XPath expression or JMS property or 2) use the current system time. This is an optional property.

oprule.timestamp={xpath_expression|$jms_property|*ts}

The timestamp for the operation will override a timestamp at the transaction level.

Any XPath expression must end with a value accessor such as @att or text().

For example:

statoprule.timestamp=./CreateTime/text()

Specifies the format of the timestamp field.

oprule.timestamp.format=format

Where the format can include punctuation characters plus:

• YYYY – four digit year

• YY – two digit year

• M[M] – one or two digit month

• D[D] – one or two digit day

• HH – hours in twenty four hour notation

• MI – minutes

• SS – seconds

• Fn – n number of fractions

The default format is "YYYY-MM-DD:HH:MI:SS.FFF"

For example:

statoprule.timestamp.format=YYYY-MM-DD-HH.MI.SS

Specifies the seqid for a particular operation. Use the XPath expression, JMS property, or system value that contains the operation seqid. This overrides any seqid defined in parent transaction rules. Must be present if there is no parent transaction rule.

Any XPath expression must end with a value accessor such as @att or text().

oprule.seqid={xpath_expression|$jms_property|*seqid}

For example:

dynoprule.seqid=@seqid

Specifies the XPath expression, JMS property, or system value that contains the txid used to uniquely identify transactions. This overrides any txid defined in parent transaction rules and is required if there is no parent transaction rule. The value must be incremented for each transaction.

oprule.txid={xpath_expression|$jms_property|*txid}

For most cases using the system value of *txid is preferred.

For example:

dynoprule.txid=$JMSTxId
dynoprule.txid=*txid

Specifies the XPath expression, JMS property, or static value that contains an arbitrary user name associated with a transaction. This value may be used to exclude certain transactions from processing. This is an optional property.

oprule.txowner={xpath_expression|$jms_property|"value"}

For example:

dynoprule.txowner=$MessageOwner
dynoprule.txowner="jsmith"

Specifies the XPath expression, JMS property, or static value that contains an arbitrary name to be associated with a transaction. This is an optional property.

oprule.txname={xpath_expression|$jms_property|"value"}

For example:

dynoprule.txname="fixedtx"

Specifies the XPath expression JMS property or hard-coded value that contains the schema and table name in the form SCHEMA.TABLE. Any XPath expression must end with a value accessor such as @att or text(). The value is verified to ensure the table exists in the source definitions.

oprule.schemaandtable={xpath_expression|$jms_property|"value"}

For example:

statoprule.schemaandtable="MY.TABLE"

Specifies the XPath expression, JMS property or hard-coded value that contains the schema name. Any XPath expression must end with a value accessor such as @att or text().

oprule.schema={xpath_expression|$jms_property|"value"}

For example:

statoprule.schema=@schema

Specifies the XPath expression, JMS property or hard-coded value that contains the table name. Any XPath expression must end with a value accessor such as @att or text().

oprule.table={xpath_expression|$jms_property|"value"}

For example:

statoprule.table=$TableName

Specifies the XPath expression, JMS property or literal value that contains the optype to be validated against an optype insertval. Any XPath expression must end with a value accessor such as @att or text().

oprule.optype={xpath_expression|$jms_property|"value"}

For example:

dynoprule.optype=@type
statoprule.optype="I"

Specifies the value that identifies an insert operation. The default is I.

oprule.optype.insertval={value|\xhex_value}

For example:

dynoprule.optype.insertval=A

Specifies the value that identifies an update operation. The default is U.

oprule.optype.updateval={value|\xhex_value}

For example:

dynoprule.optype.updateval=M

Specifies the value that identifies a delete operation. The default is D.

oprule.optype.deleteval={value|\xhex_value}

For example:

dynoprule.optype.deleteval=R

Specifies the XPath expression or JMS property that contains the transaction indicator to be validated against beginval or other value that identifies the position within the transaction. All operations within a single message are regarded as occurring within a whole transaction if this property is not defined. Specifies the begin, middle and end of transactions. Any XPath expression must end with a value accessor such as @att or text(). Transactions defined in this way can span messages. This is an optional property.

oprule.txind={xpath_expression|$jms_property}

For example:

dynoprule.txind=@txind

Specifies the value that identifies an operation as the beginning of a transaction. The default is B.

oprule.txind.beginval={value|\xhex_value}

For example:

dynoprule.txind.beginval=0

Specifies the value that identifies an operation as the middle of a transaction. The default is M.

oprule.txind.middleval={value|\xhex_value}

For example:

dynoprule.txind.middleval=1

Specifies the value that identifies an operation as the end of a transaction. The default is E.

oprule.txind.endval={value|\xhex_value}

For example:

dynoprule.txind.endval=2

Specifies the value that identifies an operation as a whole transaction. The default is W.

oprule.txind.wholeval={value|\xhex_value}

For example:

dynoprule.txind.wholeval=3

Specifies the XPath expression or hard-coded value that contains a column name. The column index must be specified if this is not and the column name will be resolved from that. If specified the column name will be verified against the source definitions file. Any XPath expression must end with a value accessor such as @att or text().

colrule.name={xpath_expression|"value"}

For example:

dyncolrule.name=@name
statkeycolrule.name="keycol"

Specifies the XPath expression or hard-coded value that contains a column index. If not specified then the column name must be specified and the column index will be resolved from that. If specified the column index will be verified against the source definitions file. Any XPath expression must end with a value accessor such as @att or text().

colrule.index={xpath_expression|"value"}

For example:

dyncolrule.index=@index
statkeycolrule.index=1

Specifies the XPath expression or hard-coded value that contains a column value. Any XPath expression must end with a value accessor such as @att or text(). If the XPath expression fails to return any data because a node or attribute does not exist, the column value will be deemed as null. To differentiate between null and missing values (for updates) the isnull and ismissing properties should be set. The value returned is used for delete before values, and update/insert after values.

colrule.value={xpath_expression|"value"}

For example:

statkeycolrule.value=./text()

Specifies the XPath expression used to discover if a column value is null. The XPath expression must end with a value accessor such as @att or text(). If the XPath expression returns any value, the column value is null. This is an optional property.

colrule.isnull=xpath_expression

For example:

dyncolrule.isnull=@isnull

Specifies the XPath expression used to discover if a column value is missing. The XPath expression must end with a value accessor such as @att or text(). If the XPath expression returns any value, then the column value is missing. This is an optional property.

colrule.ismissing=xpath_expression

For example:

dyncolrule.ismissing=./missing

Overrides colrule.value to specifically say how to obtain before values used for updates or deletes. This has the same format as colrule.value. This is an optional property.

For example:

dyncolrule.before.value=./beforevalue/text()

Overrides colrule.isnull to specifically say how to determine if a before value is null for updates or deletes. This has the same format as colrule.isnull. This is an optional property.

For example:

dyncolrule.before.isnull=./beforevalue/@isnull

Overrides colrule.ismissing to specifically say how to determine if a before value is missing for updates or deletes. This has the same format as colrule.ismissing. This is an optional property.

For example:

dyncolrule.before.ismissing=./beforevalue/missing

Overrides colrule.value to specifically say how to obtain after values used for updates or deletes. This has the same format as colrule.value. This is an optional property.

For example:

dyncolrule.after.value=./aftervalue/text()

Overrides colrule.isnull to specifically say how to determine if an after value is null for updates or deletes. This has the same format as colrule.isnull. This is an optional property.

For example:

dyncolrule.after.isnull=./aftervalue/@isnull

Overrides colrule.ismissing to specifically say how to determine if an after value is missing for updates or deletes. This has the same format as colrule.ismissing. This is an optional property.

For example:

dyncolrule.after.ismissing=./aftervalue/missing