Creating message objects using msgcreate
Use the msgcreate command to create new messages. It returns the new message object's handle. Use the message object's handle with other MSG extension commands to manipulate the message.
For example:
Input: msgcreate
Output: message0
- The engine distinguishes
between two message classes: engine and protocol.
For example, to set a new message's class with msgcreate:
Input: msgcreate -meta { CLASS protocol } Output: message1
An equivalent command is:
Input: msgcreate -class protocol Output: message1
Both versions of the command set the newly-created message object to be a protocol class message.
By default, msgcreate produces engine messages.
- The engine distinguishes between two message types: data and reply.
If specified, then data is the initial value for the new message.
For example:
Input: msgcreate -meta { TYPE reply } Output: message2
An equivalent command is:
Input: msgcreate -type reply Output: message2
By default, msgcreate produces data messages.
- The msgcreate command also
sets the message's recovery state.
USERECOVERDB
specifies that the message undergoes normal recovery database processing if/when it leaves the interpreter and enters the engine.By default, new messages are TYPE data, indeterminate CLASS, and not handled by the recovery database.
Use the
USERECOVERDB 1
flag to permit messages to be saved in the recovery database.For example:
Input: msgcreate -meta { USERECOVERDB 1 } Output: message3
An equivalent command is:
Input: msgcreate -recover Output: message3
- Creating a new protocol reply message: Note: Specify all of the options and flags required when doing this, because after the message is created, these values cannot be changed.
For example:
Input: msgcreate -class protocol -recover -type\ reply Output: message4
An equivalent command is:
Input: msgcreate -meta { CLASS protocol\ USERECOVERDB 1 TYPE reply } Output: message4
Use the "--" flag to separate the options from the rest of the args.
For example:
Input: msgcreate -- -meta Output: message0
By default, message objects are created without data. Specify the initial value after the options and flags.
- Creating a new protocol
reply message initialized with data:
For example, to create a new protocol reply message that is recoverable and initialized with data:
Input: msgcreate -class protocol -recover -type\ reply "some data" Output: message5
An equivalent command is:
Input: msgcreate -meta {CLASS protocol\ USERECOVERDB 1 TYPE reply} "some data" Output: message5
Message objects can hold up to 4,294,967,295 (that is, 2^32 - 1) characters. An error happens if an attempt is made to extend a message beyond this limit.
The msglength command returns the number of characters in a message.
For example:
Input: msglength message6 Output: 24
- Information on most extensions is available from the hcitcl
window. You can use the keyword help followed by the command that needs
clarification. Additionally, command syntax is available in the hcitcl window by
entering the command with incorrect syntax.
An example of using msgcreate is:
Input: help msgcreate Output: msgcreate -meta ?CLASS? ?TYPE? USERECOVERDB ?data?
The available options for msgcreate are also displayed if the command is run with an -h option. This option usually indicates help.
For example:
Input: msgcreate -h Output: Error: bad option "-h": should be -class, -meta, -recover, -type, or --