DJMessage Object Type
Message objects can be used to send and receive data. Message objects are containers for both data and properties. The data part is the message content or payload, while the properties is used to describe the message to an application so that it can be read and processed. The maximum size limit for DJMessage is 2 GB.
Message objects are process global resources, similar to Private variables.
The DJMessage object type provides one interface for accessing the properties and bodies of message objects. It is important to understand that the DJMessage variables are really references to the message objects and are not themselves the message container.
Message objects can be used in conjunction with the DJMessage URI scheme as the following example shows:
' Declare a DJMessage variable
Dim m As DJMessage
' Create the new DJMessage object
Set m = New DJMessage
' Give the message a name
m.name = "abc"
' Set the message body
m.body = "Hello World"
' Change the message body using the DJMessage URI scheme
FileWrite("djmessage:///abc", "This is a test")
' Print the message body to the log to show that the FileWrite has changed the content
LogMessage("Info",m.body)
In the example, a new message object is created implicitly when the new DJMessage object is created. Once the message object has a name, it is accessible through either the DJMessage interface or through the URI scheme.
Note: Clearing the DJMessages between runs breaks the Integration Manager. Hence, you must change the scripts as following:
Set mgrEmail = FindMessage("mgrEmail")
' If a message with this name is not available, one will be initialized
If mgrEmail is Nothing Then
Set mgrEmail = new DJMessage "mgrEmail"
Methods
Tip... A message attachment is simply a message that has been attached to another message.
AddAttachment Method
Attaches another message object to the message.
Syntax
messageName.AddAttachment(anotherMessage)
Parameters
Exceptions
Invalid arguments to AddAttachment, GetAttachment, and RemoveAttachment generate run-time errors.
Example
' The following code adds an attachment
Dim msg1 As DJMessage
Set msg1 = New DJMessage "msg1"
Dim msg2 As DJMessage
Set msg2 = New DJMessage "msg2"
msg1.AddAttachment(msg2)
AttachmentCount Method
Returns the number of attachments on a message.
Syntax
messageName.AttachmentCount()
Parameters
The AttachmentCount method does not accept any arguments; however, the parentheses are still required.
Example
' The following code returns the number of attachments
Dim numberOfAttachments
numberOfAttachments = msg1.AttachmentCount()
GetAttachment Method
Retrieves an attachment from a message. Method parameter is either an integer indicating the attachment index or a string indicating the attachment name.
Syntax
messageName.GetAttachment(0)
' OR
messageName.GetAttachment("attachedMessage")
Parameters
Exceptions
Invalid arguments to AddAttachment, GetAttachment, and RemoveAttachment generate run-time errors.
Example
Dim attachedMsg as DJMessage
' Return the first attachment by index
Set attachedMsg = msg1.GetAttachment(0)
' Return the attachment named msg2
Set attachedMsg = msg1.GetAttachment("msg2")
RemoveAttachment Method
Removes an attachment. Method parameter is a string indicating the attachment name.
Syntax
messageName.GetAttachment(0)
' OR
messageName.GetAttachment("attachedMessage")
Parameters
Exceptions
Invalid arguments to AddAttachment, GetAttachment, and RemoveAttachment generate run-time errors.
Example
' Remove the first attachment by index
msg1.RemoveAttachment(0)
' Remove the attachment named msg2
msg1.RemoveAttachment("msg2")
Properties
Body Property
Get/set the body or payload of a message object. The body property is used to access the data in the message body. Data stored in the message body is encoded using the encoding specified with the Encoding property.
Syntax
messageName.Body
' OR
messageName.Body = stringName
Parameters
Example
'The following code creates a new message and adds a message body.
Dim m As DJMessage
Set m = New DJMessage
m.Body = "<Test>This is a test</Test>"
Encoding Property
Get/set the character set encoding for the message body. The Encoding is used to specify the character set used to encode the data in the message body.
Character sets are identified with integer constants. When the encoding is changed from one character set to another, the data in the message body is decoded using the previous character set and re-encoded using the new character set. The default encoding is UTF-8 (ENC_UTF8). See
Constant Values for Encoding Parameters in EZscript.
Syntax
messageName.Encoding
' OR
messageName.Encoding = encoding
Parameters
Exceptions
If the property is set to an encoding that is either invalid or not installed, an exception can be returned.
Example
'The following code creates a new message and sets the encoding to ISO 8859-1.
Dim m As DJMessage
Set m = New DJMessage
m.Encoding = ENC_ISO8859_1
m.Body = "<Test>This is a test</Test>"
Name Property
Get/set the name of a message object. Message objects are process global resources that are referenced by name. The Name property is used to get the name of the message object referenced by a DJMessage variable or to change its name.
Syntax
messageName.Name
'OR
messageName.Name = name
Parameters
Exceptions
The Name property may return the following exceptions if there is an error assigning a new name.
Example
' The following code prints the internally assigned name for a new message object.
' New message objects are assigned unique names of the form MessageN, where N is an integer value.
Dim m As DJMessage
Set m = New DJMessage
LogMessage("Info",m.Name)
Properties Property
Get/set message property value for an element of the property array. The Properties property is used to get or set values for message properties.
Values are stored in the DJMessage object as strings. No distinction is made between user defined properties and message header properties. Property values can be read using either an integer representing the index of the property in the array or a string representing the property name.
An exception is returned if the specified property does not exist. New properties can be added to the properties list by indexing the properties list with a new name.
Syntax
messageName.Properties(n)
' OR
messageName.Properties(n) = value
Parameters
Exceptions
The Properties property may return the following exceptions if the array index parameter is invalid.
Example
'The following code assigns the string value of "22" to the message property Parts
msg1.Properties("Parts") = "22"
PropertiesCount Property
Get a count of the number of message properties in the property array. PropertiesCount is used to determine how many message properties are defined in a DJMessage object. It is useful for establishing the upper bound of the index one would use for iterating over the collection of message properties.
Syntax
messageName.PropertiesCount
Parameters
Example
' The following code prints the message names and values for all of the properties in the DJMessage object message:
For i = 0 to msg1.PropertiesCount - 1
LogMessage("Info", msg1.PropertyNames(i) & " = " & msg1.Properties(i) )
Next i
PropertyNames Property
Get a message property name for an element of the property array. The PropertyNames property is used to look up the name for a message property by its index in the property array.
Syntax
msg.PropertyNames(n)
Parameters
Exceptions
The PropertyNames property may return the following exceptions if the array index parameter is invalid.
Example
'The following code copies the message properties from DJMessage object msg1 to msg2. The properties in msg2 are indexed by property name to ensure that values from the msg1 properties are assigned to the corresponding properties in msg2.
For i = 0 To msg1.PropertiesCount - 1
msg2.Properties(msg1.PropertyNames(i)) = msg1.Properties(i)
Next i
Binary Property
The binary property is used to indicate if a given DJMessage has a Text or Binary payload. If the property is true, the payload is binary and consists of a byte array, if false the payload is plain text.
A special encoding (ENC_BINARY) has been introduced to make reading and writing binary files easier. You can use this feature in EZScript (Script or start/stop steps).
Syntax
Msg.binary = true
Parameters
Example
Dim srcMsg As DJMessage
Set srcMsg = New DJMessage
srcMsg.binary=true
srcMsg.body=fileread("D:\Test.png", ENC_BINARY)
if srcMsg.binary == true then
filewrite("D:\test_out.png", srcMsg.body, ENC_BINARY)
end if
Operators
New Operator
Creates a new DJMessage object.
The New operator creates a new instance of a DJMessage object. The default character set for encoding the body is UTF-8. The default name for the message object is formed by concatenating a unique numeric string to a base name of "Message".
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
New DJMessage
Parameters
Example
' In this example, the new DJMessage object is named msg1:
Public msg As DJMessage
Set msg = New DJMessage "msg1"