<define_book_name>(userguide\NEWSRDR User's Guide)
<FRONT_MATTER>(NEWSRDR_INST_1)

<TITLE_PAGE>
<TITLE>(NEWSRDR Installation Guide)
<ABSTRACT>(May, 1994)
<P>This manual describes the installation of NEWSRDR, an NNTP-based news
reader for VMS systems.
<ENDABSTRACT>
<REVISION_INFO>(This is a revised manual.)
<REVISION_INFO>(Operating System and Version:\VAX/VMS V5.0 or later; 
OpenVMS AXP V1.0 or later)
<REVISION_INFO>(Software Version:\NEWSRDR V4.8)
<ENDTITLE_PAGE>(Matthew Madison<LINE>MadGoat Software)

<COPYRIGHT_PAGE>
<PRINT_DATE>(25 May 1994)
<p>Permission is granted to copy and redistribute this document for
no commercial gain.
<P>The information in this document is subject to change without notice 
and should not be construed as a commitment by the author.
The author assumes no responsibility for any errors that 
may appear in this document.
<p><emphasis>(DISCLAIMER:\bold)   The author, the author's employer, and
    MadGoat Software make no representations or warranties with
    respect to the  contents hereof and specifically disclaim any
    implied warranties of merchantability or fitness  for any particular purpose.
<P>The following are trademarks of Digital Equipment Corporation:
<TABLE>
<TABLE_ATTRIBUTES>(SINGLE_SPACED)
<TABLE_SETUP>(3\20\20)
<TABLE_ROW>(AXP\DEC\OpenVMS)
<TABLE_ROW>(VAX\VMS\)
<ENDTABLE>
<p>MultiNet is a registered trademark of TGV, Inc.
<COPYRIGHT_DATE>(1993, 1994\MadGoat Software.  All Rights Reserved.)
<ENDCOPYRIGHT_PAGE>
<CONTENTS_FILE>
<PREFACE>(\NEWSRDR_INST_2)
<p>The NEWSRDR utility provides an interface to USENET news that may be more
familiar to VMS users.  NEWSRDR attempts to follow the conventions of the
VMS MAIL utility in its presentation and command structure whenever possible.
<head1>(Intended Audience\NEWSRDR_INST_3)
<p>This manual is intended for system managers responsible for installing
and setting up NEWSRDR.
<head1>(Document Structure\NEWSRDR_INST_4)
<p>This document consists of two chapters.  Chapter 1 describes the
installation of NETLIB, the network interface library used by NEWSRDR.
Chapter 2 describes the installation and configuration of NEWSRDR.
<head1>(Related Documents\NEWSRDR_INST_5)
<p>The <reference>(userguide) describes how to use NEWSRDR and all
NEWSRDR commands.
<p>Internet RFC 1036, <emphasis>(Standard for
Interchange of USENET Messages) explains the structure
of USENET news articles.  RFC 977,
<emphasis>(Network News Transfer Protocol), describes NNTP news service.
The Internet RFC's are available via anonymous FTP from NIC.DDN.MIL.
<head1>(MadGoat Software Mailing Lists\mgswls)
<P>MadGoat Software has set up the following mailing lists for discussions
and support of its products:
<LIST>(UNNUMBERED)
<LE><EMPHASIS>(Info-MadGoat@wkuvx1.wku.edu)
<P>
        Discussion of MadGoat Software products by users and MadGoat
        developers.  To subscribe, send a message to
<EMPHASIS>(Info-MadGoat-Request@wkuvx1.wku.edu)
        with the word SUBSCRIBE in the first line of the body of the
        message.
<LE><EMPHASIS>(MadGoat-Announce@wkuvx1.wku.edu)
<P>
        Announcements of new releases and new products from MadGoat.
        To subscribe, send a message to
<EMPHASIS>(MadGoat-Announce-Request@wkuvx1.wku.edu)
        with the word SUBSCRIBE in the first line of the body of the
        message.
<LE><EMPHASIS>(MadGoat-Bugs@wkuvx1.wku.edu)
<P>
        Address for reporting bugs in MadGoat Software products.  Please
        include the name of the package and version in the subject header
        of the message, so the report can be more easily directed to the
        appropriate developer.
<ENDLIST>

<PREFACE_SECTION>(OpenVMS AXP V1.5 Compatibility Note\v15_bug)
<p>
A bug in the DEC C Run-Time Library under OpenVMS AXP V1.5 will cause
NEWSRDR to exit with an access violation (ACCVIO) when it tries to signal
an error.  A fix for this bug is available from Digital customer support.
The identification of this patch is CSC Patch #378 (CSCPAT_0378); DSNlink
users can obtain this patch electronically using DSNLINK VTX.

<ENDPREFACE>
<ENDFRONT_MATTER>
<CHAPTER>(Installing NETLIB\NEWSRDR_INST_6)
<note>
NEWSRDR can use either a Berkeley socket library or the provided
NETLIB library for communicating with the NNTP server over TCP/IP.
If your TCP/IP package supports a Berkeley socket interface, you do
not need to install NETLIB for use with NEWSRDR, and should skip this
chapter.
<endnote>
<p>NEWSRDR can use the NETLIB library for communicating on a
TCP/IP network.  NETLIB is a layered library that is used by
several of the network utilities available from MadGoat Software.
It provides basic TCP and UDP services layered on top of one
of several vendors' TCP/IP packages. As of this writing, NETLIB
supports CMU-Tek TCP/IP, DEC TCP/IP Services for VMS, Process
Software's TCPware, TGV MultiNet, and The Wollongong Group's WIN/TCP and
PathWay products.

<head1>(Determining Whether NETLIB is Installed\NEWSRDR_INST_7)
<p>You only need to install the NETLIB libraries if they have not
already been installed on your system.  You can check for NETLIB's
existence with the commands
<interactive>
<s>($ )<u>(SHOW LOGICAL NETLIB_DIR)
<s>($ )<u>(SHOW LOGICAL NETLIB_SHRXFR)
<s>($ )<u>(SHOW LOGICAL NETLIB_SHR)
<endinteractive>
<p>If these commands succeed, and the files that they point to exist,
then NETLIB is installed and you can skip to the next chapter.
<head1>(Installing NETLIB System-wide\NEWSRDR_INST_8)
<p>NETLIB is provided in a distribution kit suitable for installation
with VMSINSTAL.  The release notes in the A save set of the distribution
kit describe installation requirements for NETLIB.  You can retrieve
the release notes by using OPTIONS N on VMSINSTAL:
<interactive>
<s>($ )<u>(@SYS$UPDATE:VMSINSTAL NETLIB disk:[directory] OPTIONS N)
<endinteractive>
<p>Once NETLIB has been installed, it should be started by invoking
its startup command procedure:
<interactive>
<s>($ )<u>(@SYS$STARTUP:NETLIB_STARTUP)
<endinteractive>
<p>This should be done from a suitably privileged account, before
you try to install NEWSRDR.
<head1>(Personal NETLIB Installation\NEWSRDR_INST_9)
<P>If you are not a system manager but still want to use NEWSRDR, you
can install a copy of NETLIB for your own personal use.  To do this,
create a temporary working directory and SET DEFAULT to it:
<interactive>
<s>($ )<u>(CREATE/DIRECTORY [.TEMP])
<s>($ )<u>(SET DEFAULT [.TEMP])
<endinteractive>
<p>Next, unload the contents of the NETLIB<emphasis>(vvu).B save set into the working
directory and execute NETLIB_USER_INSTALL.COM (substitute appropriate
values for <emphasis>(vvu); for example, 016 for NETLIB V1.6):
<interactive>
<s>($ )<U>(BACKUP disk:[dir]NETLIBvvn.B/SAVE [])
<S>($ )<U>(@NETLIB_USER_INSTALL)
<endinteractive>
<p>Answer the questions from the installation script and the NETLIB
files will be created.  Once the installation procedure is complete,
you can delete the files and the working directory:
<interactive>
<s>($ )<u>(SET DEFAULT [-])
<s>($ )<u>(DELETE [.TEMP]*.*;*)
<s>($ )<U>(SET PROTECTION=O:RWED TEMP.DIR)
<S>($ )<U>(DELETE TEMP.DIR;)
<ENDINTERACTIVE>

<head2>(Personal NETLIB Restriction\NEWSRDR_INST_10)
<p>You cannot use a personal NETLIB with NETLIB-based applications that
are installed with privileges.

<chapter>(Installing NEWSRDR\NEWSRDR_INST_11)
<p>NEWSRDR consists of a main executable image (with some possible
additions, as described later in this chapter) and requires the following
logical names for configuration purposes:
<table>(NEWSRDR system logical names\lognamtable)
<table_attributes>(WIDE)
<table_setup>(2\25)
<table_heads>(Logical Name\Meaning)
<table_row>(NEWSRDR_ANNOUNCE\a message (or a pointer to a file containing
a message) that is displayed whe NEWSRDR starts up.)
<table_row>(NEWSRDR_BANG_ADDRESS\controls whether NEWSRDR generates
UUCP bang-format addresses for From and Reply-To headers (as opposed to
user@host format).  Default is FALSE.)
<table_row>(NEWSRDR_BANG_PATH\controls whether NEWSRDR generates
UUCP bang-format addresses for the Path header (as opposed to user@host
format).  Default is TRUE.  Ignored if NEWSRDR_DO_PATH is FALSE.)
<table_row>(NEWSRDR_DISABLE_USER_REPLY_TO\when TRUE, users cannot set their
own Reply-To headers.  Default is FALSE.)
<table_row>(NEWSRDR_DISALLOW_POSTING\when defined, the user is prevented from
posting any articles.)
<table_row>(NEWSRDR_DO_DATE\controls whether NEWSRDR generates its own
Date headers. Default is FALSE.)
<table_row>(NEWSRDR_DO_MESSAGE-ID\controls whether NEWSRDR generates its
own Message-ID headers. Default is FALSE.)
<table_row>(NEWSRDR_DO_NEWGROUPS\controls whether NEWSRDR sends a NEWGROUPS
command to the server at startup.  Default is TRUE.  Should only be set
to FALSE if your NNTP server aborts when it receives a NEWGROUPS command.)
<table_row>(NEWSRDR_DO_PATH\controls whether NEWSRDR includes a Path: header
in articles it posts.  Default is TRUE.  Should be set to FALSE if requested
by the manager of your NNTP server.)
<table_row>(NEWSRDR_FAKE_NEWGROUPS\when TRUE, NEWSRDR does its own new
newsgroup discovery.  Default is FALSE.  Can be set to TRUE if your server
does not support NEWGROUPS and  you want automatic newsgroup discovery.  Use
of this feature causes all NEWSRDR profiles to list all newgroups on the
news server, which consumes much more disk space per user than when this
option is disabled.)
<table_row>(NEWSRDR_INITIAL_GROUPS\a list of newsgroups that new users will
get subscribed to automatically the first time they use NEWSRDR.)
<table_row>(NEWSRDR_MAIL_NODE\the node name of the system for mail purposes.  This
is used in constructing return addresses in mail messages and news articles.)
<table_row>(NEWSRDR_MAIL_PROTOCOL\the VMS MAIL foreign protocol prefix to be
attached to outgoing mail addresses.  The prefix should include the trailing
percent-sign (e.g., "MX%", "INET%")).
<table_row>(NEWSRDR_NO_XHDR\disables the attempted use of the XHDR extended
NNTP command.)
<table_row>(NEWSRDR_NO_XOVER\disables the attempted use of the XOVER extended
NNTP command.)
<table_row>(NEWSRDR_NODE_NAME\the node name of the system for news purposes.  This
is generally the same as the Internet node name or the mail node name.)
<table_row>(NEWSRDR_ORGANIZATION\The name of the organization to be used in the
<quote>(Organization:) header in news articles.  Optional.)
<table_row>(NEWSRDR_SERVER\The Internet node name of the NNTP news server to
be used for NEWS sessions.)
<table_row>(NEWSRDR_GMT_OFFSET\A VMS delta time string specifying the
time differential between local time and Universal Coordinated Time.)
<table_row>(NEWSRDR_US_DST_ZONE\Either TRUE or FALSE, depending on whether
your locality observes U.S. standard daylight savings time.)
<endtable>
<p>The file NEWSRDR_STARTUP.COM, supplied with the distribution kit, contains
sample commands needed for defining these logical names and performing the
other tasks needed to make NEWSRDR available on the system.  You should
edit that file as needed for your system and include it in your system
startup sequence.
<head1>(Creating the NEWSRDR Image\NEWSRDR_INST_12)
<p>The NEWSRDR package comes with the object code required to create
the NEWSRDR image. A command procedure called LINK.COM is provided
for creating the image:
<interactive>
<s>($ )<u>(@LINK)
<endinteractive>
<p>If you wish to link NEWSRDR with your TCP/IP's Berkeley socket library
(if it supports one),
you may need to recompile SERVER_SOCKET.C as appropriate for your TCP/IP
package, and you may also need to edit LINK.COM to link against the
necessary library or libraries.

<head1>(Help Library\NEWSRDR_INST_13)
<p>The help library for NEWSRDR may be placed in SYS$HELP, or, if you define
logical name NEWSRDR_HELP to be the full file specification of the library,
anywhere else on the system.  For example:
<interactive>
<s>($ )<u>(DEFINE/SYSTEM NEWSRDR_HELP LOCAL_STUFF:[NEWSRDR]NEWSRDR_HELP.HLB)
<endinteractive>

<head1>(On-Line Documentation\online_doc)
<P>
The NEWSRDR documentation set is provided in a form suitable for use with
the VMS DECwindows Bookreader program (VMS V5.3 and later).  To make
the NEWSRDR on-line documentation available automatically through Bookreader,
place the DECW$BOOK and DECW$BOOKSHELF files provided in the distribution
kit in a directory, set their protection to WORLD:RE, and set the
value of the NEWSRDR_DOC_DIR symbol at the top of NEWSRDR_STARTUP.COM
to be the device and directory specification for the location of the
files.  NEWSRDR_STARTUP will automatically modify the appropriate Bookreader
logical names to make the documentation available.


<head1>(Privileges Required\NEWSRDR_INST_14)
<p>NEWSRDR requires TCP/IP network access to the news server to operate.  On
systems which use the access controls available with the CMU TCP/IP package,
this may require the granting of a rights identifier to the
accounts that will be using NEWSRDR.

<p>NEWSRDR uses callable MAIL and the MAIL foreign protocol interface to send
mail messages.  Therefore, NEWSRDR will need to be INSTALLed with the same
privileges as VMS MAIL's executable image, MAIL.EXE
(if any). NEWSRDR never uses these
privileges itself, and turns off all image privileges
<EMPHASIS>(except) <emphasis>(NETMBX\BOLD)
at the start of execution.
If you do not wish to use NEWSRDR to send mail, you do not need to install
NEWSRDR with privileges.
<head2>(EXQUOTA and User Profiles\exquota)
<P>If you install NEWSRDR with the EXQUOTA privilege, it will turn on that
privilege when writing out a user's NEWSRDR profile (and NEWSRC file, if
one is set).  This is the <emphasis>(only) privilege that NEWSRDR will use
if it is available, and is only used for this purpose.  The privilege is
not required, but makes using NEWSRDR easier for users who are close to
their diskquota.

