x

To configure the RDB High Water Mark (RDBHWM) listener:

1. From the iWay Service Manager Administration Console, click Registry and then Listeners.

   The Listeners pane opens.

2. Click Add.

   The Select listener type pane opens.

   

3. Select the RDB High Watermark (rdbhwm) listener from the drop-down list, then click Next.

   The Configuration parameters for new listener of type RDB High Watermark (rdbhwm) pane opens.

   

   Note: This image is used for demonstration purposes and only shows the first set of configuration parameters for the RDBHWM listener in the iWay Service Manager Administration Console. The complete list of configuration parameters are listed and described in the table in step 4.

4. Provide the appropriate property values for the RDBHWM listener, as defined in the following table.

   Note: An asterisk indicates a required property.

   Parameter	Definition
   Query SQL*	Query statement to be issued. It must contain at least one question mark (?), which will be replaced with the high water mark value from the prior SQL select. The following example assumes that your HWM column is called hwm. select col1, col2, hwm from tab1 where hwm > '?' order by hwm This may be a date-time field or an increasing integer. Numeric fields should not be enclosed in single quotes. Character fields and date fields must have the single quotes coded in the SELECT as illustrated. If multiple HWM columns are used, the ? notation is replaced with ?:name, where name is an HWM column name. Note: If you are using an EDA server, column names are case-sensitive.
   HWM Field*	Name of the column(s) containing the high water mark in the retrieved row(s). It is case-sensitive. In the above example, the value would be hwm. If the high water mark consists of multiple columns, they must be comma delimited in order from the most significant to least significant value (for example, most frequently changing field entered last). For better performance and to minimize complexity, it is preferable to identify single column which can be used as the HWM value. The HWM column(s) must also be present in the SELECT list of the query SQL.
   HWM Bind	If set to true, a bind strategy is used to construct the SELECT. If set to false, the SQL is constructed for each iteration of the listener. Note: HWM Bind allows the system to prepare, and then execute the SELECT statement with different values. Some JDBC drivers optimize for prepared statements while others do not. This option is made available so you can choose the strategy that works best for your application.
   HWM Persistence Type *	Determines whether the HWM values should be persisted. Select one of the following options from the drop-down list: File. The value will be saved to a local file. File With Backup. A backup file will be maintained. RDBMS. The value will be stored in an RDBMS table. Before using RDBMS persistence, you must create the iWay_HWM table using the DDL script that is provided in the etc/setup directory. For more information, see Configuring the HWM Persistence Type Parameter.
   HWM Persistence Location *	If the HWM Persistence Type parameter is set to File or File With Backup, then specify the directory where the HWM should be saved. For RDBMS persistence, specify the name of the iSM JDBC provider for the database where the iWay_HWM table was created.
   HWM Default*	Value to be used as the high water mark on the first run of the listener, or if the high water mark value file is not found.
   Generated XML Format	Select one of the following values from the drop-down list: column field row
   Column Limit	Varchars exceeding the specified limit will be carried as external files.
   Maximum Rows	The maximum number of rows to include in each document. The default value is 1.
   Ignore Case	Some databases are case-sensitive and cannot recognize a field if the case is different than the one in which the field is stored in the database. As a result, setting this field to true facilitates column recognition.
   Base64 Check	Each value is examined and if the value cannot be represented in the normal character set, it is replaced with its base64 representation. This is not necessary for binary data if processing the result will not be processed as an iWay XML document.
   Include xLOBs in Tree	If set to true, the contents of a Binary Large Object (BLOB) or Character Large Object (CLOB) are included in the tree and not as external files. BLOBs will be encoded using Base64. The inclusion of xLOBs in the tree can result in significant memory use.
   Transaction Isolation Level	Transaction isolation level to be set if possible. Select one of the following options from the drop-down list: Asis. Leaves the isolation level as defined by the database. Compute. Selects the highest isolation level supported by the database. Read Committed. Will never read data that another application has changed and not yet committed. This option does not ensure that data will not be changed before the end of the transaction. Read Uncommitted. Allows reading of a record that may be rolled back later. Repeatable Read. Dirty reads and non-repeatable reads cannot occur. All data used in the query is locked and another transaction cannot update the data. Serializable. The most restrictive isolation level. Phantom values cannot occur. Other users are prevented from updating or inserting rows into the data set until the transaction is completed. Each option functions as defined, but selecting the appropriate option can be confusing. For most applications, selecting the Asis option is sufficient, which effectively sets the Transaction Isolation Level to none. These options are provided so that application developers can control transactionality for their solution. Isolation levels differ among database engines and developers are encouraged to test how these options impact processing.
   When To Save	Determines at what point during the life cycle of a message that the High Water Mark (HWM) value should be saved. Select one of the following values from the drop-down list: dispatch. Saves the HWM value as each row of the database is dispatched to the channel. This is the default. result set. Saves the HWM value when all of the records retrieved by an SQL execution are completely processed. row. Saves the HWM value as each row is completed. One thread is allowed. For more information, see Configuring the When To Save Parameter.
   Connection
   Use JNDI *	If set, the SQL connection is taken from a data source provider. If not set, the connection is established from locally entered driver and URL fields
   JNDI Factory	Determines how to reach the data source provider. Use this parameter only if the Use JNDI parameter is set. The default is appropriate when using iSM data providers. If you are running in an application server, you may want to change this value to reach data sources on that server.
   JNDI Name	The JNDI name of the requested data source. To use an iWay JDBC provider, specify as jdbc/provider. This parameter is required if the Use JNDI parameter is set to true.
   Driver	The full name of the JDBC driver to reach the database.
   URL	The URL used by the JDBC driver to access the database.
   User Name	The database user name to access input table.
   Password	The database password for the user.
   Tuning
   Multithreading	Number of documents that can be processed in parallel for this listener. The default value is set to 1.
   Maximum Threads	Parallel threads can grow to this count automatically on demand. The default value is set to 1.
   Optimize Favoring	Select one of the following values from the drop-down list: performance memory Note: Selecting memory is recommended if you are expecting large input documents.
   Polling Interval	The specified Interval at which to check for new input or check for server stop (in seconds). The default value is set to 2 seconds.
   Events
   Failed ReplyTo Flow	Name of published process flow to run if a message cannot be emitted on an address in its reply address list.
   Dead Letter Flow	Name of published process flow to run if an error cannot be emitted on an address in its error address list.
   Channel Failure Flow	Name of published process flow to run if this channel cannot start or fails during message use. The server will attempt to call this process flow during channel close down due to the error.
   Parse Failure Flow	Name of published process flow to run if XML parsing fails for incoming message.
   Channel Startup Flow	Name of published process flow to run prior to starting the channel.
   Channel Shutdown Flow	Name of published process flow to run when the channel is shut down.
   Other
   Whitespace Normalization	Specifies how the parser treats whitespaces in element content. Choose preserve (default) to disable all normalization as prescribed by the XML specification. Choose condense to remove extra whitespaces in pretty printed documents and for compatibility with earlier versions.
   Accepts non-XML (flat) only	If set to true, the listener expects only flat (non-XML) files and the preparsers do not run.
   Execution Time Limit	Time limit (in seconds) for a document to execute before it is terminated.
   Default Java File Encoding	Default encoding if the incoming message is not self-declaring, for example, XML.
   Always Reply to listener default	If set to true, the default reply definition is used in addition to the defined replies.
   Error Documents treated normally	If set to true, error documents are processed by any configured preemitters.
   Listener is Transaction Manager	If set to true, agents run within a local transaction managed by the listener.
   Record in Activity Log(s)	If set to true, the activity on this channel will be recorded in the activity logs, else the activity will not be recorded.
   Startup Dependencies	Comma-separated list of channel names that must be started before this one.

