PMDF System Manager's Guide

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 21.1.1.2. Further, you can need to adjust the setting of the PMDF option FORM_NAMES; see Section 21.1.1.1 for details.

21.1.1.1 PMDF Option FORM_NAMES

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

FORM_NAMES=fax-form,ph-form,x500-form,ldap-form

21.1.1.2 Form Option File

option=value

One required option which must be supplied in the option file is discussed in Section 21.1.1.2.1. Additional options are described in Section 21.1.1.2.4; customizing the form for another language is discussed in Section 21.1.1.3.

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.

21.1.1.2.1 Required Options

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, |)

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 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 (this 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 Section 21.1.1.2.2 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.

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 QI_SERVERS. For example, on OpenVMS the logical definition

$ DEFINE PMDF_QI_SERVERS "ph.example.com|admin.example.com+5000"

might be used.

21.1.1.2.2 Connectionless Operation

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 special name (this exact string, including angle brackets) with the QI_SERVERS option. For instance,

QI_SERVERS=<local-access>|ph.example.com

With the above setting, the connectionless protocol will first be attempted and if that fails (e.g., cannot load the necessary API image), then a TCP/IP connection will be made to ph.example.com.

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 example on VAX,

$ DEFINE/SYSTEM/EXEC CSO_APISHR d1:[qi.vax_exe]qi_api.exe $ INSTALL CREATE CSO_APISHR /OPEN/HEADER/SHARED

21.1.1.2.3 Queries

query name-value dept-value return name department email alias

where name-value is derived from the text in the name field on the pop-up form and dept-value is derived from the text in the department field.

The method by which the name-value and dept-value strings are derived from their corresponding fields in the form is controlled with the QUERY_METHOD_0, QUERY_METHOD_1, ..., QUERY_METHOD_9 options:

QUERY_METHOD_n=qi-command|name-format|dept-format

Here qi-command is an optional qi server command to issue prior to the query command (e.g., set soundex=on). name-format and dept-format are formatting strings describing how to format the information from the name and department fields for use in a qi query command. Table 21-1 describes control sequences which can be used in the formatting strings.

Table 21-1 Query Method Formatting String Control Sequences

Sequence	Usage
%s	Substitute in the value of the name or department field supplied by the user to the pop-up form
%*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
%f	Substitute in the name of the department field as specified with the DEPARTMENT_FIELD_NAME option

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

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 name-format and dept-format formatting strings and the query commands that would result. In the table the return ... portion of the query command is omitted.

Table 21-2 Example Formatting Strings

Formatting string	Resulting query command
%s|%f=%s	query John C Doe department=Sales
%*s|%f=%*s	query John* C* Doe* department=Sales*
name=%s|%f=%s	query name=John C Doe department=sales
%s|title=%s	query John C Doe title=sales
%s|%s	query John C Doe Sales

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

Note that options to the set command are server dependent. The set commands 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 ...

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

To omit any department information from appearing in the query commands, simply omit any dept-format formatting strings from the QUERY_METHOD_n options; e.g.,

QUERY_METHOD_0=set approx=on soundex=on|%s QUERY_METHOD_1=|%*s

Note that in the above example a qi command to issue prior to the query command 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 set command between query commands.

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 form⁴

query * department=dept-value

Such a query can be inefficient with some databases. If the department field is indexed by the database, then specify DEPARTMENT_INDEXED=1. In that case, the optimized query command

query department=dept-value

will instead be generated.

21.1.1.2.4 Additional Options

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 login command. 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 CCSO database field name associated with this user supplied information. By changing this field name as well as the form label and comment (DEPARTMENT_LABEL and DEPARTMENT_COMMENT options; see Section 21.1.1.3), the form can be configured to query a field other than the department field. When not specified, DEPARTMENT_FIELD_NAME=department is assumed.

DEPARTMENT_INDEXED (0 or 1)

Specifies whether or not the field specified with the DEPARTMENT_FIELD_NAME option is an indexed field. By default, DEPARTMENT_INDEXED=0 is used; specify DEPARTMENT_INDEXED=1 when your CCSO database 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 21.1.1.2.3 for further details on the usage of this option.

EMAIL_FIELD_NAME (text string <= 251 characters long)

The name of the CCSO field to use to obtain an entry's e-mail address. When not specified, EMAIL_FIELD_NAME=email is assumed. See Sections 21.1.2.1 and 21.1.2.2 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.hlp from the PMDF documentation directory is used (PMDF_DOC:ccso_form.hlp on 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 %*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 lookup process with some qi servers. Specify a value of 1 to 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 -1 indicates that either one of the fields must be specified (i.e., at least one of the fields must be specified). Use of the value 0 will 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_ERROR6 option 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 -1 for MANDATORY_FIELDS and the default values for NAME_LABEL and DEPARTMENT_LABEL.

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.hlp from the PMDF documentation directory is used (PMDF_DOC:ccso_form_menu.hlp on 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=1). Specify MENU_SINGLE=0 to 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=0 increases 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 ? and PF1 ? keys.

NAME_FIELD_NAME (text string <= 251 characters long)

The name of the CCSO field to use to obtain the person's name associated with a database entry. When not specified, NAME_FIELD_NAME=name is assumed.

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 21.1.1.2.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 21.1.1.2.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 siteinfo command 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 siteinfo information 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_NAME option. See Section 21.1.1.2.3 for further details.

21.1.1.3 Changing Languages