mt_start_transfer_in(3xmt) — Subroutines

Name

mt_start_transfer_in − Begins the inbound transfer of a communique or a report.

Syntax

OM_return_code = mt_start_transfer_in (session, object, identifier)

Argument	Data Type	Access
session	OM_private_object	read only
object	OM_private_object	write only
identifier	OM_string	write only
return_code	OM_return_code

C Binding

OM_return_code mt_start_transfer_in (session, object, identifier) OM_private_object session;
OM_private_object ∗object;
OM_string ∗identifier;

Arguments

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

ObjectThe object to be transferred in; an instance of class Communique or Report. The Service prevents the Client from modifying this object later. This argument is present only if the Return Value indicates success.

IdentifierA Service-assigned identifier that distinguishes the object from all other objects ever placed, or ever to be placed in the input queue. The identifier is a value with the syntax String(IA5) and a maximum length of 64 characters. This argument is present only if the Return Code result is success.

By means of a pointer, the Client provides the storage into which the Service is to place the identifier and its length. This space must be sufficient to accommodate the longest allowed identifier. When the identifier is no longer useful, the Client should deallocate the storage.

Description

This routine begins the inbound transfer of a communique or a report by reserving an unreserved object in the input queue to which a session provides access. If no objects await transfer in, the routine reports an exception. The Client can call this routine to begin the transfer in of one object before it has called the Finish Transfer In routine to finish the transfer in of another object, the delivery of which was started earlier in the same session. The inbound transfer of a particular object, however, cannot take place in two sessions simultaneously.

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

Return Values

MH_RC_FEATURE_UNAVAILABLE

OM_MEMORY_INSUFFICIENT

OM_NETWORK_ERROR

MH_RC_QUEUE_EMPTY

OM_SUCCESS

OM_SYSTEM_ERROR

MH_RC_WRONG_CLASS

Plus errors returned from:

om_instance

Examples

This example shows both the Start Transfer In and Finish Transfer In calls.

    om_status = mt_start_transfer_in (session,
                                      &transferred_object,
                                      &object_id);
    /∗
    ∗∗ finish transfer in and remove object from input queue
    ∗/
    om_status = mt_finish_transfer_in (session,
                                       transferred_object,
                                       OM_TRUE);

Museum