PMDF System Manager's Guide

When a service type of 4 is specified, the directory channel will query a CCSO directory to look up mailbox names.⁷ The types of queries are controlled with the QUERY_METHOD_ channel options. In the event of an ambiguous match, the possible choices will be returned along with the original message to the message originator.

The directory channel queries a CCSO directory via a TCP/IP connection to either a local or remote qi server.
Alternatively, on OpenVMS platforms if you are using Bruce Tanner's qi implementation, then the channel can use a connectionless protocol to communicate directly with the CCSO database.⁸ See <REFERENCE>(HEAD4_CCSOFORMCONNECTIONLESS) for details on configuring this. When using TCP/IP on OpenVMS, UCX emulation is required of your TCP/IP package.

When a single, unambiguous match is found for a pseudo domain mailbox name, the message is redirected to the address associated with the matching entry's e-mail field. The name of the e-mail field is given by the EMAIL_NAME_FIELD option. The email field should therefore be an internal address to which to forward the message. If the matching entry has no email field, then the message is returned to the originator with a note stating so.

If more than one match is found, then the message is returned to the originator along with a list of up to fifty possible matches. The SIZELIMIT option may be used to place a different limit on the number of matches returned. The list of matches will show, for each match, the values of the name and department fields. Different fields can be selected with the NAME_FIELD_NAME and DEPARTMENT_FIELD_NAME options. In addition, an email address to use for the match will be generated from the mail field and mail domain information generated by a qi siteinfo command. If the qi server does not return mailfield information then the address associated with the field named email will be returned. A different field can be selected with the PUBLIC_EMAIL_FIELD_NAME option.

As an example, suppose that a qi server's response to a siteinfo command is:

-200:0:version:VMS qi V2.12 -200:1:administrator:directory_manager@example.com -200:2:mailfield:alias -200:3:maildomain:example.com 200:Ok.

In this case the mail field name is alias and the mail domain name is example.com. For an entry with an alias field value of Bob.Smith, the generated email address would then be Bob.Smith@example.com.

If no matches are found then the message is returned with a note stating so.

3.2.8.1 Required Options

3.2.8.1.1 QI_SERVERS Option

The option's value takes the form, (note the use of the vertical bar character, |),

host1+port1|host2+port2|host3+port3...

where host1, host2, host3, ... and port1, port2, port3, ... are, respectively, the TCP/IP hosts and ports to which to connect. The hosts will be attempted in the order listed, from left to right, until a connection is successfully made to one of the hosts or the list is exhausted. IP addresses may be used in place of host names. If the port number is omitted then the standard qi port, port 105, will be used. When omitting the port number, also omit the +.
To bypass TCP/IP and communicate directly with an OpenVMS CCSO database, specify the hostname (that exact string, including angle brackets). This is only supported on OpenVMS platforms and only in conjunction with Bruce Tanner's qi implementation for OpenVMS. See <REFERENCE>(HEAD4_CCSOFORMCONNECTIONLESS) for further details.

For instance, to use the hosts ph.example.com and admin.example.com as qi servers, you can specify

QI_SERVERS=ph.example.com|admin.example.com+5000

Since the port number was omitted for ph.example.com, port 105 will be used. Port 5000 is used when connecting to admin.example.com.

3.2.8.1.2 QI_QUERY_METHOD_ Options

Each query command will be of the form

query name-value return ...

where name-value is derived from the mailbox and pseudo domain name, and the ... portion of the command signifies the names of various CCSO directory fields which will be requested.

The method by which the name-value string is derived is controlled with the QUERY_METHOD_0, QUERY_METHOD_1, ..., QUERY_METHOD_9 options:

QUERY_METHOD_n=qi-command|name-format|translate-from-chars|translate-to-char

Here qi-command is an optional qi server command to issue prior to the query command (e.g., set exact=on). name-format is a formatting string describing how to format the pseudo domain address for inclusion in the query command. translate-from-chars is an optional field specifying one or more characters which, when they appear in the mailbox name, will be translated to the optional character translate-to-char.

Table 3-2 describes control sequences which may be used in the name-format formatting string. Substitutions are done after any character translations have been performed.

Table 3-2 Query Method Formatting String Control Sequences

Sequence	Usage
%s	Substitute in the value of the mailbox name
%*s	Same as %s but with wild card, *, suffixes added to each blank delimited part of the field value; if LEADING_WILDCARDS=1 is specified in the option file then wild card prefixes will also be added
%h	Substitute in the pseudo domain name

To specify a literal %, |, or \, specify \%, \|, or \\.

As an example, let us assume that the address John.Doe@example.com is to be looked up in a CCSO database. In this case, the mailbox name is John.Doe and the pseudo domain name is example.com. Under this assumption, Table 3-3 shows sample query methods and the query commands that would result. In the table, the qi-command portion of the query method has been omitted.

Table 3-3 Example Formatting Strings

Formatting string	Resulting query command
|%s	query John.Doe return ...
|name=%s|_.|	query name=John Doe return ...
|%*s	query John.Doe* return ...
name=%*s|_.|	query name=John* Doe* return ...

In the second and fourth examples a space character follows the final |. Thus, the characters . and _ are changed to a space wherever they appear in a mailbox name.

To continue the above example, suppose that the three query methods shown below are specified:

QUERY_METHOD_0=set approx=off soundex=off|email=%s@%h QUERY_METHOD_1=set approx=on|%s|_.| QUERY_METHOD_2=|%*s|_.|

