Before the form can be used, it must be configured. At a minimum, an option file for the form must be provided as described in Section 18.104.22.168. Further, you can need to adjust the setting of the PMDF option FORM_NAMES; see Section 22.214.171.124 for details.
126.96.36.199 PMDF Option FORM_NAMES
If you do not have a PMDF option file then you can skip this section.2
If you have a PMDF option file originally created prior to PMDF V5.2 and containing a FORM_NAMES entry, then you will need to edit that file and change the FORM_NAMES entry to read
188.8.131.52 Form Option File
The pop-up CCSO form requires the use of an option file. The name of
the option file must be
ccso_form_option. and it must be
stored in the PMDF table directory; e.g.,
PMDF_TABLE:ccso_form_option. The file must be world
readable. Each line of the option file contains the setting for one
option. An option setting takes the form
One required option which must be supplied in the option file is discussed in Section 184.108.40.206.1. Additional options are described in Section 220.127.116.11.4; customizing the form for another language is discussed in Section 18.104.22.168.
The name (address) used to invoke the CCSO form from PMDF MAIL, VMS MAIL, and DECwindows MAIL will be ph-form. To use a name other than in%ph-form from VMS MAIL or DECwindows MAIL, use the VMS MAIL SET FORWARD/USER= command to equate the desired name with in%ph-form.
22.214.171.124.1 Required Options
In order to use the pop-up CCSO addressing form, a mandatory option
must be specified in the file
option is the
QI_SERVERS option. If this option is not
specified, the form will refuse to run and will signal an
The QI_SERVERS option specifies the TCP/IP host names of the qi servers to use. The option's value takes the form (note the use of the vertical bar character, |)
host3, ... and
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 can 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
string, including angle brackets). This is only supported on OpenVMS
platforms and only in conjunction with Bruce Tanner's
qi implementation for OpenVMS. See Section 126.96.36.199.2 for further details.
For instance, to use the hosts
admin.example.com as qi servers, you can specify
ph.example.com, port 105 will be used. Port 5000 is used when connecting to
The PMDF_QI_SERVERS logical can be used to override the values of the
QI_SERVERS option. The translation value of
PMDF_QI_SERVERS, if defined, should be of the same format
as the values used with the option file option
For example, on OpenVMS the logical definition
$ DEFINE PMDF_QI_SERVERS "ph.example.com|admin.example.com+5000"
188.8.131.52.2 Connectionless Operation
The contents of this section are also applicable to the directory channel.
Normally, the form opens a TCP/IP connection to the local or remote qi server. On OpenVMS platforms, this overhead can be avoided if you are also hosting the CCSO database on the same cluster and are using Bruce Tanner's qi implementation for OpenVMS. In this case, the form can communicate directly with the database thereby obviating the need to make a TCP/IP connection. To configure this, two things must be done: (1) configure the form to use the connectionless protocol, and (2) install the qi API image provided with Bruce Tanner's qi implementation.
To configure the form to use the connectionless protocol, specify the
(this exact string, including
angle brackets) with the
QI_SERVERS option. For instance,
The qi and CCSO datbase's API image must be installed as a known image
with the OpenVMS
INSTALL command and the system-wide,
executive mode logical
CCSO_API must be defined and point
to the location of the image. Any logicals referenced by
CSO_APISHR must also be executive mode logicals. For
$ DEFINE/SYSTEM/EXEC CSO_APISHR d1:[qi.vax_exe]qi_api.exe $ INSTALL CREATE CSO_APISHR /OPEN/HEADER/SHARED
When attempting to locate an entry in the database, the pop-up form
will generate up to ten qi
query commands. The
query commands will be tried one after the other until
either a match is found or the list of possible query methods is
query command will be of the form
query name-value dept-value return name department email alias
name-valueis derived from the text in the name field on the pop-up form and
dept-valueis derived from the text in the department field.
The method by which the
dept-value strings are derived from their
corresponding fields in the form is controlled with the
qi-commandis an optional qi server command to issue prior to the
dept-formatare formatting strings describing how to format the information from the name and department fields for use in a qi
querycommand. Table 21-1 describes control sequences which can be used in the formatting strings.
||Substitute in the value of the name or department field supplied by the user to the pop-up form|
Same as %s but with wild card,
Substitute in the name of the department field as specified with the
Let us assume that the name field has the value "John C Doe"
and the department field has the value "Sales". Under this
assumption, Table 21-2 shows sample
formatting strings and the
query commands that would
result. In the table the
return ... portion of the
query command is omitted.
By default, two query methods are used. They are,
QUERY_METHOD_0=set approx=on soundex=on|%s|%f=%s QUERY_METHOD_1=|%*s|%f=%*s
setcommand are server dependent. The
setcommands used by the default query methods are accepted by Bruce Tanner's qi implementation for OpenVMS. They are most likely not appropriate for other qi servers.
Under these defaults, a query for the name "John C Doe" in the department "Corporate Sales" would result in the following sequence of qi commands.
set approx=on soundex=on query John C Doe department=Corporate department=Sales return ... query John* C* Doe* department=Corporate* department=Sales* return ...
To omit any department information from appearing in the query
commands, simply omit any
strings from the QUERY_METHOD_n options; e.g.,
QUERY_METHOD_0=set approx=on soundex=on|%s QUERY_METHOD_1=|%*s
querycommand is only specified with QUERY_METHOD_0. This means that no additional command will be issued before the second query method, QUERY_METHOD_1, is attempted. Since with most qi servers, settings persist, there is no need to reissue the same
Another aspect of the format of
query commands is
controlled with the
DEPARTMENT_INDEXED option. By default
the department field is not assumed to be indexed,
DEPARTMENT_INDEXED=0. In this case, when the
CCSO database is queried and no name has been specified
but a department name has been, the
query command will
take the form4
query * department=dept-value
184.108.40.206.4 Additional Options
Described below are some additional options which can be specified in
the form's option file,
ALIAS_FIELD_NAME (text string <= 251 characters long)The name of the CCSO field to use to obtain a unique entry identifier and to also use with the
logincommand. Normally this is a field named "alias"; however, some CCSO databases can use a different field name (e.g., "unique" or "uniqueid"). When not specified, ALIAS_FIELD_NAME=alias is assumed.
DEPARTMENT_FIELD_NAME (text string <= 251 characters long)The form allows users to specify a "department" name when querying the database. This parameter allows specification of the
CCSOdatabase field name associated with this user supplied information. By changing this field name as well as the form label and comment (
DEPARTMENT_COMMENToptions; see Section 220.127.116.11), the form can be configured to query a field other than the department field. When not specified,
DEPARTMENT_INDEXED (0 or 1)Specifies whether or not the field specified with the
DEPARTMENT_FIELD_NAMEoption is an indexed field. By default,
DEPARTMENT_INDEXED=0is used; specify
CCSOdatabase treats the department field as an indexed field. This will yield better performance for searches in which only a department name is specified. See Section 18.104.22.168.3 for further details on the usage of this option.
EMAIL_FIELD_NAME (text string <= 251 characters long)The name of the
CCSOfield to use to obtain an entry's e-mail address. When not specified, EMAIL_FIELD_NAME=email is assumed. See Sections 22.214.171.124 and 126.96.36.199 for details on the usage of this option.
HELPFILE (text string <= 252 characters long)The complete file specification for a text file containing help information. The contents of this file will be displayed when help is requested from the main addressing screen. By default, the file
ccso_form.hlpfrom the PMDF documentation directory is used (
PMDF_DOC:ccso_form.hlpon OpenVMS). See also the MENU_HELPFILE option.
LEADING_WILDCARDS (0 or 1)Specifies whether or not leading wild cards,
*, are put into strings formatted with the
%*scontrol sequence. By default,
LEADING_WILDCARDS=0, a leading wild card is not put into such strings since that reduces the efficiency of the lookup process with some qi servers. Specify a value of
1to have leading wild cards added.
MANDATORY_FIELDS (-1, 0, 1, 2, or 3)A bit encoded value indicating which fields a user must supply in order for a lookup to be performed. When the lowest bit is set, a value must be specified for the form's name field; when the second lowest bit is set, a value must be specified for the form's department field. The default value of
-1indicates that either one of the fields must be specified (i.e., at least one of the fields must be specified). Use of the value
0will allow lookups when no information has been supplied therefore allowing a user to retrieve all entries from the database (actually, all entries which would result from the command
query *.) Note that the
STR_ERROR6option can be used to specify the text of the error message generated when the required fields have not been supplied. The default value for that option is intended to be compatible with the default setting of
MANDATORY_FIELDSand the default values for NAME_LABEL and
MENU_HELPFILE (text string <= 252 characters long)The complete file specification for a text file containing help information. The contents of this file will be displayed when help is requested from within a selection menu. By default, the file
ccso_form_menu.hlpfrom the PMDF documentation directory is used (
PMDF_DOC:ccso_form_menu.hlpon OpenVMS. See also the HELPFILE option.
MENU_SINGLE (0 or 1)When a user queries the directory and matches are found, a selection menu is then presented to the user. From the selection menu the user can then select the desired match or matches. By default, even if only a single match is found the selection menu is presented (
MENU_SINGLE=0to dispense with the selection menu when a single match is found. Note that while some users can dislike
MENU_SINGLE=1, it does force them to stop and think about whether or not the match that has been turned up is the one for which they were looking. Using
MENU_SINGLE=0increases the likelihood that a user will accept with minimal consideration a match returned by the directory. Should a match be incorrect, the user can end up sending mail to the wrong person. Note that from the selection menu a user can call up detailed information on each match with the
NAME_FIELD_NAME (text string <= 251 characters long)The name of the
CCSOfield to use to obtain the person's name associated with a database entry. When not specified,
NEXT (K, L, N, or P)The control character which can be entered to move to the next address when more than one address is being entered). By default,
CTRL/N (NEXT=N)is the control character keystroke used.
PREV (K, L, N, or P)The control character which can be entered to move to the previous address when more than one address is being entered. By default,
CTRL/P (PREV=P)is the control character keystroke used.
QI_SERVERS (text string <= 252 characters long)A list of one or more qi servers to use. See Section 188.8.131.52.1 for details.
QUERY_METHOD_0, ..., QUERY_METHOD_9 (text string <= 252 characters long)Specify the query methods to use when searching for an entry. See Section 184.108.40.206.3.
RECV_TIMEOUT (integer >= 0 seconds)This option controls how long the pop-up form will wait for a response from the qi server before giving up (timing out). By default, the form will wait 120 seconds
(RECV_TIMEOUT=120). To disable the timeout mechanism, specify
RECV_TIMEOUT=0. This will cause the pop-up form to wait indefinitely. When a timeout occurs, the form closes its connection to the qi server. When necessary, the form will attempt to restablish a connection with a qi server (e.g., in response to a find request from the user).
SITEINFO (0 or 1)Controls whether or not information gathered in response to a qi
siteinfocommand is used in generating the e-mail address for an entry selected from the directory. By default, SITEINFO=1, such information is used. Inhibit the use of
siteinfoinformation by specifying
SITEINFO=0. In that case, the value of the e-mail address field will always be used to generate an e-mail address. The name of that field is specified with the
EMAIL_FIELD_NAMEoption. See Section 220.127.116.11.3 for further details.
18.104.22.168 Changing Languages
ccso_form_option.sample in the PMDF table
directory is a sample option file which specifies the default option
values used by the pop-up CCSO form. In that option file, there appear
a large number of options beginning with
STR_ or ending
_COMMENT. Those options, which
are not documented here, can be used to control the text appearing in
labels, prompts, and messages. They allow customization of the form for
use with languages other than English. See also the description of the
MENU_HELPFILE options in
2 On OpenVMS systems, the PMDF option
file is the file pointed at by the