(c) Digital Equipment Corporation. 1994. All rights reserved. 

Name

ma_start_delivery − Begins the delivery of a message or a report to one or more users. 

Syntax

OM_return_code = ma_start_delivery (session, object)

C Binding

OM_return_code ma_start_delivery (session, object) OM_private_object session;
OM_private_object ∗object;

Arguments

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

ObjectThe object that the routine starts the delivery of; an instance of the Delivered Message or the Delivered Report class. If a Delivered Message, the object includes one envelope for each user. The Service prevents the Client from modifying this object later. This argument is present only if the Return Value indicates success. 

Description

 
This routine begins the delivery of a message or a report to one or more of the users associated with a session by ma_open. It does this by reserving an unreserved object in the delivery queue. If no objects are awaiting delivery, the routine reports an exception. The Client must finish the delivery of one object before it can start the delivery of another in the same session.  The delivery of a particular object cannot take place in two sessions simultaneously. 

If the Multiple Delivery feature is available for the session, the Service can begin delivery of an object addressed to several users in one routine call. If not, the service begins delivery of an object addressed to several users in one routine call for each user. 

If the Multiple Delivery feature is selected, and the number of recipients on the message is greater than 100, the message is split into several messages, each for either 100 recipients or the remainder. The Service begins delivery of the first message for the first 100 recipients, and the remaining messages are requeued.  Further ma_start_delivery routine calls are required for the remaining messages. 

The Service always selects the first object in the delivery queue. The queue is ordered by arrival time and priority, priority taking precedence over arrival time. 

An invocation of this routine initiates but does not complete delivery; that is, it does not transfer responsibility for the object from the Service to the Client. The latter is accomplished by ma_finish_delivery. 

If either ma_wait or ma_size indicates that the delivery queue contains an object, this does not guarantee this routine’s success; another process, for example, may begin the delivery of the object in the meantime. 

Return Values

MH_RC_FEATURE_UNAVAILABLE

OM_MEMORY_INSUFFICIENT

OM_NETWORK_ERROR

MH_RC_QUEUE_EMPTY

MH_RC_SESSION_BUSY

OM_SUCCESS

OM_SYSTEM_ERROR

MH_RC_WRONG_CLASS

Plus errors returned from:

om_instance

Examples

 
This example shows the calls for both Start Delivery and Finish Delivery. In practice, an application would not call Finish Delivery until it had saved a complete copy of the message to disk.

The NULL arguments in the call to Finish Delivery indicate to the MTA that delivery was successful, and that the MTA should generate delivery reports if required. 
 
    om_status = ma_start_delivery (session, &delivered_object);
    om_status = ma_finish_delivery (session, NULL, NULL);