DJComponent Object Type
The DJComponent object provides enhanced support for queue sessions, iterators, aggregators, transformers, invokers, and validators. This object is available through the expression language and API.
Used in conjunction with the
DJMessage Object Type, the DJComponent object can be referenced in any expression within the Map window and any expression step within the Process window. This object provides transactional handling support of messages and conditional message puts and gets. The DJComponent ConnectString option is specific to the messaging middleware supported.
Messaging Support
The DJComponent object can call any MCF component. The message body is set and retrieved using the DJMessage object.
Properties
The DJComponent object type provides a generic interface for MCF components that support message queue-like operations.
ConnectString Property
Set the connection string for a DJComponent object. The connection string is a set of semicolon separated attribute-value pairs that specify all the information the DJComponent object needs to establish a connection with the data source.
The following attributes are supported for the DJComponent connection strings.
Syntax
msgadaptor.ConnectString = connection_string
Parameters
Exceptions
ConnectString returns exceptions if there is an error. The following exceptions can be returned.
Example
' The following example shows a connection string for connecting to a queue with the Websphere MQ adaptor:
Dim q As DJComponent
Set q = New DJComponent "Websphere MQ"
q.ConnectString = "queue=q_in"
Dim msg As DJMessage
On Error Resume Next
Set msg = q.GetMessage()
Properties Property
Get/set a message property value for an element of the property array. Properties property is used to get or set values for the properties that are part of the message adaptor configuration.
Property values can be read using either an integer representing the ordinal position of the property in the array or a string representing the property name. An exception is returned if the specified property does not exist.
Syntax
msgadaptor.Properties(n)
'OR
msgadaptor.Properties = value
You can also retrieve a property of the GetMessage action.
Dim djtrg As DJMessage
Dim comp As DJComponent
Set djtrg = New DJMessage "trg"
Set comp = New DJComponent "HideIterator"
comp.properties("hide") = "true"
comp.properties("opt1","GetMessage") = "This is a test for DJComponent"
' Retrieves the value of the option 'opt1' of the 'GetMessage' action
Set djtrg = comp.GetMessage()
filewrite(macrovalue("MCFTarget") & "TC24584DJComponentIterator.txt", djtrg.body)
Parameters
Exceptions
The Properties property may return the following exceptions if the array index parameter is invalid.
Example
' The following code sets the timeout for a message adaptor named 'q' to 200 milliseconds:
q.Properties("timeout") = "200"
PropertiesCount Property
Get a count of the number of message adaptor properties in the property array.
PropertiesCount is used to determine how many properties are supported by the message adaptor and associated with a DJComponent object.
Syntax
msgadaptor.PropertiesCount
Parameters
Example
' The following code logs the message property names and values for each of the properties of the message adaptor for the DJComponent object.
' Since the count will start at 1 but the array index starts at zero, subtract one from the PropertiesCount to determine the number of times to loop.
For i = 0 To (msg1.PropertiesCount - 1)
LogMessage("Info", q.PropertyNames(i) & " = " & q.Properties(i)
Next i
PropertyNames Property
Get a message adaptor property name for an element of the property array. PropertyNames property is used to look up the name for a message adaptor property by its ordinal position in the property array.
Syntax
msgadaptor.PropertyNames(n)
Parameters
Exceptions
The PropertyNames property may return the following exceptions if the array index parameter is invalid.
Example
' The following code logs the message property names and values for each of the properties of the message adaptor for the DJComponent object.
' Since the count will start at 1 but the array index starts at zero, subtract one from the PropertiesCount to determine the number of times to loop.
For i = 0 To (msg1.PropertiesCount - 1)
LogMessage("Info", q.PropertyNames(i) & " = " & q.Properties(i)
Next i
Methods
BeginTransaction Method
Start a new transaction on the message adaptor connected to a DJComponent object. BeginTransaction starts a transactional session on a message adaptor. If the message adaptor does not support transactions, calls to this method do nothing.
Syntax
msgadaptor.BeginTransaction()
Parameters
Example
'The following example starts a transaction for the message adaptor instance myQueue, reads a message, and commits the change.
Dim msg As DJMessage
On Error Resume Next
myQueue.BeginTransaction()
Set msg = myQueue.GetMessage()
myQueue.CommitTransaction()
CommitTransaction Method
Commit work done during a transaction on the message adaptor connected to a DJComponent object. CommitTransaction makes work done to a message adaptor during a transactional session permanent. If the message adaptor does not support transactions, calls to this method do nothing.
Syntax
msgadaptor.CommitTransaction()
Parameters
Example
'The following example starts a transaction for the message adaptor instance myQueue, reads a message, and commits the change.
Dim msg As DJMessage
On Error Resume Next
myQueue.BeginTransaction()
Set msg = myQueue.GetMessage()
myQueue.CommitTransaction()
GetMessage Method
Receive a message from the message adaptor connected to a DJComponent object. The GetMessage method returns a reference to a DJMessage object.
Note: In any component step, the component’s getMessage method is responsible for populating the message and returning a relevant return code. In a successful getMessage invocation (if source data is available), the component will populate the message body and associated message properties and return a (0) return code. If the component’s getMessage method encounters an issue (like no more data or EOF), the component is responsible for setting an appropriate return code. It’s up to the individual component to populate the message with information relevant to the encountered error. Some components getMessage method may add relevant information to the message, whereas other components do not add anything (leaving the message empty).
Syntax
msgadaptor.GetMessage()
Parameters
Exceptions
If there is an error at run time, the GetMessage method may return one of the following exceptions.
Example
'The following example starts a transaction for the message adaptor instance myQueue, reads a message, and commits the change.
Dim msg As DJMessage
On Error Resume Next
myQueue.BeginTransaction()
Set msg = myQueue.GetMessage()
myQueue.CommitTransaction()
PutMessage Method
Send a message to the message adaptor connected to a DJComponent object. The PutMessage method sends the contents of a DJMessage object to the message adaptor.
Syntax
msgadaptor.PutMessage(msg)
Note: Component and step options are copied to djmessage properties before the PutMessage action is called on the component UNLESS the djmessage already has a property with the same name. This means that djmessage property values take precedent over (override) option values.
Parameters
Exceptions
The PutMessage method may return one of the following exceptions if there is an error at run time.
Example
'The following example starts a transaction for the message adaptor instance myQueue, writes a message, and commits the change.
Dim msg As DJMessage
Set msg = New DJMessage
msg.Body = "<Test>This is a test</Test>"
On Error Resume Next
myQueue.BeginTransaction()
myQueue.PutMessage(msg)
myQueue.CommitTransaction()
Execute Method
Use the Execute method to execute a component associated with a DJComponent object.
Syntax
myComponent.execute(srcmsg, trgmsg)
Parameters
Example
' The following example shows how to create a DJComponent object to execute a Transformer component.
Dim srcmsg As DJMessage
Set srcmsg = New DJMessage
Dim trgmsg As DJMessage
Set trgmsg = New DJMessage
srcmsg.Body = "<Test>This is a test</Test>"
Dim myTransformer As DJComponent
Set myTransformer = New DJComponent "NullTransformer"
myTransformer.execute(srcmsg,trgmsg) ' Do something with the target message...
RollbackTransaction Method
Rollback a pending transaction on the MCF component connected to a DJComponent object. RollbackTransaction back out changes made during a transaction with the MCF component. If the MCF component does not support transactions, calls to this method do nothing.
Syntax
msgadaptor.RollbackTransaction()
Parameters
Example
' The following example starts a transaction for the MCF component instance myQueue, reads a message, and undoes the effect of the GetMessage on the component by calling RollbackTransaction.
Dim msg As DJMessage
On Error Resume Next
myQueue.BeginTransaction()
Set msg = myQueue.GetMessage()
myQueue.RollbackTransaction()
Connect Method
Establishes a connection to the message source/destination. Connect calls the component referenced by DJComponent.
Syntax
myComponent.connect(connectString)
Parameters
Disconnect Method
Instructs the component to disconnect from its currently established connection. Disconnect calls the component referenced by DJComponent.
Syntax
myComponent.disconnect()
Parameters
Reset Method
Called explicitly as an action to request that the component reset to initialized state, the beginning of the component lifecycle. Reset calls the component referenced by DJComponent.
Syntax
myComponent.reset()
Parameters
Exceptions
The component is expected to set an error condition if it fails to reset.
Operators
New Operator
The New operator creates a new instance of a DJComponent object. It takes one parameter, the name of the MCF component.
Once an object is created, the choice of component can not be changed without recreating the object. The operator returns a reference to the new object. Typically, this reference is assigned to an object variable that has been declared with a compatible type. The assignment is done using the Set statement.
Syntax
Set myComponent = New DJComponent componentName
Parameters
Examples
' Use the newest version of the REST Invoker
Set restInvoker = New DJComponent "REST Invoker"
' Use REST Invoker 1 instead of the newest version
Set restInvoker = New DJComponent "REST Invoker 1.0.0"
Exceptions
The New operator returns exceptions if there is an error creating the object. The following exceptions can be returned.