When a service type of 4 is specified, the directory channel will query a CCSO directory to look up mailbox names.7 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.8 See
Section 21.1.1.2.2
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@acme.com -200:2:mailfield:alias -200:3:maildomain:acme.com 200:Ok.In this case the mail field name is alias and the mail domain name is acme.com. For an entry with an alias field value of Bob.Smith, the generated email address would then be Bob.Smith@acme.com.
If no matches are found then the message is returned with a note stating so.
3.2.7.1 Required options
Channel options must be used to specify the qi server with which to
communicate and to control aspects of the CCSO queries performed. To
this end, the QI_SERVERS and one or more QUERY_METHOD_ options must be
specified in the directory channel's option file.
3.2.7.1.1 QI_SERVERS option
The QI_SERVERS option specifies the TCP/IP host names of the qi servers
to use. This is a required option; if it is not specified, the
directory channel will not perform look ups.
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 For instance, to use the hosts ph.acme.com and admin.acme.com as qi servers, you can specify
QI_SERVERS=ph.acme.com|admin.acme.com+5000Since the port number was omitted for ph.acme.com, port 105 will be used. Port 5000 is used when connecting to admin.acme.com.
3.2.7.1.2 QI_QUERY_METHOD_ options
When attempting to locate an entry in a CCSO directory, the directory
channel will generate up to ten qi query commands. The
query commands will be tried one after the other until
either a match (or matches) is found or the list of possible query
methods is exhausted. The forms of the query commands are
controlled by "query methods" specified in the option file.
Since both the format of mailbox names and the behavior of qi
query commands vary so widely, no default query methods
are supplied by the directory channel. A set of one or more query
methods must be specified.
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-charHere
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.
| 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 |
As an example, let us assume that the address John.Doe@acme.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 acme.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.
| 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 ...
|
|. 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@acme.com would result in the following sequence of qi commands.
set approx=off soundex=off query email=John.Doe@acme.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.7.2 Additional options
Additional options are listed below:
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.7 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.7 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.7 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, ifNO_MATCH_HOST=hub.acme.comand no match can be found for the user Nerble, then the message will be forwarded on to Nerble@hub.acme.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 thesiteinfocommand cannot be used. See Section 3.2.7 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.7.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.7.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 thesiteinfocommand. 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=10The 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"@acme.comquerycommands of the formquery Bob Smith return ...would be generated. Were STRIP_QUOTES=0 specified, then the queries would be of the formquery "Bob Smith" return ...which may not be appropriate.
3.2.7.3 Example option files
An example option file is shown below.
acme.com=4 QI_SERVERS=qi.acme.com|vaxc.acme.com+5200 QUERY_METHOD_0=set exact=on|alias=%s QUERY_METHOD_1=set approx=on|%*sThe acme.com=4 option specifies that CCSO directory operations are to be done for the acme.com pseudo domain. The QI server qi.acme.com is used. If it is not reachable, then the qi server on port 5200 of vaxc.acme.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
qi*.zip file. Each qi*.zip file is a complete
distribution distinguished by its version number.