beginMessage

beginMessage(msg:     JadeGenericMessage input;
             options: String);

The beginMessage method of the JadeGenericQueue class prepares a message specified by the value of the msg parameter for segmented transmission and links it with the destination queue.

The initializeForPut method must be invoked for the msg parameter either explicitly, or implicitly by calling the createMessage method with the value of the forPUT parameter set to true.

After the beginMessage method is called, data can be added to the body of the message by using the appendBodyTuple method only, or by repeatedly using any of the appendBinary, appendString, appendStringAsUtf8, or appendStringUtf8 methods. The message is completed by calling the putMessage method, after which calls to an append method results in an exception being raised.

The message can begin transmitting before the putMessage method is invoked, because the beginMessage method has previously associated the message with the destination queue. This allows some overlap between message assembly and message transmission for large messages, although this behavior depends on the transport. After the beginMessage method is executed, you cannot update any properties of the message.

The putMessage method must be called on the same queue as the beginMessage method, to allow the message to become visible to receiving applications.

If the JadeGenericMessage object referenced by the msg parameter is deleted or is initialized by invoking the initializeForGet or initializeForPut method, the incomplete message is discarded, including any segments already transmitted.

If the options parameter is a null string, transport-specific default actions are taken. Options passed to this method override any specified in the defaultPutMessageOptions property. Components that can be included in the options parameter string for the JadeMQ transport are listed in the following table. (These options are ignored for the WebSphere MQ transport.)

Component	Result
NoWait	The method returns immediately if the queue is full
Timeout=milliseconds	The method waits for the specified number of milliseconds until there is enough room in the queue for a message to be sent
Timeout=0	The method waits indefinitely (the default implied option)

The following example shows the use of the beginMessage method.

vars
    msg : JadeGenericMessage;
begin
    msg := myQueue.createMessage(true);
    myQueue.beginMessage(msg, null);
    msg.appendString("first entry");
    // build the rest of the message
    msg.appendString("last entry");
    myQueue.putMessage(msg, null);
end;