<head1>(Other User Requirements\NEWSRDR_INST_15)
<p>NEWSRDR has no extensive disk quota or memory
requirements for most operations.  The NEWSRDR_PROFILE.NRPF file created for
each user contains information about only those groups to which users subscribe,
and should not require more than a few disk blocks for each user.
<p>When NEWSRDR retrieves news articles from a news server, it copies them into
temporary files created in the user's SYS$SCRATCH directory.  Extracts for
reply postings, mailings, and print jobs are also created in SYS$SCRATCH. 
Since news articles generally do not exceed a few hundred lines, this should
not be a problem for most users.

<head1>(Full-Screen Output\NEWSRDR_INST_16)
<p>NEWSRDR displays news articles on a page-by-page basis, much like
VMS MAIL.  The Screen Management Facility (SMG$) is used to obtain
the terminal size and perform the screen clears for each page of output.

<head1>(Callable Editors\NEWSRDR_INST_17)
<p>NEWSRDR can use any callable editor for message composition that meets the
following calling standard:
<list>(unnumbered)
<le>The callable editor's shareable library name must be xxxSHR.EXE, where
<quote>(xxx) is the name by which the editor will be called.  The library
must reside in SYS$SHARE or must have an exec-mode logical pointing to
the library elsewhere.
<le>The shareable library must contain an entry point which called
xxx$EDIT, which must take the input file-spec and output file-spec, both
character strings passed by descriptor, as the first two arguments.  If
there are optional arguments, the xxx$EDIT routine must not rely on having
more than two arguments present.
<endlist>
<p>The Digital-supplied editors TPU, EDT, and TECO, and the (layered product)
DEC Language-Sensitive Editor (LSE) all follow this calling standard.
Editors that do not qualify as callable can be set up as spawned editors
(where the editor is spawned in a subprocess).  See the description of
the SET EDIT command in the <reference>(userguide) for further information.

