8.2 Defining Dynamic Queries
Each dynamic query must be given a nickname, which may not contain white-space or non-printable characters. List owners know the queries by their nicknames, and have no access to their actual definitions. A query is defined by a LISTSERV configuration variable called:
DYN_QUERY_nickname=kwd1 *kwd2 *…++
On unix, the nickname must be entered in upper case, and shell escape and quoting conventions must be respected. Keywords have the following syntax:
keyword=’string that can contain white space’
keyword=”string that can contain white space”
Quotes within a quoted string must be doubled. The following keywords are recognized for both LDAP and DBMS queries:
- TYPE=LDAP | DBMS | EXIT (default: LDAP)
Whether the query uses LDAP, DBMS or a customer-supplied exit (script).
- SERVER=server_name (default: DEFAULT)
The nickname of the LDAP or DBMS server against which to run the search. If omitted, the search is run against the default (unnamed) LDAP or DBMS server.
- E-MAIL=attr_name (default: see explanation)
EMAIL=attr_name (default: see explanation)
NAME=attr_name (default: see explanation)
The name of the LDAP attribute or SQL column that contains the e-mail address or full name of the recipient, respectively. For LDAP, a default value can be specified in the LDAP server configuration (LDAP_DEFAULT_EMAIL_server and LDAP_DEFAULT_NAME_server). There is no default value for DBMS sources. The e-mail attribute or column name must be supplied, either explicitly or through LDAP_DEFAULT_EMAIL; the name is optional.
The following keywords are recognized for LDAP queries only:
- SCOPE=scope (default: SUBTREE)
The scope of the LDAP query.
The ‘distinguished name’ of the search base. Mandatory; may refer to parameters.
The search ‘filter’. Mandatory; may refer to parameters.
- ATTRS=attr1 *attr2 *…++
Any additional attributes (besides the name and e-mail address) that should be returned by the query when it is used in the context of processing a posting to a mailing list. These additional attributes become available as mail-merge fields. This keyword is ignored when the query is executed for other purposes (access control, etc.)
These keywords are recognized for DBMS queries only:
- DBMS=ODBC | OCI | CLI | UODBC (default available if only one driver is configured)
The name of the DBMS driver to use for the search. As with other DBMS functions, a default is provided if only one DBMS driver has been configured. Otherwise, this attribute is mandatory.
The SELECT statement to execute. It must return at least the e-mail column, and must also return the name column if one was specified. It may return additional columns, which are made available as mail-merge fields when the query is used in the context of processing a posting to a mailing list. For optimal performance, you should list the e-mail and name columns first. This attribute is mandatory and may refer to parameters.
These keywords are recognized for TYPE=EXIT queries only:
- EXITPARMn=arbitrary_data (1 ≤ n ≤ 4)
Four independent keywords are provided to pass arbitrary data or arguments to the exit. These keywords are made available to the exit script as it is called and may refer to parameters.
Important: For security reasons, keywords may not refer to parameters unless indicated otherwise. LISTSERV inserts all parameters as escaped text constants, to prevent them from changing the semantics of the search.
Parameters are specified as %1 for the first parameter, %2 for the second one, and so forth. The percent sign must be doubled.