User Guide : Scripting : Script Objects : DJMessage Object Type
 
Share this page                  
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 512 MB.
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.
Methods
 
Method
Description
AddAttachment
Attaches a message. Method parameter is a message object.
AttachmentCount
Returns the number of attachments on a message.
GetAttachment
Retrieves an attachment from a message. Method parameter is either an integer indicating the attachment index or a string indicating the attachment name.
RemoveAttachment
Removes an attachment. Method parameter is a string indicating the attachment name.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or method invocation.
DJMessage
Yes
Message object to attach to the subject message.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or method invocation.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or method invocation.
Variant
Yes (if no string is supplied)
The index number of the attachment.
String
Yes (if no index number is supplied)
The name of the attached message object.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or method invocation.
Integer
Yes (if no string is supplied)
The index number of the attachment.
String
Yes (if no integer is supplied)
The name of the attached message object.
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
 
Property
Type
Access
Description
Body
String
RW
Get/set the message body.
Encoding
Integer
RW
Get/set the character set encoding used for the message body.
Name
String
RW
Get/set the message name.
Properties
String
RW
Get/set a message property by name or by index.
PropertiesCount
Integer
RO
Get the number of message properties.
PropertyNames
String
RO
Get the name of the nth property in the property list.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, which is the subject of the property or method invocation.
String
Yes
Data to be assigned to the message body.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or method invocation.
Integer Constant
Yes
Code for the character set used to encode the body.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or method invocation.
String
Yes
Name assigned to the message.
Exceptions
The Name property may return the following exceptions if there is an error assigning a new name.
Exception
Description
ERR_PROPASSGN
Returned if the name is already used for another message object.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or method invocation.
Variant
Yes
Integer value representing the index of the property in the property array, or the name of the property. The index starts at zero.
String
Yes
Value to assign to a specified property.
Exceptions
The Properties property may return the following exceptions if the array index parameter is invalid.
Exception
Description
ERR_INDEX
Returned if index parameter is out of the valid range of indexes for the array.
ERR_NOSUCHPROP
Returned if the index is a name and there is no property with the given name.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or method invocation.
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
 
Type
Required
Description
DJMessage
Yes
Reference to the DJMessage, the subject of the property or the method invocation.
Integer
Yes
Integer value representing the index of the property in the property array. The index starts at zero.
Exceptions
The PropertyNames property may return the following exceptions if the array index parameter is invalid.
Exception
Description
ERR_INDEX
Returned if index parameter is out of the valid range of indexes for the array.
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
Operators
 
Operator
Type
Description
New
DJMessage
Create a new object.
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
 
Type
Required
Description
DJMessage
No (optional)
Name of the DJMessage object may be specified.
Example
' In this example, the new DJMessage object is named msg1:
Public msg As DJMessage
Set msg = New DJMessage "msg1"