IBM InfoSphere Streams Version 4.1.1

Operator DB2SplitDB

SPL standard and specialized toolkits > com.ibm.streams.db 2.0.0 > com.ibm.streams.db.db2 > DB2SplitDB

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streams.db/op$com.ibm.streams.db.db2$DB2SplitDB.svg

The DB2SplitDB operator determines the partition to use when you are writing input tuples to a partitioned DB2 database. The operator submits the input tuple to an output stream that corresponds to the partition number.

The DB2SplitDB operator uses DB2 database table key information from an input tuple to determine its corresponding partition number in the DB2 database table. The input tuples must contain the attributes that correspond to the key fields in the database table. The operator has n number of output streams where n is equal to the number of partitions in the database. The operator submits the input tuple to an output stream that corresponds to the partition number.

The access specification that is named in the operator declaration must contain the tablename attribute within the <table> element. The access specification must also contain a <native_schema> element with <column> elements for each column in the table that is specified by the tablename attribute in the <table> element.

Behavior in a consistent region

A DB2SplitDB operator can be used in a consistent region. It cannot be the start operator of a consistent region.

In a consistent region, a DB2SplitDB operator cannot have a control port.

On drain: no action is done.

On checkpoint: no action is done.

On reset: no action is done.

Exceptions

The DB2SplitDB operator throws an exception and terminates in the following cases:
  • Unable to determine number of partitions
  • The number of output streams does not match the number of partitions.
  • The number of <column> elements that have the key=true attribute in the <native_schema> element of the <access_specification> element does not match the number of hash keys that are configured for the database table.
  • The NoRetry is specified for the reconnectionPolicy parameter and the initial connection attempt fails while the ODBCAppend operator is starting.

For other errors, messages are written to the log.

Examples

(stream <PersonSchema> out0;                          
 stream <PersonSchema> out1;                          
 stream <PersonSchema> out2;                          
 stream <PersonSchema> out3) = DB2SplitDB(persondata) 
{                                                           
  param                                                     
	connection         : "DBPerson";                        
	access             : "PersonSinkDefault";               
	connectionDocument : "./etc/connections.xml";           
}

Summary

Ports
This operator has 2 input ports and 1 or more output ports.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 10 parameters.

Required: connection, access

Optional: connectionDocument, connectionDatabase, connectionUser, connectionPassword, connectionPolicy, reconnectionPolicy, reconnectionBound, reconnectionInterval

Metrics
This operator reports 1 metrics.

Properties

Implementation
C++
Threading
Always - Operator always provides a single threaded execution context.

Input Ports

Ports (0)

The DB2SplitDB operator has one required input port. The tuples on the required input port must contain attributes that correspond to the key fields in the database table. The input port is non-mutating and its punctuation mode is Oblivious.

Properties

Ports (1)

The DB2SplitDB operator has one optional input port. This port allows operator configuration to be changed at run time.

Properties

Output Ports

Assignments
This operator does not allow assignments to output attributes.
Ports (0...)

The DB2SplitDB operator has one output port open set. The required number of output streams is the same as the number of partitions in the database. The output port is mutating and its punctuation mode is Preserving.

Properties

Parameters

This operator supports 10 parameters.
connection

This parameter specifies the name of a connection specification element in the connection specifications document that identifies the external service to which this operator connects. This parameter is required for all operators that require a database connection. The connection parameter must have exactly one value of type rstring.

Properties

access

This mandatory parameter specifies the name of an access specification element in the connection specifications document. The access specification indicates how this operator accesses specific data in the external service that is identified by the connection parameter.

Properties

connectionDocument

This optional parameter specifies the path name of the file that contains the connection and access specifications that are identified by the connection and access parameters.

If the connectionDocument parameter is specified, it must have exactly one value of type rstring. If the parameter is not specified, the operator looks for a file that is called connections.xml in the etc subdirectory of the application directory. The SPL application directory is the current working directory where the sc command is run. For example, if you run the sc command from the /home/myapp directory, the compiler looks for a connection document in the /home/myapp/etc directory.

