mt_open(3xmt) — Subroutines

Name

mt_open − Establishes an MT session between a Client and the Service.

Syntax

OM_return_code = mt_open (client_name, client_instance_name, feature_list[], session, workspace)

Argument	Data Type	Access
client_name	OM_string	read only
client_instance_name	OM_string	read only
feature_list	MH_feature[]	read-write
session	OM_private_object	write only
workspace	OM_workspace	write only
return_code	om_return_code

C Binding

OM_return_code mt_open (client_name, client_instance_name, feature_list[], session, workspace) OM_string client_name;
OM_string client_instance_name;
MH_feature feature_list[];
OM_private_object ∗session;
OM_workspace ∗workspace;

Arguments

Client NameThe name by which the Service knows the Client. The name can be up to 128 characters long, and can include hyphens. The leading character must be alphabetic.

Client Instance NameThe name by which the Service knows the Client instance, passed as a value with the syntax String(IA5).

Feature ListThis argument is an ordered sequence of features each represented by an object identifier and a Boolean value. The sequence must be terminated by an object identifier having no components (a length of zero and any value of the data pointer in the C representation).

If the routine completes its task successfully, the service puts true or false in the Boolean value against the requested feature, depending on whether the feature is available or not.

SessionThe established MT session between the Client and the Service; an instance of the Digital Session class. The Service prevents the Client from modifying this object subsequently. This argument is present only if the Return Value indicates success.

WorkspaceThe workspace that contains all objects returned as a result of the routines invoked in the session.

Description

This routine establishes an MT session between a Client and the Service, and makes the Basic Transfer FU and the OM Package initially available in that session. The Client may also specify the other features required for the session.

The Client must specify its Client name and its instance name. If the Service has several Clients, the Client’s name determines the input and output queues to which the session provides access. All Client instances share the Client’s input and output queues. If a Client has several instances, the Service may use the instance name for purposes such as identifying any log entries that are required for management. While the session is being established, the MAILBUS 400 API verifies that the MTA version is compatible. If the version is not compatible, the Service returns this error code: OM_PERMANENT_ERROR

Opening an MT session creates a workspace. A workspace contains objects returned as a result of routines invoked within that session. The workspace is used as an argument in calls to om_create and om_copy.

The maximum number of sessions that may exist simultaneously is set by the Maximum Agent Connections attribute in the MTA.

Return Values

MH_RC_FEATURE_CONFLICTS

MH_RC_FEATURE_UNAVAILABLE

OM_MEMORY_INSUFFICIENT

OM_NETWORK_ERROR

MH_RC_NO_SUCH_CLIENT

OM_PERMANENT_ERROR

OM_SUCCESS

OM_SYSTEM_ERROR

OM_TEMPORARY_ERROR

MH_RC_WRONG_CLASS

Examples

In this example, a string is set up for the client name and the feature list is declared dynamically before the routine call.

    /∗
    ∗∗ Set up strings defining the agent’s name and a null value for
    ∗∗ the client_instance_name argument
    ∗/
    static OM_string
        client_name = OM_STRING ("Fred"),
        nullstring = (0,0);
    /∗
    ∗∗ Construct the feature list, requesting the following functional
    ∗∗ units: Basic Access, Submission; and the following object
    ∗∗ definition packages: Message Handling 1988,
    ∗∗ Interpersonal Messaging 1988
    ∗/
    MH_feature feature_list[5];
    feature_list[0].feature = MH_FE_BASIC_ACCESS;
    feature_list[0].activated = OM_TRUE;
    feature_list[1].feature = MH_FE_SUBMISSION;
    feature_list[1].activated = OM_TRUE;
    feature_list[2].feature = MH_FE_MH_88;
    feature_list[2].activated = OM_TRUE;
    feature_list[3].feature = MH_FE_IM_88;
    feature_list[3].activated = OM_TRUE;
    feature_list[4].feature.length = 0;
    feature_list[4].feature.elements = OM_ELEMENTS_UNSPECIFIED;
    feature_list[4].activated = OM_TRUE;
    /∗
    ∗∗ Open a session
    ∗/
    om_status = mt_open ( 0,
                          client_name,
                          nullstring,
                          feature_list,
                          &session,
                          &workspace );

Museum