maX_open(3xma) — Subroutines

Name

maX_open − Establishes an MA session between the Client and the Service if a password is passed in the routine call.

Syntax

OM_return_code = maX_open (user_address, client_name, password, feature_list[], session, workspace)

Argument	Data Type	Access
user_address	OM_public_object	read only
client_name	OM_string	read only
password	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 maX_open (user_address, client_name, password, feature_list[], session, workspace) OM_public_object user_address;
OM_string client_name;
OM_string password;
MH_feature feature_list[];
OM_private_object ∗session;
OM_workspace ∗workspace;

Arguments

User AddressExplicitly identifies the local user to which the session is to provide MTS access; an instance of the OR Address class.

If you omit this argument, you must include the Client Name argument.

You should indicate the absence of this argument by using a null pointer.

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. The name implicitly identifies one or more local users to which the session is to provide MTS access.

If you omit this argument, you must include the User Address argument.

You should indicate the absence of this argument by using a zero length string.

PasswordThe interpretaion of this argument depends on whether your application uses the Client Name or the User Address argument:

If you are using a Client Name, this is the password associated with the Client, as specified when the Client application is registered with the MTA.

If you supply the User Address argument, this is the password specified when the user’s O/R address is registered in the directory.

You can indicate the absence of a password by using a null pointer.

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.

SessionAn MA session established between the Client and the Service; an instance of the Digital Session class. The Service prevents the Client from modifying this object. This argument is present only if the Return Code result is success.

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

Description

This routine is a Digital extension to the standard X.400 API. It establishes an MA session between the Client and the Service, and makes the Basic Access FU and the OM Package initially available in that session. The Client should specify the other features required for the session.

The Client specifies either its own name or the O/R address of a local user. In the case of a Client name, the session provides access to a group of local users statically associated with the Client name. In the case of a local user, the session provides MTS access to that user at the specified address. The Client can optionally specify a password. 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

The Client always designates a particular user in the same way. There is no maximum number of users that may be assigned to a single delivery queue.

Opening an MA session also 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

MH_RC_NO_SUCH_USER

MH_RC_ORIGINATOR_IMPROPER

OM_PERMANENT_ERROR

OM_SUCCESS

OM_SYSTEM_ERROR

OM_TEMPORARY_ERROR

MH_RC_WRONG_CLASS

Plus errors returned from:

om_create

om_put

Examples

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

    /∗
    ∗∗ Set up strings defining the agent’s name and password
    ∗/
    static OM_string
        client_name = OM_STRING ("Fred");
        password = OM_STRING ("secret");
    /∗
    ∗∗ 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 = maX_open ( 0,
                          client_name,
                          password,
                          feature_list,
                          &session,
                          &workspace );

Museum