Important:
  • The SPL compiler, in conjunction with the Database Toolkit, checks that the document named by the connectionDocument parameter is semantically valid XML. The compiler also checks that the values for the connection and access parameters have corresponding sections in this connection XML document.
  • The SPL compiler cannot check at compile time that the operator can connect to the external data service and access data as configured. The operators have internal checks for correct configuration of the external data service that might result in a runtime failure. Any failures are captured in the processing element logs. You can also use the odbchelper and db2helper programs that are included with the Database Toolkit to help you find setup and configuration issues.
Properties

connectionDatabase

This optional parameter specifies the data source name (DSN) of the target database. If this parameter is specified, any value specified in the database attribute of the <ODBC> element of the <connection_specification> element in the connection.xml document.

Properties

connectionUser

This optional parameter specifies the user name or identifier that is used to connect to the target database. If this parameter is specified, any value specified in the user attribute of the <ODBC> element of the <connection_specification> element in the connection.xml document is ignored.

Properties

connectionPassword

This optional parameter specifies the password that is used to connect to the target database. If this parameter is specified, any value specified in the password attribute of the <ODBC> element of the <connection_specification> element in the connection.xml document is ignored.

Properties

connectionPolicy

This optional parameter specifies the policy that is used to determine when a database connection, or subsequent reconnection after a database connection failure, occurs. The valid values are Immediate and Deferred. The default value is Immediate.

If Immediate is specified, the connection to the database is attempted when the operator is started. If a connection fails while an operator is running, a reconnection is attempted immediately when the disconnection is detected. This connection behavior minimizes delays in tuple processing.

If Deferred is specified, the initial connection to the database is not attempted until a connection is needed, which is usually the first time that an SQL statement is run. If a connection fails while an operator is running, the operator does not try to connect to the database until the next time that a connection is needed. This connection behavior is useful if an application has many instances of an ODBC operator and you need to minimize the number of connections that occur immediately.

Properties

reconnectionPolicy

This optional parameter specifies the policy that is used by the operator to handle database connection failures. The valid values are: NoRetry, InfiniteRetry, and BoundedRetry. The default value is InfiniteRetry.

If NoRetry is specified and a database connection failure occurs, the operator does not try to connect to the database again. The operator shuts down at startup time if the initial connection attempt fails.

If BoundedRetry is specified and a database connection failure occurs, the operator tries to connect to the database again up to a maximum number of times. The maximum number of connection attempts is specified in the reconnectionBound parameter. The sequence of connection attempts occurs at startup time. If a connection does not exist, the sequence of connection attempts also occurs before each operator is run.

If InfiniteRetry is specified, the operator continues to try and connect indefinitely until a connection is made. This behavior blocks all other operator operations while a connection is not successful. For example, if an incorrect connection password is specified in the connection configuration document, the operator remains in an infinite startup loop until a shutdown is requested.

Properties

reconnectionBound

This optional parameter specifies the number of successive connection attempts that occur when a connection fails. It is used only when the reconnectionPolicy parameter is set to BoundedRetry; otherwise, it is ignored. The reconnectionBound parameter is type uint32. The default value is 5.

Properties

reconnectionInterval

This optional parameter specifies the amount of time (in seconds) that the operator waits between successive connection attempts. It is used only when the reconnectionPolicy parameter is set to BoundedRetry or InfiniteRetry; otherwise, it is ignored. The default value is 10.

Properties

Metrics

droppedTuples - Counter

The number of input tuples that are dropped (not processed) because of a failure in retrieving the partition number.

Libraries

db2
Library Name: db2
Library Path: @STREAMS_ADAPTERS_DB2_LIBPATH@
Include Path: @STREAMS_ADAPTERS_DB2_INCPATH@