Pine is a user-agent for reading, sending, and managing
electronic messages. It was originally developed at the
University of Washington with novice users in mind, but can be
tailored to accommodate the needs of more experienced users. The
UNIX, DOS, and Windows versions are maintained by the Computing &
Communications group at the University of Washington and can be
obtained from ftp.cac.washington.edu via anonymous FTP. A mailing
list for Pine is maintained as pine-info@cac.washington.edu;
however, bugs found in the PMDF version of Pine should be
reported to support@process.com.
Pine has a full-screen interface which uses one-character
mnemonic commands and control sequences for its command input.
You do not have to hit the RETURN or ENTER key to finish a
command. A command menu is always present at the bottom of the
screen, and help is only one keystroke away. It is intended that
Pine can be learned by exploration and the browsing of extensive,
context-sensitive on-line help provided within Pine, but some
basic concepts to get a new user started are discussed below.
1 – Getting Started
To start PINE, use the PMDF PINE command:
$ PMDF PINE
Command line qualifiers for pine are not supported. Pine is
exited using the QUIT command, Q.
If you want to get started using pine, DON'T READ ANY FARTHER!
Just start pine and try it. The help within pine should be more
useful in actually operating pine than the configuration and
OpenVMS-specific details covered in the topics here.
NOTE
System managers should see also under PMDF Pine System
Configuration.
1.1 – Terminal Characteristics
Pine uses the OpenVMS SMG$ run-time library to implement terminal
I/O. Pine will be unable to start if the terminal type is unknown
to SMG$. If pine dies unexpectedly, it is possible that the
terminal characteristics might need to be reset. Specifically
you might need to issue the command:
$ SET TERMINAL/NOPASTHRU/LINE_EDIT
so as to restore your terminal characteristics.
1.2 – Function Key Mode
Pine has a function key mode which is enabled by the USE-
FUNCTION-KEYS option in the pine resource file. When enabled,
the VT numeric keypad keys are mapped to the function keys F1
through F12 as follows:
o PF1-PF4 are mapped to F1-F4,
o KP5-KP9 are mapped to F5-F9,
o KP0 is mapped to F10,
o KP1 is mapped to F11, and
o KP2 is mapped to F12.
In addition, the top row function keys F6 to F12 are mapped to
their namesakes. The HELP key is mapped to F1.
The MINUS key on the numeric keypad, KP-, can be used in place
of the control, CTRL, key. However, it is used as a two key
sequence. For example, to enter CTRL/A, you would press the two
keys KP- followed by A.
One consequence of using pine in function key mode is that you
can only choose from twelve commands at any given time. That
is, whereas in alphabetic key mode you can press a key for a
command even though the command is not visible on the bottom of
the screen, in function key mode you must toggle to the screen
where the command is visible.
2 – General Concepts
Pine is an IMAP (Internet Message Access Protocol) client and
POP (Post Office Protocol) client which can access local VMS MAIL
mail files as well as other mail files served by an IMAP server
or POP3 server.
If only local mail is to be accessed, no network connection
is created, and no IMAP server or POP server is needed on the
local system. If your system does not have any TCP/IP software
installed, then you will receive an error message when you
attempt any operation requiring TCP/IP access. To access mail
files on a remote OpenVMS system, an IMAP server such as the PMDF
IMAP server, or a POP server such as the PMDF POP server, must be
running on that remote system. To access mail files on a remote
UNIX system, the remote system must have an IMAP daemon (server)
or POP daemon (server) running.
Pine is also an NNTP (Network News Transport Protocol, RFC 977)
client, and can be used to read news from NNTP servers like the
ANU News program or many common UNIX NNTP servers. Of course, you
have to know the name of one such system before you can use this
capability. Ask your system or network manager for help.
The pine view is that messages are stored in folders, and
folders are stored in folder collections. Folder collections
can be physically located on the local system, or on any remote
system with an IMAP server. Regardless of what system a folder
collection is physically located on, a pine user sees it as
just another folder collection: a pine user can read messages
in any of their folder collections and can save (move) messages
between different folder collections. See under PMDF Pine Folders
and Folder Collections for more details on folders and folder
collections.
Or a read-and-delete-only pine folder can correspond to the "new
messages" folder on a remote system with a POP3 server. (The
POP3 protocol does not provide access to multiple folders-it only
provides access to the "new" messages, usually those in a special
"new" sort of folder. The POP3 protocol also does not allow for
moving messages into a POP3 folder.)
3 – Configuration Files
The PINE RESOURCE file is the most important file used by Pine.
This file contains the configuration options settable by a
user. See under PMDF Pine Configuration_files Resource File for
details.
Users can have address books in pine, with nicknames for long
addresses or mailing lists. See under PMDF Pine Configuration_
files Addressbook for details.
When using pine to read news group messages, a file is required
listing the names of news groups you read; by default, pine uses
the file PMDF_INIT:NEWSRC. See under PMDF Pine Configuration_
files News Groups File for details.
When reading MIME messages, pine uses a MAILCAP file to
determine how to display the message parts. See under PMDF Pine
Configuration_files Mailcap Files below for details.
When sending attachments, pine consults a file to determine what
MIME labelling to use on the attachment parts. By default, the
file consulted is PMDF_INIT:MIME.TYPES, or as specified by the
MIMETYPE-SEARCH-PATH option setting in the pine resource file.
Pine also has other optional configuration files to control
filtering incoming or outgoing message text, etc.
NOTE
System managers should also see under PMDF Pine System_
configuration Configuration Files for information on
tailoring the the pine environment on the system via
additional system-level pine configuration files.
3.1 – Resource File
Pine uses a resource file to keep track of its configuration,
user preferences, and other information. By customizing the
option settings in your PINE RESOURCE file, you can customize
your pine environment to your liking. Generally the best way to
set or change option settings in your PINE RESOURCE file is from
within pine, via the CONFIG option of the SETUP submenu accessed
from pine's main menu. (Context sensitive help is available
within pine for each such configurable item so you can get hints
on setting your options.) However, the PINE RESOURCE file is
a normal text file, so it is also possible to modify the PINE
RESOURCE file using a text editor.
3.1.1 – Location
On OpenVMS systems, the Pine resource file is named PINE.PINERC
and is located in the PMDF_INIT: directory. By default, PMDF_
INIT is a logical which translates to SYS$LOGIN. Users wanting
to keep their pine resource file elsewhere can redefine the PMDF_
INIT logical. The logical name PINERC can be used to specify an
alternate file name. For instance, the definition
$ DEFINE PINERC PINE.RC
causes the file name PINE.RC to instead be used, thereby
accessing the file
PMDF_INIT:PINE.RC
The definition of the PINERC logical must not contain a device or
directory reference.
3.1.2 – Format
In the Pine resource file, any line starting with # is considered
to be a comment line. Lines not beginning with # contain settings
for configuration options using the format
option=value[,value,...]
All values are strings; quotes can be used around any value.
If a value is absent, then the associated option is not set
and a system-wide default setting, if there is one, will be
used instead. For some options, only the values YES and NO are
allowed.
A line beginning with a space or tab is considered to be a
continuation of the previous line.
3.1.3 – Dollar Sign
The dollar sign, $, has a special meaning in the Pine resource
file: it means that the word following it is an "environment
variable", i.e., a DCL symbol or logical name, the value of which
is then substituted at that point in the file. To specify $ in a
value, you need to prefix it with a backslash; e.g.,
SYS\$LOGIN:SIGNATURE.TXT
3.2 – Addressbook
You can have one or more addressbooks in Pine. In addition to a
personal addressbook, one or more global, read-only addressbooks
can be set up (for sharing between multiple users). The names
of your personal addressbooks are specified in the Pine resource
file by the ADDRESS-BOOK option. Normally, this option is set
and modified from within Pine by using the SETUP menu and then
selecting the Addressbook menu; it can, however, also be set by
manually editing the Pine resource file. The built-in default
file name used for an addressbook PMDF_INIT:PINE.ADDRESSBOOK.
A "lookup" file is used to speed access to the addressbook. The
lookup file has the same name as the addressbook, with -LU as
suffix; e.g., PMDF_INIT:PINE.ADDRESSBOOK-LU. The lookup file
is generated automatically by Pine. Global addressbooks can be
specified using the GLOBAL-ADDRESS-BOOK option.
3.2.1 – Addressbooks and PMDF Personal Alias Database
A limited interface between Pine's address books and PMDF's
personal alias database has existed since Pine 3.91. When you
add an address to one of Pine's address books using Pine's
ADDRESS BOOK menu, it will also be added to your personal alias
database, overwriting any existing entry of the same name. The
Pine "nickname" is the alias name used in PMDF's personal alias
database and the e-mail address is the corresponding value for
the alias. Adding or deleting Pine's address lists has no effect
on PMDF's personal alias database.
When you delete an address in one of Pine's address books, it is
also deleted from PMDF's personal alias database if present.
The J command can be used to dump the entire current addressbook
into your PMDF personal alias database. If no personal alias
database exists, it will be created.
3.3 – News Groups File
If you use the news reading capability in Pine to talk to a NNTP
server, then you need to have a NEWSRC. file in the PMDF_INIT:
directory, or a newsrc file with a non-default name as selected
by your NEWSRC-PATH Setup Config option. This file contains the
names of news groups you read. Pine updates it when you delete
a message in the news group. Deleting a message in news does not
really delete it, but simply makes the message unavailable to
you when you next read the associated news group. The format of
this file is one line per news group, with the lines having the
format:
newsgroupname:[message,...]
where MESSAGE is either a number or a range of numbers (e.g.,
1-3).
3.4 – Mailcap Files
When reading MIME messages, Pine uses a mailcap file to determine
how to display message parts. Mailcap files are described in RFC
1524, a copy of which can be found as PMDF_ROOT:[DOC.RFC]RFC1524.
Or see the PMDF User's Guide which gives a brief overview of
mailcap files.
The default mailcap filename is MAILCAP. in the PMDF_INIT
directory, unless the logical name PMDF_MAILCAP_DIR is defined,
in which case the list of directories defined by PMDF_MAILCAP_DIR
is searched for the file MAILCAP., in the order listed. The first
entry found in the list of files will be used. For instance, with
the following PMDF_MAILCAP_DIR definition, PMDF will use a user's
own mailcap file, if they have one, and if the user does not have
a personal mailcap file, PMDF will use a mailcap file in the PMDF
table directory:
$ DEFINE/SYSTEM PMDF_MAILCAP_DIR PMDF_INIT:,PMDF_TABLE:
Note that a trailing colon is necessary if logical names are used
because the filename MAILCAP. is appended to whatever value you
have specified.
4 – Folders and Folder Collections
The Pine view is that messages are stored in folders, and
folders are stored in folder collections. Folder collections
can be physically located on the local system, or on any remote
system with an IMAP server. Regardless of what system a folder
collection is physically located on, a Pine user sees it as just
another folder collection: a Pine user can read messages in any
of their folder collections and can save (move) messages between
different folder collections.
4.1 – Folders
Each mail message is stored in a folder. A Pine folder is
equivalent to a VMS MAIL folder in a VMS MAIL mail file.
While both Pine and VMS MAIL folder names are case sensitive,
Pine users must be much more mindful of this fact. (VMS MAIL
automatically converts folder names to upper case unless you
surround the folder name with quotes.)
For VMS MAIL files, a new folder is automatically created the
first time a message is saved to it; a folder is automatically
deleted when all messages in the folder are deleted. So when you
use the Create folder command in Pine to create a new folder, the
folder will be created with a placeholder message in it.
4.2 – Collections
A folder collection is a folder specification for a collection
of folders on one system. For example, it can be all of your
VMS MAIL folders which have the name prefix INFO-, or it can be
all of your UNIX mail folders on a system called foo.bar.com, or
it can be all of your VMS MAIL folders in a different mail file
than you normally use. You can access multiple different folder
collections from within Pine.
By default, PMDF Pine knows only about the local folder
collection, corresponding to your VMS MAIL mailbox. The use
of additional folder collections is controlled by the FOLDER-
COLLECTIONS option in your Pine resource file. Normally, this
option is set from within Pine by using the SETUP menu and then
selecting the L (collectionList) menu. However, the option can
also be set by manually editing your Pine resource file.
4.2.1 – Syntax
The setting of the FOLDER-COLLECTIONS option can be a list of
values, where each value specifies a folder or folders on the
local system or accessible via an IMAP server, or specifies the
new mail folder accessible via a POP3 server. Folders on the
local system or accessible via an IMAP server are specified using
the format:
optional-label {imaphost}optional-file[view]
or
optional-label {imaphost:port/user=username}optional-file[view]
OPTIONAL-LABEL is a label which will be displayed by Pine in
place of the full name of the folder collection.
The optional field IMAPHOST is the name of a host where the
mail file resides. IMAPHOST can be any system which has an IMAP4
server, and need not necessarily be an OpenVMS system.
The optional PORT specification can be included if you want to
connect to a port other than the default (for IMAP) of 143.
The optional USERNAME can be included if you want to log in to
the IMAPHOST under a different account name.
The optional field OPTIONAL-FILE is the file specification
of a mail file. If OPTIONAL-FILE is omitted but IMAP-HOST is
specified, then the default mail file on the remote IMAPHOST
system will be used. If neither OPTIONAL-FILE nor IMAP-HOST is
specified, then your local default mail file will be used.
When OPTIONAL-FILE is specified for an OpenVMS host locally or
remotely running PMDF's legacy IMAP server, it must have the
format
#disk:<directory>mailfile.mai#
where DISK, DIRECTORY, and MAILFILE.MAI specify the full path,
disk, directory, and file name, to the mail file. For instance,
to select the mail file MEMOS.MAI of DISK$USER1:[BOB], you would
specify
#DISK\$USER1:<BOB>MEMOS.MAI#
Finally, the VIEW field controls which folders from the mail file
are part of the collection. If specified as being empty, [],
then all folders from the mail file are treated as part of the
collection. Wild cards can be used to select folders matching a
pattern. For example, [INFO-*] would select all folders beginning
with the string INFO- from the mail file. Again, note that folder
names are considered to be case sensitive.
For POP3 access to a new mail folder on a remote system, the
format is:
"foldername" {pop3host/POP3}INBOX
or
"foldername" {pop3host/POP3/USER=username}INBOX
where FOLDERNAME is the name by which Pine will refer to the
folder, POP3HOST is the name of the system running the POP3
server, and USERNAME is the name under which to log in to the
remote POP3 server.
4.2.1.1 – Example
An example of setting the FOLDER-COLLECTIONS option in your
Pine resource file, PINE.PINERC, to a list of several folder
collections is:
folder-collections=local [],
archive #DRA0:<JONES.ARCHIVE>OLDMAIL.MAI#[],
remoteVMS {vax.example.com}#DUA2:<JONES.MAIL>MAIL.MAI#[INFO*]
remoteUNIX {sun.example.com}mail/[]
In the above example, four collections with the names local,
archive, remoteVMS, and remoteUNIX are created. local consists
of all folders in the local default mail file; archive consists
of all folders in the mail file DRA0:[JONES.ARCHIVE]OLDMAIL.MAI;
remoteVMS consists of all folders whose name begin with INFO
in the mail file DUA2:[JONES.MAIL]MAIL.MAI on the remote host
vax.example.com; and remoteUNIX consists of all folders from the
mail directory MAIL/ on the remote system sun.example.com.
4.2.2 – Saving Messages
When saving a message to a different folder collection, you can
select PREV COLLECTION or NEXT COLLECTION to get to the folder
collection you want to save to. Here, "Prev" is an abbreviation
for "Previous". By default, the first folder collection is the
one to save to.
For local or remote OpenVMS servers, you can also specify the
file name where the folder resides directly as
#disk:[directory]mailfilename#foldername
when prompted with the folder name. If you are saving to the same
file in the folder collection, then only the folder name itself
is needed.
5 – OpenVMS Notes
In the following subsections, some issues specific to Pine on
OpenVMS are discussed.
5.1 – Expunging
When accessing mail locally, the Pine Expunge command moves all
messages marked for deletion to the VMS MAIL WASTEBASKET folder.
In addition, it performs the equivalent VMS MAIL PURGE command
only when your VMS MAIL profile allows for AUTO_PURGE. If you
have set NOAUTO_PURGE, then the deleted messages are left in the
WASTEBASKET folder. However, should you expunge the WASTEBASKET
folder, then the VMS MAIL PURGE function will be performed.
Purged message space is not available for reuse until a reclaim
operation is performed. When the amount of deleted message space
in the mail file exceeds 32,767 bytes, a reclaim operation is
automatically done by the Expunge command.
NOTE
Pine never compresses your mail file.
5.2 – New Mail Updates
By default, Pine automatically checks for new mail every 2.5
minutes (150 seconds). This interval is settable per user as
the MAIL-CHECK-INTERVAL configuration option (unless the system
manager choose to fix its value in the PINE.CONF-FIXED file). You
can also force a refresh of the folder by pressing the DOWN arrow
key four times at the last message of the Index screen or by
pressing CTRL/L. A folder is also refreshed whenever you expunge
it. When you force a check, and you have no new mail, Pine will
report the last message as new mail even though it is not new.
5.3 – VMS MAIL Profile
When accessing mail locally, Pine uses the same VMS MAIL mail
file as VMS MAIL and PMDF MAIL, so you can use any of these
programs interchangeably and access the same messages stored
in a VMS MAIL mail file.
Pine uses your VMS MAIL profile settings as follows:
AUTO_PURGE
When AUTO_PURGE is set, expunged messages will be purged from
your mail file, i.e., purged from your WASTEBASKET folder.
COPY_SELF
Your VMS MAIL COPY_SELF settings are honored by Pine when sending
or replying to messages.
MAIL_DIRECTORY
The MAIL_DIRECTORY profile setting is used when you do not
specify a filename with your folder specification.
NOTE
Pine should not be used on an account whose login device
is a search list and has MAIL_DIRECTORY defined as a
subdirectory.
PERSONAL_NAME
Your VMS MAIL PERSONAL_NAME setting will be used if none is set
in Pine's configuration file.
WASTEBASKET_NAME
As with VMS MAIL, the WASTEBASKET_NAME setting is used for your
wastebasket folder name.
6 – System Configuration
PMDF Pine uses PMDF extensively. PMDF must be installed and
configured on the system for Pine to function. Pine uses PMDF
to send mail, to parse addresses, and to save copies of messages
you have sent, if the Pine DEFAULT-FCC option is set. Once PMDF
is configured and installed on a system, PMDF Pine is usually
ready for use, although see under PMDF Pine System_configuration
UCX Emulation and PMDF Pine System_configuration Subprocess Quota
for descriptions of two installation issues to check, and see
under PMDF Pine System_configuration Configuration Files for a
description of tailoring the Pine environment on a system wide
basis.
In particular, note that Pine does not, by default, use IMAP
to talk to your local system, so it is not necessary to have
an IMAP server running on your system just to use Pine. (Only
if a user were to specifically request that Pine treat the
local system as if it were instead a remote system with an IMAP
server, by specifying the IMAP-HOST field when accessing a folder
collection, would PMDF Pine attempt to make an IMAP connection to
the local system.)
Pine is installed by PMDF with the privileges SYSPRV and CMKRNL.
Without those privileges, users can not send mail, although they
can still read mail.
6.1 – UCX Emulation
UCX$IPC_SHR is an executive-mode logical name pointing to a
shareable image supplied by your TCP/IP vendor. If this logical
is not defined, then either TCP/IP is not installed, or, in the
case of a package other than DEC's TCP/IP Services for OpenVMS
(a.k.a. UCX), UCX emulation was not installed when the package
was installed. In order to use the TCP/IP functionality of
PMDF Pine, this logical must be defined and be pointing to the
appropriate image for your TCP/IP package. Moreover, the image
must be installed as a known image,
$ INSTALL UCX$IPC_SHR /OPEN/SHARED
If you are running Pine on a system without any TCP/IP software,
a dummy shareable image PMDF_EXE:UCX_DUMMY.EXE is provided with
PMDF. Your system manager should define a system-wide, executive-
mode logical named UCX$IPC_SHR which points to it and then
install it:
$ DEFINE/SYSTEM/EXEC UCX$IPC_SHR PMDF_EXE:UCX_DUMMY.EXE
$ INSTALL UCX$IPC_SHR /OPEN/SHARED
NOTE
If you install any TCP/IP package later, remember to
deassign the logical name or you won't have a functional
TCP/IP.
The definition of the logical and installation of the image
should be made part of the system startup procedure. Note that
the installation of the image can be effected through the site-
supplied PMDF_COM:SITEIMAGE.DAT file which uses the same format
as the Process-supplied PMDF_COM:PMDFIMAGE.DAT file.
6.2 – Subprocess Quota
Pine uses subprocesses to perform several of its tasks. As such,
users without subprocess quota cannot do any of the following:
o use a customized printing command,
o view image or video attachments,
o use the spell checker, or
o use an alternate editor.
A side effect of using subprocesses in Pine when you have a
remote IMAP connection is that the connection might timeout while
waiting for a subprocess to complete. This is especially likely
when using an alternate editor to compose a message.
6.3 – Configuration Files
A system manager can tailor Pine's environment on a per system
basis by the use of files described below. These files should all
be world readable.
PMDF_TABLE:PINE.CONF
This file is shipped with PMDF and contains a default system-wide
configuration for Pine. A new version is shipped with every PMDF
release, so you should keep a copy of your customizations. This
default configuration provides for one folder collection with the
default mail file on the local system.
PMDF_TABLE:PINE.CONF-FIXED
You can create this Pine resource file and place in it options
which you do not want users to be able to change or override.
This file, as supplied with PMDF, initially contains the same
information as hardcoded in the program for the BUGS-ADDRESS and
BUGS-FULLNAME options with the local Postmaster being the one to
receive the bug reports. You can change it to a different address
if necessary, but we suggest you direct it to a local support
address.
PMDF_TABLE:PINE.INFO
When this file exists, the information contained in it is
presented to the user as LOCAL SUPPORT CONTACTS from the main
menu's help screen.
PMDF_TABLE:MIME.TYPES
This file provides a basic set of file extension to MIME type
mappings. Users can supplement or override these defaults with
their own choices in their own file, via the MIMETYPE-SEARCH-PATH
option in their Pine resource file.
6.3.1 – Precedence of Settings
There are potentially four sources of configuration settings
which are shown below in decreasing order of precedence:
1. Unchangeable, system-wide settings from the PMDF_
TABLE:PINE.CONF-FIXED file.
2. Per-user settings from the user's PMDF_INIT:PINE.PINERC file.
3. System-wide settings from the PMDF_TABLE:PINE.CONF file.
4. Default Pine values.
One exception to the above precedence scheme is the FEATURE-LIST
option which is cumulative. In order to turn off a feature, you
have to negate it by prepending NO- in front of an individual
feature.