<head1>(VMS MAIL Interface\NEWSRDR_INST_18)
<p>NEWSRDR uses the callable MAIL interface to send mail messages.
NEWSRDR also assumes that since there is TCP/IP available
on the system, there is some form of Internet mailer also available that
will handle Internet-format (user@domain) addresses.
<p>A further assumption is that the Internet mailer package used at your
site includes a VMS MAIL <quote>(foreign mail protocol) interface library.
The logical name NEWSRDR_MAIL_PROTOCOL should specify the protocol prefix used
on your system, including the terminating percent-sign.  This prefix is
automatically prepended to any address specified when a user mails a message
using NEWSRDR.

<head1>(Character Conversion Support\NEWSRDR_INST_19)
<p>If your news network uses a character representation for its articles
that requires conversion from the DEC character set, as do Japanese
sites (due to differing Kanji representations), you can accommodate the
network character representation by installing a shareable library on the
system containing routines that perform the character code conversions.
<p>An example of a module containing such routines is provided in the
file KANJI_CONVERSION.C as part of the distribution kit.  To install
the KANJI_CONVERSION library as your character code conversion library,
you must:
<list>(numbered)
<le>Compile the C module (object code is provided for those without C
compilers):
<interactive>
<s>($ )<u>(CC KANJI_CONVERSION)
<endinteractive>
<le>Create the shareable library image:
<interactive>
<s>($ )<u>(LINK/SHARE/NOTRACE KANJI_CONVERSION,SYS$INPUT:/OPT)
<S>( )<U>(UNIVERSAL=NETWORK_TO_LOCAL,LOCAL_TO_NETWORK)
<S>( )<U>(<key>(ctrl/Z))
<endinteractive>
<le>Place the image in SYS$LIBRARY, define the appropriate NEWSRDR
logical name and INSTALL the image:
<interactive>
<s>($ )<u>(COPY KANJI_CONVERSION.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE)
<s>($ )<u>(DEFINE/SYSTEM/EXEC NEWSRDR_CHARACTER_CONVERSION -)
<S>(_$ )<U>(    SYS$SHARE:KANJI_CONVERSION.EXE)
<S>($ )<U>(INSTALL CREATE NEWSRDR_CHARACTER_CONVERSION/OPEN/SHARE/HEADER)
<ENDINTERACTIVE>
<endlist>
<p>Note that you must do this from a suitably privileged account, and
you must have at least one global section and three global pages free on
the system to INSTALL the image.  The commands for installing the image
are provided in the sample NEWSRDR_STARTUP.COM command procedure provided
with the NEWSRDR kit.
<p>You only need to INSTALL the character conversion library if
NEWSRDR is installed with privileges.

