mhX_orname_to_foreign(3xmh) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
mhX_orname_to_foreign − Uses the O/R Name supplied to look up a foreign address in the MAILbus 400 MTA’s routing information.
Syntax
OM_return_code = mhX_orname_to_foreign (workspace, mts_name domain, domain_password, or_name, foreign_address, match_oraddress, discard_oraddress, diagnostic)
| Argument | Data Type | Access |
| workspace | OM_workspace | Read |
| mts_name | OM_string | Read |
| domain | OM_string | Read |
| domain_password | OM_string | Read |
| or_name | OM_public_object | Read |
| foreign_address | OM_string | Write |
| match_oraddress | OM_private_object | Write |
| discard_oraddress | OM_private_object | Write |
| diagnostic | OM_enumeration | Write |
C Binding
OM_return_code mhX_orname_to_foreign (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_public_object or_name;
OM_string ∗foreign_address;
OM_private_object ∗match_oraddress;
OM_private_object ∗discard_oraddress;
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 passord is 128 octets.
O/R NameThe O/R Name of the user for which a foreign address translation is required. The O/R Name must contain a valid O/R address; the Service ignores any directory name component.
Foreign AddressThe returned translation value associated with the O/R Name supplied with the call. This address can be in PrintableString or Teletex format.
Match O/R AddressThe O/R address that describes the values that the Service found in the directory as corresponding to the Foreign Address specified. This result might be a partial O/R address, for example "c=nz;a=nz-ptt;p=acme;o=acme;ou1=well".
Discard O/R AddressThe partial O/R address that contains the terms discarded while the Service was scanning the directory (see Description), for example "cn=fred bloggs". Note that the Discard O/R Address includes only those parts of the directory entry that the MAILbus 400 MTA uses for routing, so that a combination of the Match O/R Address and the Discard O/R Address is not always the same as the O/R Name that was supplied to the routine call.
DiagnosticAdditional error information is returned by 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 that holds the MAILbus 400 MTA’s routing information.
If the connection to the directory is unsuccessful, the Service returns OM_SYSTEM_ERROR with a diagnostic code of MHX_DIR_BIND_FAIL. With this diagnostic code, the problem may be temporary, 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, the O/R Name supplied is converted into a distinguished name suitable for a lookup in the MAILbus 400 MTA’s routing information.
If the O/R Name specified in the call contains a Personal Name rather than a Common Name, the Service searches the directory for the Common Name corresponding to that Personal Name. The Service uses the Common Name value in its search for foreign address translations. Note that the Service also returns the Common Name value as one of the O/R address arguments, and not the Personal Name.
The Service searches the directory, looking for foreign address translations that apply to the Domain Name supplied. The search involves progressively removing the last term from the O/R address. For details of this search, see MAILbus 400 MTA Tuning and Problem Solving. The Service returns the routing terms it has removed in the Discard O/R Address and omits them from the Match O/R Address.
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_ORNAME | The O/R Name specified in the call is invalid, either because it is not syntactically correct or because it does not match an ORaddress entity. Note that the call must specify the Personal Name attributes in PrintableString format; if the call supplies them only in Teletex format, the search fails with this diagnostic. |
| MHX_DIR_AMBIGUOUS_ORNAME | The O/R Name specified in the call is invalid because the personal attributes do not distinguish a single directory entry. |
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 O/R Name specified in the call, but there was no translation stored with it in the directory. |
| MHX_DIR_BAD_TRANSLATION_ATTR | The O/R Name 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. In this case, the Service still sets the Match O/R Address and Discard O/R Address. |
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
OM_WRONG_VALUE_LENGTH
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;
foreign_address.length = 1024;
foreign_address.elements = foreign_buffer;
/∗ Do lookup ∗/
om_status = mhX_orname_to_foreign(workspace,
OM_mts,
OM_domain,
OM_domain_password,
pub_or_name,
&foreign_address,
&match_oraddress,
&discard_oraddress,
&diagnostic);