mhX_foreign_to_orname(3xmh) — Subroutines

Name

mhX_foreign_to_orname − Uses the foreign address supplied in the call to look up an O/R Name in the MAILbus 400 MTA’s routing information.

Syntax

OM_return_code = mhX_foreign_to_orname (workspace, mts_name domain, domain_password, foreign_address, orname, diagnostic)

Argument	Data Type	Access
workspace	OM_workspace	Read
mts_name	OM_string	Read
domain	OM_string	Read
domain_password	OM_string	Read
foreign_address	OM_string	Read
or_name	OM_private_object	Write
diagnostic	OM_enumeration	Write

C Binding

OM_return_code mhX_foreign_to_orname(workspace, mts_name domain, domain_password, foreign_address, or_name, diagnostic) OM_workspace workspace,
OM_string mts_name,
OM_string domain,
OM_string domain_password,
OM_string foreign_address,
OM_private_object ∗or_name,
OM_enumeration ∗diagnostic

Arguments

WorkspaceThe workspace in which the Service creates any returned objects.

MTS NameThe PrintableString version of the distinguished name of the routing domain that the application operates in. Your application must give this argument the same name as is used for the MTS entity.

DomainName of the Domain entity that represents the application requesting the function. Your application must give this argument the same name as is used for the Domain entity (an entity of the MTS module).

Domain PasswordThe password associated with the Domain Name, as specified in the MTS Create/Set Domain command. A descriptor with a length of zero (0) indicates a null password. Maximum length of the password is 128 octets.

Foreign AddressThe foreign address string that must be translated into an O/R Name

O/R NameThe O/R Name stored as an attribute of the foreign address in the directory.

DiagnosticAdditional error information is returned in this argument, if appropriate.

Description

The Service uses the MTS Name, Domain Name and Domain Password supplied with the call to connect to the directory.

If the connection to the directory is unsuccessful, the Service returns OM_SYSTEM_ERROR with a diagnostic code of MHX_DIR_BIND_FAIL. This diagnostic code can indicate a temporary problem, and your application should retry. Other OM_SYSTEM_ERROR diagnostics indicate underlying errors that need to be put right before the routine will succeed:

Diagnostic Code	Problem
MHX_DIR_DLL_FAILURE	The Service has failed to find or invoke the appropriate shareable image or library. In this case it is necessary to re-install all three components of the MAILbus 400 MTA.
MHX_DIR_INTERNAL_PROBLEM	There is a problem with some resource used by the Service; for example, the DUA is not configured. In this case, the MAILbus 400 MTA will be failing in a more general way.

If the connection to the directory is successful, and if the entry exists, the Service looks up the foreign address entry and returns its O/R Name translation.

If the return code is MH_RC_NO_SUCH_USER, the diagnostic codes have these meanings:

Diagnostic Code	Problem
MHX_DIR_BAD_PASSWORD	The Domain Password specified in the call does not match the one previously entered for the Domain entity.
MHX_DIR_BAD_DOMAIN_NAME	The Domain Name argument to the call does not match the Domain entity.
MHX_DIR_BAD_MTS_NAME	The MTS Name argument to the call is invalid, either because it is not syntactically correct or because it does not match the MTS entity.
MHX_DIR_BAD_FOREIGN_ADDR	The Foreign Address argument to the call is invalid, either because it is not syntactically correct or because it does not match a Foreign Address entity

If the return code is MH_RC_ORIGINATOR_IMPROPER, the diagnostic codes have these meanings:

Diagnostic Code	Problem
MHX_DIR_NO_TRANSLATION	The Service successfully found the Foreign Address specified in the call, but there was no translation stored with it in the directory.
MHX_DIR_BAD_TRANSLATION_ATTR	The Foreign Address specified in the call does exist, and the Service found a translation for it in the directory. But the Service could not process the translation it found.

Return Values

OM_FUNCTION_DECLINED

OM_MEMORY_INSUFFICIENT

OM_NETWORK_ERROR

MH_RC_NO_SUCH_USER

MH_RC_ORIGINATOR_IMPROPER

OM_SUCCESS

OM_SYSTEM_ERROR

MH_RC_WRONG_CLASS

Plus errors returned from:

om_create

om_put

Examples

/∗ Set up strings defining the MTS, domain and password ∗/
    OM_mts.length = strlen (mts);
    OM_mts.elements = (void ∗) mts;
    OM_domain.length = strlen (domain);
    OM_domain.elements = (void ∗) domain;
    OM_domain_password.length = strlen (domain_password);
    OM_domain_password.elements = (void ∗) domain_password;
/∗ Do lookup ∗/
    om_status = mhX_foreign_to_orname(workspace,
                                     OM_mts,
                                     OM_domain,
                                     OM_domain_password,
                                     foreign_address,
                                     &match_oraddress,
                                     &diagnostic);

Museum