With these settings, a look up for John.Doe@example.com would result in the following sequence of qi commands.

set approx=off soundex=off query email=John.Doe@example.com return ... set approx=on query John Doe return ... query John* Doe* return ...

These commands will be tried one after the other until either a match is returned or the list of methods exhausted.

3.2.8.2 Additional Options

DEPARTMENT_FIELD_NAME (text string <= 251 characters long)

Specify the name of the CCSO directory's department field. This should be the name of the field giving the department name or other useful identifying information associated with a directory entry. This field is only used in the event of multiple matches. If not specified, the field name "department" is assumed. See Section 3.2.8 for futher details.

EMAIL_FIELD_NAME (text string <= 251 characters long)

Specify the name of the CCSO directory's email field. This should be the field with the "internal" email address to use for forwarding mail to an individual in the database. If not specified, the field name "email" is assumed. See Section 3.2.8 for further details.

LEADING_WILDCARDS (0 or 1)

Specifies whether or not leading wild cards, *, are put into strings formatted with the %*s control sequence. By default, LEADING_WILDCARDS=0, a leading wild card is not put into such strings since that reduces the efficiency of the look up process with some qi servers. Specify a value of 1 to have leading wild cards added.

NAME_FIELD_NAME (text string <= 251 characters long)

Specify the name of the CCSO directory's name field. This should be the name of the field giving the name associated with a directory entry. This name is only used when rejecting a message either because the matching database entry lacks an email field or in the event of multiple matches. If not specified, the field name "name" is assumed. See Section 3.2.8 for further details.

NO_MATCH_HOST (text string <= 252 characters long)

Specify a host to redirect messages to when no matches can be found in the CCSO directory. For instance, if

NO_MATCH_HOST=hub.example.com

and no match can be found for the user Nerble, then the message will be forwarded on to Nerble@hub.example.com rather than return the message as undeliverable.

PUBLIC_EMAIL_FIELD_NAME (text string <= 251 characters long)

Specify the name of the CCSO directory's public e-mail field. This should be the field with the "public" e-mail address to use as a hint when the address to be looked up is ambiguous. This field will only be used when information from the siteinfo command cannot be used. See Section 3.2.8 for further details. If not specified, the field name "email" is used.

QI_SERVERS (text string <= 252 characters long)

Specify the qi servers to contact. See Section 3.2.8.1.1 for details.

QUERY_METHOD_0, ..., QUERY_METHOD_9 (text string <= 252 characters long)

Specify the query methods to use. See Section 3.2.8.1.2 for details.

RECV_TIMEOUT (integer >= 0 seconds)

This option controls how long the directory channel will wait for a response from the qi server before giving up (timing out). By default, the channel will wait 120 seconds (RECV_TIMEOUT=120). To disable the timeout mechanism, specify RECV_TIMEOUT=0. This will cause the channel to wait indefinitely. When a timeout occurs, the channel closes its connection to the qi server. When necessary, the channel will attempt to reestablish a connection with a qi server.

SITEINFO (0 or 1)

In the case of an ambiguous address, the message is bounced back to the sender with hints as to how to resolve the ambiguity. These hints will include the e-mail addresses of the possible matches. When SITEINFO=1, the default, the e-mail addresses will, if possible, be constructed from information gathered with the siteinfo command. When SITEINFO=0, the addresses will be the value, if any, of the email address field for each possible match. The PUBLIC_EMAIL_FIELD_NAME option specifies the name of the field to use for this purpose.

SIZELIMIT (integer >= -1)

When the directory channel performs a search for an e-mail address, many entries may match the search criteria. If this is the case, the mail is returned to the sender along with a list of possible choices. The SIZELIMIT option controls the maximum number of choices which are returned; e.g.,

SIZELIMIT=10

The default value for SIZELIMIT is 50. You may want to make this limit smaller to reduce "trawling" of your database. Note that this limit may be superseded by a smaller limit which has been imposed by the manager of the qi server or CCSO directory. Specify a value of -1 to allow any number of matches to be returned; specify a value of 0 to suppress the return of possible matches.

STRIP_QUOTES (0 or 1)

Controls whether or not outer quotes are stripped from the local part of an address to be looked up. By default, STRIP_QUOTES=1, quotes are stripped. Thus, for the address

"Bob Smith"@example.com

query commands of the form

query Bob Smith return ...

would be generated. Were STRIP_QUOTES=0 specified, then the queries would be of the form

query "Bob Smith" return ...

which may not be appropriate.

3.2.8.3 Example Option Files

example.com=4 QI_SERVERS=qi.example.com|vaxc.example.com+5200 QUERY_METHOD_0=set exact=on|alias=%s QUERY_METHOD_1=set approx=on|%*s

The example.com=4 option specifies that CCSO directory operations are to be done for the example.com pseudo domain. The QI server qi.example.com is used. If it is not reachable, then the qi server on port 5200 of vaxc.example.com will be used.

Shown below is an example of an option file for a directory channel which services two different pseudo domains.

stateu.edu=4 students.stateu.edu=4 QI_SERVERS=ph.athena.stateu.edu stateu.edu_SIZELIMIT=10 students.stateu.edu_SIZELIMIT=15 students.stateu.edu_DEPARTMENT_FIELD_NAME=school QUERY_METHOD_0=set exact=on|alias=%s QUERY_METHOD_1=set approx=on|%*s