2.2 List Management Commands

Commands that support the QUIET keyword are marked with an asterisk (*).

ADD(*) listname user [full_name]
ADD(*) listname DD=ddname [IMPORT [PRELOAD]]

The first syntax is used to add an individual user to one of your lists, or update his name field. Note that you can substitute an asterisk (“*”) for full_name and LISTSERV will substitute “<No name available>” in the list.

The second syntax is used for bulk ADD operations where a dataset (DD=ddname) is used add multiple users, one address/name pair per line. For bulk operations you may also use the IMPORT option, which implies a QUIET ADD (in other words you do not need to specify QUIET if you use IMPORT) and otherwise vastly speeds up the ADD process by loosening syntax checking and omitting success messages. The IMPORT PRELOAD option is used to direct LISTSERV to preload the existing e-mail keys in memory before starting the transaction, which speeds the operation up considerably. This option is used primarily with DBMS lists to speed up bulk adds. PRELOAD is not necessary for traditional LISTSERV lists and does not normally lead to a significant performance improvement. However, when importing a new list (no existing subscribers), it does reduce CPU usage somewhat.

For a bulk ADD operation, the users are defined in a separate dataset beginning on the line following the ADD command. For instance,

ADD listname DD=ddname IMPORT
//ddname DD *
userid@host.com User Name
userid2@host.com User2 Name
... more address/name pairs, one per line ...
/*

Please see the Site Manager’s Manual for LISTSERV for specific instructions for bulk ADD operations. Bulk ADD operations may also be done via the web interface.

ADDHere(*)

Used with peered lists. Same as ADD, but means “add the user on this peer, do not forward this request to a (possibly) closer peer”. For non-peered lists, is functionally identical to ADD.

CHANGE(*) <listname | *> newaddr
CHANGE(*) <listname | *> <oldaddr | pattern> <newaddr | *@newhost>

Change the currently-subscribed email address for a list or lists.

The first form can be used by any subscriber and results in an OK confirmation request being sent to the new address. This request MUST be confirmed by the new address, exactly as it was entered, or the command will fail. This is the only case where a LISTSERV OK confirmation request must be confirmed by a specific address.

The list owner form does not use the "OK" mechanism but simply applies the standard “Validate=” rules (as for a DELETE command). You can specify a wildcard pattern for the old address and *@newhost for the new address to rename certain addresses to a new hostname. The CHANGE1 template is sent unless you specify QUIET.

Change log entries are made (CHANGE oldaddr newaddr) and there is a CHG_REQ exit point which allows you to examine the operation and reject it if necessary.

DELete(*) <listname | *> user [(options]
DELete(*) listname DD=ddname [BRIEF]

The first syntax is used to remove a single user from one of your lists, or from all local lists if listname is ‘*’ The available options are:

Global	Forward request to all peers
LOCal	Don't try to forward request to closest peer if not found locally
TEST	Do not actually perform any deletion (useful to test wildcard patterns)

The second syntax is used for bulk DELETE operations (similar to a bulk ADD operation). See the Site Manager’s Manual for LISTSERV for details. The single available option is:

BRIEF

Good for deleting wildcard patterns (such as *@*) when you don’t want a “userid@host has been deleted from list xxxx” for each user deleted. Returns instead only a count of the users that were deleted.

Bulk DELETE operations may also be done via the web interface.

EXPLODE listname <(options>

This command is only available on z/VM servers.

Examine a peered list and suggest better placement of recipients, returning a ready-to-submit MOVE job.

BESTpeers n	Suggest the N best possible peers to add.
Detailed	More detailed analysis.
FOR node	Perform analysis as though local node were ‘node’.
PREFer node	Preferred peer in case of tie (equidistant peers).
SERVice	Check to see that service areas are respected.
With(node1 [node2 [...]]]	Perform analysis as though specified nodes ran a peer.
Without(node1 [node2 [...]]]	Opposite effect.

FREE listname <(option>

Release a held list. The single option is:

Global

Forward request to all peers

GET listname <(options>

Get a copy of a list in a form suitable for editing and storing the list and lock it so that other list owners can’t modify it until you store it back (or until you or they issue an UNLOCK command). The options are:

Global	Forward request to all peers.
HEADer	Send just the header; on the way back, only the header will be updated. This is the recommended way to modify your list header via email.
NOLock	Do not lock the list
OLD	Recover the "old" copy of the list (before the last PUT)

HOLD listname <(options>

Hold a list, preventing new postings from being processed until a FREE command is sent. The single option is:

Global

Forward request to all peers

Lists [option]

Additional options available for list owners and moderators:

OWNed	Returns a list of local lists owned by the invoker
MODerated	Returns a list of local lists that are moderated by the invoker

MOVE(*) listname user [TO] node

Move a subscriber to another peer. Do NOT use this command to move users from one list host site to another during migration. It is strictly for moving subscribers from one peer to another peer.

listname DD=ddname

Move several subscribers to various peers

PUT listname LIST

Update a list from the file returned by a GET command. This is the standard “PUT command” or “list PUT” referred to throughout this document.

Use of the PUT command to store a list header with new subscriber data at the bottom (e.g., an attempt to add subscribers “on the fly”) will result in only the header of the list being stored, and in the generation of the following warning:

Warning: New subscriber data was found in the replacement list you sent, possibly due to the use of a signature file with an unusual separator line. If you really meant to update the subscriber data, please resend your request with the word “PUT” replaced with “PUTALL”. For now, only the list header will be updated.

PUTALL listname LIST

This command allows you to PUT an entire list file, that is, the list header followed by the list of subscribers.

Documented Restriction: PUTALL does not work with DBMS lists; only the header information is replaced. Subscriber information in the DBMS table is not changed. For DBMS lists where the subscriber information needs to be replaced in toto, either the DBMS should be manipulated with your regular DBMS tools or you should use ADD IMPORT.

Query listname [WITH options] FOR user

Query the subscription options of another user (wildcards are supported).

WITH options FOR user

Searches all the lists you own for the specified user(s) with the specified option(s).

REINDEX [options] list1 [list2 [...]]]

Documented Restriction: Because it is resource-intensive, the REINDEX command is considered a “maintenance” command as opposed to an “everyday” command, and should not be issued in production environments outside of regularly-scheduled maintenance windows.

The REINDEX maintenance command rebuilds the WWW indexes (default), database indexes, or both for one or more lists. This command requires list owner privileges.

The wildcard * or the literal ALL is supported to mean “all lists”. List owners will be able to rebuild indexes only for their own lists. LISTSERV maintainers may rebuild indexes for all lists on the server.

The available options are:

DATABASE	Reindex only the archive notebooks.
WWW	Reindex only the web archive indexes.
BOTH	Reindex both the archive notebooks and the web archive indexes
IMMEDiate	Execute the operation immediately in the foreground.

Note: By default, web indexes will be rebuilt in the background on LISTSERV Classic HPO unless you specify the IMMEDIATE option. In addition, there is no background reindexing support for LISTSERV Classic non-HPO.

The main reason to use REINDEX is to retroactively add RSS abstracts to an existing list. It may also be useful if an archive file is edited by accident or if there is a corrupt file or the like. LISTSERV Classic non-HPO sites with one or more very large and active list(s) may also wish to run this command when upgrading to HPO.

On non-z/VM systems where there are no web indexes, normally there is no reason at all to rebuild your database indexes, other than in cases of disk corruption or in an upgrade to HPO coupled with the presence of a list with very large archives.

Note: LISTSERV servers being upgraded to version 17.0 from earlier versions MUST execute a full reindex for all lists before the "seamless" archive threading feature introduced in LISTSERV 17.0 will work.

When rebuilding web indexes, BOTH the HTML files AND the INDxxxx files are reindexed. While there may be legitimate reasons for wanting to rebuild the HTML files (template changes, etc), it is NOT recommended to use the REINDEX command to accomplish that, as the overhead involved in rebuilding the INDxxxx files is prohibitive if they do not actually need rebuilding.

With LISTSERV Classic there is no background support, so REINDEX * should be scheduled for “quiet” periods if there are many lists and/or lists with large archives.

While a particular list has its indexes rebuilt, WA browsing accesses will generally fail and/or LISTSERV will throw “listname.html not found" errors. There is no good way to avoid that since the goal is to recreate the entire index structure from scratch, and during that process files will be deleted and not be available until they are rebuilt.

By default, database indexes are reset and will be rebuilt the next time they are needed; this is a fast operation. Under HPO, the IMMEDIATE option may be used to cause an immediate rebuild of all database indexes if absolutely necessary, but remember that the immediate rebuild will block the server from doing anything else until it completes. However, this can be a useful command when migrating an entire server or perhaps just a single list during off hours and it is desired to pre-index everything so that the server is snappy when traffic increases in the morning.

SET(*) listname options <FOR user>

Alter the subscription options for other users (wildcards are supported when setting options for another user or set of users).

Additional options for list owners:

NORENEW \| RENEW	Waive subscription confirmation for this user, or not.
NOPOST \| POST	Prevent user from posting to list, or not.
EDITor \| NOEDITor	User may post without going through moderator, or not.
REView \| NOREView	Postings from user are moderated, even if user is otherwise allowed to post, or not -- but see note, below.

Note: Setting a subscriber to the EDITor option does not confer any list moderation privileges to that subscriber. This setting allows a trusted subscriber to bypass moderation, so that their posts go directly to the list without delay for review by a human moderator. It has no other effect.

The only way to confer full list moderation privileges to a user is to add their address to the Editor= or Moderator= setting(s) in the list header.

REView/NOREView: Typically, the SET listname REView command would be used on a non-moderated list (Send= Public or Send= Private) to set a problem subscriber to individual moderation, while allowing other subscribers to post per the setting of the Send= list header keyword.

On a moderated list (Send= Editor), SET listname REView has no effect, as those who are listed as editors and moderators are not subject to it, and all users other than those explicitly set to the EDITOR personal option (see above) are already being moderated. SET listname REView also has no effect on regular subscribers to a moderated list who have been explicitly set to the EDITor option -- if, on a moderated list, you want to revoke unrestricted posting rights from users who are set to the EDITor personal option, you must explicitly set them to the NOEDITor personal option.

On lists where only certain users, whose email addresses are explicitly specified in the Send= list header keyword, are allowed to send to the list, SET listname REView has no effect. (And neither does SET listname EDITor .)

REVIEW may also be set as an argument to the Default-Options= list header keyword, i.e., so new subscribers start out with this option already set, but this is beyond the scope of the current document. For more information, please see the documentation for Default-Options= in the List Header Keyword Reference.

STats listname (RESET

This command is only available on z/VM servers.

Resets (BITNET) statistics for the list.

This command is entirely obsolete unless you are running LISTSERV-NJE for z/VM on an internal network that still understands BITNET/NJE addressing. With only a couple of known exceptions, every L-Soft LISTSERV site running today runs LISTSERV-TCP/IP.

If you are running LISTSERV on Windows or on a unix variant, the response to a STATS listname command will be, simply

The STATS command has not yet been ported to this environment.

Modern list-level statistics and history reports are available via the web interface and have taken the place of this command. Please see the List Activity Reports menu item under the List Management section in the LISTSERV web interface.

UNLOCK listname

Unlock a list after a GET, if you decide not to update it after all, or unlock a list if it has been locked by another list owner or by the LISTSERV maintainer.

Note that if you are not the person who originally locked the list, it is considered good practice to ask the person who originally locked the list whether or not they are done with the list before you unlock it.