ma_wait(3xma) — Subroutines

Name

ma_wait − Indicates when a message or a report is available for delivery.

Syntax

OM_return_code = ma_wait (session, interval, minimum_sequence_number, available)

Argument	Data Type	Access
session	OM_private_object	read only
interval	MH_interval	read only
minimum_sequence_number	MH_sequence_number	read only
available	OM_boolean	write only
return_code	OM_return_code

C Binding

OM_return_code ma_wait (session, interval, minimum_sequence_number, available) OM_private_object session;
MH_interval interval;
MH_sequence_number minimum_sequence_number;
OM_boolean ∗available;

Arguments

SessionAn established MA session between a Client and the Service; an instance of the Session class.

IntervalThe maximum length of time (in milliseconds) that the Service is to block the Client before returning.

Minimum Sequence Number
This argument is relevant only to retrieval queues, which are not supported in this version of the MAILbus 400 API
The Service ignores this argument.

AvailableThis argument has the value true if there is an available object on the queue when the routine is called, or if the call returns early when an object is placed on the queue.

Description

This routine returns when a message or a report is available for delivery in the delivery queue to which a session provides access, or when a period of time elapses, whichever occurs first.

If there is at least one unreserved object on the delivery queue, the call returns immediately and indicates that an object is available.

If there are no unreserved objects on the delivery queue and the specified interval is zero, the call returns immediately and indicates that no object is available.

If there are no unreserved objects on the delivery queue and the specified interval is greater than zero, the call returns after the specified interval has elapsed, or when the Service places a new object on the queue, whichever occurs first. If the specified interval has elapsed, availability is false. If the Service places a new object on the queue, availability is true.

If there are multiple sessions waiting on a single queue when an object arrives on the queue, the Service returns to the first session that called the routine only.

Return Values

MH_RC_FEATURE_UNAVAILABLE

OM_MEMORY_INSUFFICIENT

OM_NETWORK_ERROR

OM_SUCCESS

OM_SYSTEM_ERROR

MH_RC_WRONG_CLASS

Plus errors returned from:

om_instance

Examples

This example uses an interval of 60000 milliseconds; that is, one minute. The zero is entered for the Minimum Sequence Number argument, and is ignored by the Service. The example includes code that shows how to use the results of a call to ma_wait.

    /∗
    ∗∗ Check to see if a message or report is waiting
    ∗/
    om_status = ma_wait (session, 60000, 0, &available);

    /∗
    ∗∗ No messages or reports on the queue
    ∗/
    if (available !=OM_TRUE)
        {
        printf ("No messages waiting for UA %.∗s0, client_name.length,
        client_name.elements);
        om_status = ma_close (sessions);
        exit (2);
        }
    /∗
    ∗∗ Messages or reports waiting on the queue
    ∗/
    om_status = ma_start_delivery (session, &delivered_object);

Museum