5. Click Next.

   The Select listener type pane opens.

   

6. Provide a name and optionally, a description for the RDBHWM listener, and click Finish.

   The newly created RDBHWM listener is added to the list in the Listeners pane, as shown in the following image.

   

x

The When To Save parameter determines at what point during the life cycle of a message the High Water Mark (HWM) key(s) are saved to the external file. The external file is used to determine from which point to pick up the read when the listener starts next or resumes. The values that can be selected for this parameter depends on the requirements and design of the application:

• dispatch. The HWM value is saved before the message is dispatched for execution. This is the original saving point. This is the default.
• resultset. If your SQL DML selects more than one row, and you expect more than one record to be returned with the same HWM value (for example, multiple records for a given timestamp or order number), then this value may be appropriate. The HWM value would be stored when all of the records in the result set are completely processed. Failure to use this setting may result in the loss of some records if the server fails while records are being processed. In this scenario, the HWM key might have been written and the DML specifies a value greater than the HWM value during startup.
• row. The HWM value is saved as the key changes to the next key (or the end of the current result set). This allows multiple keys of the same value to be processed within the result set. This is applicable only for cases that involve a single processing thread. If multiple threads were used, then the order of completion for the rows could not be guaranteed. This would result in possible gaps in the HWM tracking value, and as a result, the potential loss of records during a restart. For example, assume the completion order of a three parallel thread channel completed in the order of 4, 6, and 5. The HWM update would be 4 and then 6. Record 5 would not be written, since it is not an increase of the previous record (6). If the server fails, then record 5 would not be reread.

x

The High Water Mark (HWM) listeners read through a relational table in series, keeping the access keys of the last row processed. The assumption is that the access keys are ordered by the increasing value of key field(s). These state fields are written to external media as the states change. The state is tracked internally, and the external media is read when the listener starts. It is not read at any other time. The persistence options can be selected from the HWM Persistence Type drop-down list.

Three variations on this design pattern are provided, as listed in the following table.

Variation	Use	Managed By
RDBHWM/File	HWM kept in a local file. Fastest.	Listener
RDBHWM/Source DBMS	HWM kept in a source database.	Listener
RDBHWM/Target DBMS	HWM kept in a target database.	Application

Top of page

Top of page

Top of page