<head1>(Establishing Your Time Zone\NEWSRDR_INST_20)
<p>This is only required if NEWSRDR_DO_DATE is defined TRUE.
<p>Two logical names control the way date/time stamps are generated by
NEWSRDR for articles posted by NEWSRDR users.  NEWSRDR_GMT_OFFSET should
be defined as a VMS delta time specification preceded by either a plus sign
or a minus sign.  This value represents the time differential between
local time and Universal Coordinated Time (also called Greenwich Mean Time).
For the U.S. Eastern time zone, you would define it as:
<interactive>
<s>($ )<u>(DEFINE/SYSTEM NEWSRDR_GMT_OFFSET "-0 05:00:00")
<endinteractive>
<p>The minus sign indicates that Eastern time is 5 hours behind GMT.
<p>The logical name NEWSRDR_US_DST_ZONE should be defined as TRUE if
your locality observes U.S. standard daylight savings time (DST).  This
will cause NEWSRDR to automatically adjust the GMT offset during daylight
savings time.  If you do not observe U.S. standard DST, you may need
alter the GMT offset value manually at the beginning and end of your
DST period.

<head1>(Name Conversion Support\NEWSRDR_INST_21)
<p>If your site does not use VMS usernames for addressing local users in
network mail, you can install a shareable library containing a routine
that NEWSRDR will call on to perform username-to-mailname conversions
for addresses that it puts in article headers.
<p>An example of a module containing the routines needed to support such
conversions is provided in the file NAME_CONVERSION.C as part of the
distribution kit.  To install a name conversion library, you must:
<list>(numbered)
<le>Edit and compile the C module, or develop your own module in another
language that provides the same interface.
<le>Create the shareable library image:
<interactive>
<s>($ )<u>(LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT)
<s>( )<u>(UNIVERSAL=INIT,CONVERT,CLEANUP)
<s>( )<u>(<KEY>(ctrl/Z))
<endinteractive>
<le>Place the resulting image in SYS$LIBRARY, define the appropriate
NEWSRDR logical name, and INSTALL the image:
<interactive>
<s>($ )<u>(COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE)
<s>($ )<u>(DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION SYS$SHARE:library.EXE)
<S>($ )<U>(INSTALL CREATE NEWSRDR_NAME_CONVERSION/OPEN/SHARE/HEADER)
<ENDINTERACTIVE>
<endlist>
<p>The interface used by NEWSRDR is identical to that used by MadGoat's
Message Exchange E-mail software.  If you already have installed a
name conversion library for use with Message Exchange, you need only
define a logical name to use the same library with NEWSRDR:
<interactive>
<s>($ )<u>(DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION MX_SITE_NAME_CONVERSION)
<endinteractive>
<p>Refer to the sample code provided for further information on the
name conversion interface.
<head1>(Address Conversion Support\NEWSRDR_INST_22)
<p>When NEWSRDR sends mail, it uses callable Mail routines, forming the
addresses by translating the logical name NEWSRDR_MAIL_PROTOCOL and
prefixing that to the quoted RFC822 destination address.  If your site
requires a more sophisticated translation (such as domain name reversal
or better handling of special characters in addresses), you can install
your own address conversion routine to perform this function.
<p>An example of a module containing the routines needed to support such
conversions is provided in the file ADDRESS_CONVERSION.C as part of the
distribution kit.  To install an address conversion library, you must:
<list>(numbered)
<le>Edit and compile the C module, or develop your own module in another
language that provides the same interface.
<le>Create the shareable library image:
<interactive>
<s>($ )<u>(LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT)
<s>( )<u>(UNIVERSAL=INIT,CONVERT,CLEANUP)
<s>( )<u>(<KEY>(ctrl/Z))
<endinteractive>
<le>Place the resulting image in SYS$LIBRARY, define the appropriate
NEWSRDR logical name, and INSTALL the image:
<interactive>
<s>($ )<u>(COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE)
<s>($ )<u>(DEFINE/SYSTEM/EXEC NEWSRDR_ADDRESS_CONVERSION SYS$SHARE:library.EXE)
<S>($ )<U>(INSTALL CREATE NEWSRDR_ADDRESS_CONVERSION/OPEN/SHARE/HEADER)
<ENDINTERACTIVE>
<endlist>
<p>Refer to the sample code provided for further information on the
address conversion interface.
<head1>(Installing NEWSRDR for Personal Use\NEWSRDR_INST_23)
<p>If you are not the system manager, you can install NEWSRDR for your own use,
with the restriction that you may not be able to send mail using NEWSRDR
(depending on your site's E-mail software).
<P>To install NEWSRDR for your own use, create the NEWSRDR image as described
above, place the image and the help library in directories you own, and
edit NEWSRDR_STARTUP.COM to reflect the location of those files.
You should also edit NEWSRDR_STARTUP.COM to remove the /SYSTEM qualifier
from the definition of NEWSRDR_DEF.