.ls 1
.ch "Other Notesfile Utilities"

	The notesfile distribution includes utility programs to
provide hard copy output,
additional interfaces to user programs,
and
statistics.
They are described below.

.se "Hard Copy Output"

	The program ``nfprint'' sends to standard output a nicely formatted listing of
the notesfile in its command line.
Its format is:

	nfprint [-lnn] [-p] [-t] topic [ note# ] [ note#-note# ] [ ... ]

The ``-l'' option specifies an alternate page size (the default is
66).
The optional note number list specifies that only
certain notes of the notesfile
are to be printed.  The list can specify individual notes and ranges.
The notes are printed in the order specified.

	The -p option specifies that each notestring is to begin
on a new page.
The -t option signifies that only a table of contents is to be
generated.

.se "Piped Insertion of Notes"

	The nfpipe program enters text from the standard input into a
notesfile:

	nfpipe topic [-t title] [ -d ] [ -a ]

The -t option allows specification of a title.  The -d and -a options
specify the director and anonymous flags respectively (if available).
If no title is specified, one is manufactured from the first line
of the note.

.se "User Subroutines"

.ss "Nfcomment"

	The nfcomment subroutine is callable from a user's C program. It
allows any user program to enter text into a notesfile:

	nfcomment (nfname, text, title, dirflag, anonflag)

.KS
.br
The parameters are:

.br
.ls 1
	char *nfname;	/* name of notesfile */
.br
	char *text;	/* null terminated text to be entered */
.br
	char *title;	/* if non-null, title of note */
.br
	int dirflag;	/* != 0 -> director flag on (if allowed) */
.br
	int anonflag;	/* != 0 -> anonymous note (if allowed) */
.br
.ls
.KE

	If the *text pointer is NULL, the text of the note will be read
from standard input.
If no title is specified the subroutine will manufacture a title
from the first line of the note.
This routine is useful for error reports, user comments
about programs, and automatic logging of statistics or internal states.

	This routine can be loaded with a C program by specifying `-lnfcom'
on the `cc' command line.

.ss "Nfabort"

	Nfabort allows users to generate core images of their
process, save the core image in a ``known'' place,
and
log the fact in a notesfile.
This proves useful for intermittent failures;
when a program does crash,
a core image is placed in an appropriate place and a
message is placed in a notesfile.
The programmer regularly scans the notesfile and can examine
the core dump at his leisure.
Some of the problems of recreating conditions which cause errors
are eliminated by this approach.

	Nfabort is callable from the user program. It accepts
the following parameters:

	nfabort (nfname, message, title, cname, exitcode)

.KS
.br
The parameters are:

.br
.ls 1
	char *nfname;	/* name of notesfile */
.br
	char *message;	/* text string to insert */
.br
	char *title;	/* title of the message */
.br
	char *cname;	/* prefix for core image destination */
.br
	int exitcode;	/* code for exit() */
.ls
.KE

	The core image is placed in the file specified by
concatenating the ``cname'' argument and a unique 
integer (the process id of the current process).
The notesfile specified by the ``nfname'' parameter
receives a note whose body consists of the text pointed
to by ``message'' and a line telling the complete pathname
of the core image.
The title of the note is specified by the ``title'' 
parameter.
After the core image is generated and the
note has been written, 
nfabort terminates with the exit code specified
by the ``exitcode'' parameter.

	Nfabort generates default values for each of
the string parameters if NULL pointers are passed.
This routine can be loaded with a C program by specifying `-lnfcom'
on the `cc' command line.


.se "Statistics"

	The notesfile system keeps statistics on where notes and responses
originate, the number of network accesses, duplications and orphaned 
responses.
Combined with the use of the log maintained by the notesfile
networking software,
monitoring notesfile traffic is
quite easy.

	The -s option specifies that only a summary is to be produced,
skipping the individual reports.
Wildcard constructs with '*', '?', '[', and ']' are
recognized by nfstats.
Invoke the statistics program with:

		nfstats [ -s ] topic1 [ ... ]

Typical output is:

.KS
.nf
.ls 1
             rbenotes on uiucdcs at  6:24 pm  May  7, 1982
.ta 1.5i 2.25i 3.0i
	NOTES	RESPS	TOTALS
Local Reads     	359	115	474
Local Written   	53	55	108
Networked in    	0	0	0
Networked out   	0	0	0
Network Dropped 	0	0	0
.TA
Network Transmissions: 0   Network Receptions: 0
Orphaned Responses Received: 0    Entries into notesfile: 109
Total time in notesfile:   66.57 minutes  Average Time/entry:   0.61 minutes
Created at 10:04 pm  May  5, 1982, Used on 3 days
.ls
.fi
.KE

	A combined set of statistics is produced at the end of listings
of more than one notesfile.
The statistics are largely self explanatory.

.se "Checking for New Notes"

	The checknotes program
checks the notesfiles specified by the NFSEQ environment 
variable to determine if there are new notes.
The exit code is arranged to make the program useful in shell scripts:
0 (TRUE) is there are new notes, 1 (FALSE) otherwise.

	Use the ``-q'' option to receive a message

		There are new notes

if one or more of the notesfiles have notes/responses written since
the user's last entry time into that notesfile.

	The ``-n'' option is similar to the ``-q'' option, with the exception
that it yields output when there are no new notes. The output
of checknotes with the ``-n'' option is:

		There are no new notes

	Use ``-v'' to print the name of each notesfile with new 
notes/responses.
The ``-s'' option is suitable for use in conditional
expressions in shell scripts; no output is generated by this option.

.se "Mail to Notesfiles"

	Some mailers  (like 4.2 BSD's \fIsendmail\fP)
allow mail to be directed to specific programs.
The nfmail program facilitates sending mail to notesfiles.
The subject line of the mailed letter is extracted and used as the
title of the note.
Nfmail extracts the author's name and system
from the body of the letter.
Subject lines are examined for ``Re:'' prefixes and, if they
exist, are used in an attempt to link the letter as a reply to
an existing base note.

	To send mail addressed to ``somenotes'' 
to the notesfile ``somenotes'' with the 4.1 Bsd /etc/delivermail
add the following line to the file /usr/lib/aliases.
The second line shows the general format for /usr/lib/aliases entries
which feed a notesfile.
If the Notesfile utilities are stored in a different directory, the
path name should be changed appropriately.

.in +.75i
.nf
somenotes: ``|/usr/spool/notes/.utilities/nfmail somenotes''
mailaddress: ``|/usr/spool/notes/.utilities/nfmail anotesfile''
.fi
.in

.se "Modifying Access Rights for Many Notesfiles"

	It is convenient to add entries to a large number of
access lists simultaneously.
The nfaccess program adds an access specification to each of
a specified list of notesfiles.
Nfaccess functions similarly to chmod(1).
Nfaccess is invoked as:

	nfaccess <access-right> notesfile [notesfile ...]

The ``access-right'' is formatted as: ``type:name=mode''.
Type can be any of ``user'', ``group'', or ``system'';
capitalized variants are also valid.
The ``type:'' specification can be omitted.
``User'' is assumed in these cases.
The ``mode'' field consists of a sequence of the
characters ``d'', ``r'', ``w'', ``a'' and ``n''.
These indicate director, read, write, answer (respond) and null
access respectively.

	Nfaccess requires user and group entries to be valid
by looking for them in /etc/passwd and /etc/group.
System entries are not checked for validity.
Nfaccess will add the entry to the access list of the specified
notesfiles.
If an entry for that particular user, group or system exists,
the new access right replaces the old access rights.
The computed mode is an absolute mode; the previous value in
the access list (if any) is replaced with the new mode.

	Any user can run the nfaccess program.
Nfaccess refuses to modify access lists for any notesfile
where the user is not a director.
The nfaccess program is stored in the notesfile utility
directory, typically ``/usr/spool/notes/.utilities''.

	Nfaccess is often used to remedy missing permissions
in a number of notesfiles.
One example is when the notesfile administrator is replaced;
nfaccess is used to grant director access to the appropriate
notesfiles (usually most of them).
As new notesfiles are created, the access list can be tuned
by placing lists of access-rights in the file
``/usr/spool/notes/.utilities/access-template''.
These access-rights are added to the default access list
of newly created notesfiles.
