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 --