OS/2 Shareware BBS: 35 Internet/35-Internet.zip/yrndl153.zip/yd.doc

Text File | 1997-03-13 | 121KB | 2,836 lines

YD.DOC        13 Mar 1997        (from YRNDL153.ZIP)
(c) 1996-7 by Jerry Levy        Marblehead, MA USA
[e-mail]

This is the full documentation file accompanying YARNDIAL
in YRNDL153.ZIP (YARNDIAL v. 1.53)

README.1ST is a shortened version of YD.DOC.
README.1ST should suffice for most people.  YD.DOC has
assumed the bulk and format of a manual and become very long.
Its Table of Contents is provided in the README.1ST file
in the event you want assistance on a specific subject and
do not wish to kill trees printing the whole YD.DOC.

Any comments, problems, bugs, irregularities or inconsistencies
in operation of YARNDIAL or its installer, and any suggestions,
should be sent to me at [e-mail].  I will make every effort
to respond to each one.

YARNDIAL.CMD is a menu-driven front end for C.T. Huang's
OS/2 Souper and Yarn off-line News and Mail reader programs
and now supports use of VSoup as well as Souper.  VSoup is
recommended because of its speed: it is multi-threaded for
news retrieval.  I gratefully acknowledge Hardy Greich and his
VSoup implementation by means of the sincerest form of flattery:
the adoption here of his suggested mail and news subdirectory
structure, and adoption of his innovation of allowing more than
one Internet Service Provider's mail and news servers to be
linked in a single on-line session.

YARNDIAL.CMD is a ReXX utility running under OS/2 Warp.  It is
designed to automate the steps needed to retrieve and send news
articles and mail and while doing so to provide a more versatile,
friendlier interface for users than could be accomplished using
ordinary batch files.  Packaged with YARNDIAL.CMD is a
rather full-function installer.  If YARN and Souper are up and
running, installation of YARNDIAL via its installer is a breeze.

PRINTING THIS DOCUMENTATION
This documentation file should be printed at 10 cpi (Courier or
other monospaced font preferred).  Left and right margins of
1 inch or less (0.75 inches works very well) are recommended.

NOTE:  At some point in this documentation I started to use
%HOME% and %YARN% in place of HOME and YARN to denote
the HOME and YARN environmental variables, which are the
HOME and YARN directory paths as defined for installation
of YARN.  And at other times I write of HOME or YARN
as the directory names.  I think context will let you know
what I mean.

IF YOU USE IN-JOY
Read over Section 16.00 very carefully.  Give serious thought to
setting a routing interface name in  each host setup that is unique,
i.e., different from all other interface names used by IN-JOY or
your other dialers (if you do use others).  This interface name is
set in an options page for PPP and no doubt will be equally
configurable in a corresponding SLIP options page when SLIP is
supported by IN-JOY.  YARNDIAL will use this interface name you
assign to positively correlate an existing connection to the
YARNDIAL installation when YARNDIAL starts up.  It can only do
this competently if you use unique interface names, different for
all connections and providers.

There is a problem which in my experience is unique to IN-JOY
where a router interface is sometimes left standing when phone
connection and connection to the router (i.e., to your Internet
Service Provider) have been terminated.  INTERFACE_REMOVAL in
the YD_PARMS.DAT file can overcome the problem by permitting
removal of such interfaces when YARNDIAL finishes and the dialer
is shut down.  Options are discussed in Section 16.00 and again
summarized in the YD_PARMS.DAT file created upon installation of
YARNDIAL.  Unless you establish simultaneous multiple (modem)
connections, setting INTERFACE_REMOVAL=2 (which I use),
or 1, is preferred.

If INTERFACE_REMOVAL is set equal to 1 or 2 (refer section 16.00),
and a routing was left up when YARNDIAL exits, it is removed and a
message is returned indicating deletion of the routing, with indication
of the destination and router addresses.  The difference is that the
setting of 2 removes such interfaces whatever the dialer; whereas
a setting of 1 does so only if IN-JOY is the dialer.


IF YOU ARE USING THE IAK DIALER (DIALER.EXE)
Make sure when you set it up (SETTINGS or PROPERTIES), that if
there is a box to check to CONFIRM BEFORE CLOSING that
YOU SHOULD NOT CHECK IT  (If there is one it will probably
be on the phone page of the settings notebook).  If you
check the box, the dialer will need to ask you before it closes
and the dialer may/will remain connected until you respond
or it times out.

IF YOU ARE GOING TO USE VSOUP
Aside from getting a copy of VSoup (see section 33.00), you will need to
get and install at least version 09c of EMX.


This YARNDIAL program is and will stay freeware.

DIALERS
For use of third-party dialers such as IN-JOY or ILINK/2, or if
you use PPP.EXE or SLIP.EXE dialup strings, it is most convenient
and strongly recommended that you go through the motions of
setting up SLIPPM even where you do not intend to use SLIPPM to
make the connection.  Think of SLIPPM in that context as a PM
program to conveniently store parameters where the YARNDIAL
installer can most readily get at them.

SLIPPM is a fine utility, and in most instances where you are
connecting to a provider with other than the IBM/Advantis IAK
dialer, alone or with add-on script packages such as PPDIAL29, it
is serviceable.  ILINK/2 is an improvement over SLIPPM in
many respects and piggybacks on SLIPPM-created dialup
configurations.  IN-JOY is another improved dialer, but unlike
ILINK/2, it was rewritten from the ground up and is totally
independent of the SLIPPM, SLIP.EXE and/or PPP.EXE programs,
and does not speak to (or listen to) the TCPOS2.INI file used by
SLIPPM and ILINK/2.  IN-JOY version 1.0 now supports SLIP
as well as PPP.  Most testing with IN-JOY was for version
0.9.  The very recent v. 1.0 seems to work equally well but after
being mercilessly assaulted by its advertising gimmick I stopped
all futher tests with it.

I am committed to adding and improving support of third-party
dialers provided I can obtain a copy to work with and the
interface is not obscure.  So far, only ILINK/2 and IN-JOY have
been brought to my attention as alternatives to SLIPPM, PPP.EXE
and SLIP.EXE.

Contact me if I do not support your pet dialer ([e-mail]).

                        CONTENTS
 1.00  Installation For The Impatient User (Assumes Yarn And
        Souper Are Installed And They Work
 2.00  What Is Yarndial?
 3.00  Key Features
         3.10   Multiple Service Providers
         3.20   Setting Up To Access More Than a Single
                 Provider's Servers In A Single Session
 4.00  Copyright Notice And Disclaimers
 5.00  Passwords - Disclaimer
 6.00  How Does The Installer Work?
 7.00  Example: Setting Up For Two Users (My Installation)
 8.00  What Does YDINSTL.CMD Do?
 9.00  .CMD Files Created - Meaning Of Customization
10.00  Recreating Objects (Running OBJECTS.CMD - A Peculiarity)
11.00  Warp, Souper, VSoup, Yarn: Versions Tested
         11.10   VSoup
            11.11   VSoup is Supported
            11.12   Changes That Have Been Made In YARNDIAL To
                    Enable VSoup Support, And Applicability To
                    Souper
               11.121   Directory Structure
               11.122   Command Lines: Souper vs. VSoup And Other
                        Command-Line Issues
               11.123   No More YD_ALT.DAT Parameter File
               11.124   Automatic Backups of  SOUP.ZIP
                  11.1241   Restoring from the Backed-Up SOUP.ZIP File
               11.125   (Changes in) How Scheduled Operation Works
12.00  You Have Not Installed Yarn And Souper Yet?
13.00  History
14.00  Should You Upgrade Anything Before You Install?
        14.10   Souper
        14.20   IBM/Advantis IAK Dialer
        14.30   SLIPPM.EXE (Dial-Other-Internet-Providers Utility
                 and SLIP Upgrades
        14.40   EMX
15.00  Before You Run YDINSTL.CMD
16.00  Notes On Using the IN-JOY Dialer
17.00  About The Fix-Interrupted-Import Option On The Main
        YARNDIAL Menu
18.00  Souper Command-Line Options
19.00  Issues That May Come Up During Or After Install
20.00  Manual Install
21.00  Manual Install: The Password Problem
22.00  Connection_Type: The Different Choices
23.00  More About Dialup_String: A Programming Note
24.00  Zip And UnZip Files
25.00  Compression Executables: OS/2 Versus MS-DOS
26.00  Some Other Breed Of Compression Utilities
27.00  Files For Setting Up Yarn And Souper From Scratch
28.00  Install EMXRT, METAMAIL, MIME64 (recommended)
        28.10 EMXRT09 (optional, butEMXRT09c is required for
               VSoup))
        28.20 MIME64 (optional)
        28.30 METAMAIL (optional)
           28.31  Metamail Tricks
           28.32  Doing MIME Attachments Under Yarn, Metamail
                   Operation, Decoding Multipart Messages, and
                   Handling Non-Conforming MIME Attachments
              28.321  Doing MIME Attachments Under Yarn
              28.322  Decoding Non-Conforming Mime Attachments
              28.323  Decoding MIME With MIME64.EXE
              28.324  Content-type Editing:  MIME Associations
           28.33  UUENCODED Attachments Under Yarn,
                   Using YEP
              28.331  Installing YEP
              28.332  UUENCODED Attachments (Insertions)
              28.333  Decoding UUENCODED Attachments Under
                       Yarn
              28.334  Decoding UUENCODED Attachments the
                       Hard Way
29.00  Step-By-Step Installation Of Yarn and Souper
30.00  Note About Adding Newsgroups
31.00  Setting Up And Installing For Multiple Users
32.00  Connection Killed Or Not When YARNDIAL Ends
33.00  Where To Get Software And Helpful Documentation
34.00  Bugs and Error-Trapping






1.00  INSTALLATION FOR THE IMPATIENT USER (ASSUMES YARN AND
       SOUPER ARE INSTALLED AND THEY WORK)

=========
BEFORE YOU START:
I tried to mimic the directory structure required for VSOUP, but there
is
one thing I did not implement and yet felt should be done.  You can
make the change yourself.  That change is to use reply.zip as the name
for the reply-packet file in YARN's CONFIG file, and with a path which
is the path recommended by Hardy Griech for his VSoup installation.

Edit the Reply-Packet statement in YARN's CONFIG file to show this
new file name with its full path.  In my setup where E:\ADVANTIS
is the %HOME% directory, this line becomes
          reply-packet=E:\ADVANTIS\YARN\OUT\REPLY.ZIP

Substitute your own YARN %HOME% directory for E:\ADVANTIS.

That's it.  You don't have to do this.  Just seems desirable in the
event you want to tackle the real VSoup installation at some later time.
If you do it, best to do it before you (re)install YARNDIAL.  That way
the installer finds the correct path and reply-packet filename and you
won't have to edit a zillion places.
============

    1.10   First unzip YRNDLxxx.ZIP archive into a temporary
folder.  You have probably done that if you are reading this.

Files in the YRNDLxxx.ZIP archive are
        FILE.DIZ        Zipfile Description
        README.1ST    A lot shorter than YD.DOC
        YD.DOC          This file
        YDINSTL.CMD   The installer
        YARNDIAL.CMD
        GO.EXE          From GO_15.ZIP, needed by YARNDIAL
        GO_15.ZIP      Please open at your leisure, read
                          the documentation and send Carsten
                          his postcard.

        Also an \ICONS\ subdirectory containing all of the icons
          needed

        (YD_ALT.DAT, for storing data for supplemental ISP's, is
        no longer used.  Instead that data can be edited into the
        YD_PARMS.DAT file created during installation.)


If you unzipped YRNDLxxx.ZIP with PkZip without using the -d
option, you will not have a subdirectory named ICONS.  That
will not interfere with installation.  YDINSTL will manage
to find the icons.

       1.20   If you are using the IBM/Advantis IAK Dialer
proceed directly to the next step (1.30).

If you are using either SLIPPM (the IBM Dial-Other-Internet-
Providers utility) or the ILINK/2 dialer, you MUST set up
SLIPPM and verify it can connect to your provider successfully
before you run YDINSTL.CMD to install YARNDIAL.

If you are using either the IN-JOY dialer, or a SLIP.EXE or
PPP.EXE dialup string to connect, you SHOULD set up
SLIPPM and verify it can conect to your provider successfully
before you run YDINSTL.CMD to install YARNDIAL.  This is
because the YARNDIAL installer (YDINSTL.CMD) can extract
parameters from the TCPOS2.INI file used to store SLIPPM
setup information.

In setting up SLIPPM, you MUST fill in the names of your news
server, your mail gateway (i.e., your SMTP server), your POP
mail server, your pop login ID, and your pop password.  This is
not required for SLIPPM operation but the YARNDIAL installer
(YDINSTL.CMD) needs them and will automatically incorporate those
parameters into YARNDIAL's data file.

       1.30   Double-click on YDINSTL.CMD and follow the
instructions in screen prompts.

       1.40   For unattended operation, read section 35.00.


2.00    WHAT IS YARNDIAL?
YARNDIAL.CMD is a menu-driven front end for C.T. Huang's
OS/2 Souper and Yarn off-line News and Mail reader programs.
YARNDIAL is a ReXX utility running under OS/2 Warp.  It is
designed to automate the steps needed to retrieve and send news
articles and mail and while doing so to provide a more versatile,
friendlier interface for users than could be accomplished using
ordinary batch files.

YARNDIAL and its installer (YDINSTL.CMD) should work with any
version of OS/2 Warp (3.0).  Beta testers have confirmed that fixes
applied to YARNDIAL v. 1.32(beta) and beyond permit it to work with
the OS/2 Merlin beta.

ReXX must be installed for YARNDIAL and its installer to run.

Yarn and Souper must be correctly installed and functioning (the
true test of "correctly installed").  YARNDIAL only functions as a
front end and control panel for Souper and its interfaces with
Yarn, and is not a substitute.

YARNDIAL's opening menu allows you seven choices:

MAIN SELECTION MENU
1  Only import Mail
2  Only import News Articles
3  Only import, but both Mail AND News
4  Only export (send Mail, Posts, Replies, and Follow-ups)
5  Everything: Get Mail and News AND send Posts, Replies,
    Follow-ups
6  Complete an interrupted importation of mail/news
         or rebuild a corrupted YARN history file
7  Souper options:  one-time-only changes in how souper runs:
      Catchup on News
      Maximum News Packet Size
      Do not retrieve newsgroup articles longer than set number of lines
      Read-only for Mail: Don't empty POP3 mailbox
Press:
    1 2 3 4 5 6 7   Executes functions as shown; goes off-line when done
 or ! @ # $ % ^ &   Same functions; connection remains up
To exit now and close connection: Escape key
To exit, but leave any existing connection up: CTRL-Q



Note: The ! @ # $ % ^ & choices represent shift-1, shift-2,
through shift-7 on a US-English keyboard.  Those alternates may be
changed to suit your own keyboard.


3.00  KEY FEATURES
o  Automatic dialup, connection, retrieval and sending of
news and/or mail, and (usually) signoff.  Optionally, can be run
so connection remains up when YARNDIAL finishes.

o Ability under certain circumstances to use an existing
SLIP or PPP connection to a provider.

o  Ability to select read-only for mail retrieval (doesn't empty
your POP3 mailbox).  I did not extend this to read-only for news
retrieval (i.e., to prevent your NEWSRC file from updating).  You
can edit the Souper parameters in YD_PARMS.DAT file following
installation to achieve this end (add -r to the
souper_getnews_xtra options element).

o  Ability to use a variety of dialup and connect options.
Supported are: the IBM/Advantis IAK Dialer,  IBM's Dial-
Other-Internet-Providers utility (SLIPPM.EXE),  PPP.EXE and
SLIP.EXE dialup strings, the IN-JOY dialer (in-joy v. 09 is
well tested, and v. 1.0 seems so far to be a plugin) and
ILINK/2.  Other dialers can be used.

o  Menu-driven, for convenient selection of tasks.

o  Supports use of Souper and VSoup.

o  Ability to choose/change a limited number of Souper
or VSoup command-line options (menu, during install).

o  Ability to choose/change some Souper or VSoup command-line
options (menu, when running YARNDIAL).

o  A YARNDIAL menu item which allows you to complete an
importation of news or mail which had been interrupted,  and
to call up the Yarn utility REBUILD to restore damaged Yarn
spool and history files.  (You don't need to understand this:
if you were downloading news and mail and it never showed
up, or your machine quit in the middle, or the lights went
out, maybe this will provide a fix.)

o  YDINSTL.CMD provides a near-automated (prompted)
installation process if you already have installed Yarn and
Souper and they work.

o  Some ability exists to discriminate if the connection
that is up is the correct connection for the particular user
for which YARNDIAL was installed.  For the IN-JOY dialer
this works best if one selects a unique interface name
when configuring IN-JOY to connect to your provider.  Refer
Section 16.00 for more on use of the IN-JOY dialer.

o  Ability when you run YARNDIAL to do catchup on news.
Catchup marks as read all but some number you specify of
unread articles in each news group.  Catchup as implemented
in YARNDIAL uses the same "catchup" number for all
newsgroups.

o  Among the Souper/VSoup command-line options you can
choose when you run YDINSTL.CMD or at runtime when
YARNDIAL is executed are:
      Set maximum size of the news packet you can download
      in a single session
  and
      Limit retrieval of news articles to those with no more than
      some maximum number you set of lines in the body of the
      article.

o  Ability to set up and (try to) connect to multiple ISP's in a
single session (refer next section).

         3.10   MULTIPLE SERVICE PROVIDERS
YarnDial Version 1.5x allows you to get news and mail and send
mail and postings to/from more than one ISP in a single session.
This was an idea copied from Hardy Griech's VSoup. (Thanks).
Not all Service Providers will let you access POP3 Mail Servers
and NNTP News Servers when you are signed on to another
provider.  This is because, for security reasons, those servers
may operate behind firewalls and part of the security regime
is that those servers can only be accessed (ordinary subscribers)
via a dial-in or otherwise directly-logged connection.

That limitation generally does not apply to the sending of mail,
posts, etc., via an SMTP server.  Any mail gateway (SMTP server)
to which you have access via the ISP you dialed into, will
appropriately accept and broadcast your outgoing mail and postings.
Whatever additional ISP's you add to YD_PARMS.DAT, we always
do our sendoing send with the server/settings for the ISP 1 (the one
you did the YarnDial install for).

         3.20   SETTING UP TO ACCESS MORE THAN A SINGLE
                 PROVIDER'S SERVERS IN A SINGLE SESSION

First install YARNDIAL and make sure YARNDIAL is working well
for your principal Internet Service Provider (ISP).

Then print out and read the notes contained in YD_PARMS.DAT
which the YARNDIAL installation creates in the Yarn %HOME%
directory.  The parts concerning adding more ISP's are near the
end.

Only then experiment to see if your alternate ISP can be
accessed.  Open YD_PARMS.DAT in your %HOME% directory and
edit parameters for your second ISP.  Play with them until either
you can do what you want (get/send stuff) or until you determine
that firewall protection prevents this kind of access.  Do this for
each additional ISP section in YD_PARMS.DAT in turn.  Set
each ISP_ACTIVE.i=1 or 0 in YD_PARMS.DAT to activate or
de-activate each added ISP section.

NOTE: Because you may need to play around a bit, the password
fields are managed such that if you have something in both the
encrypted and unencrypted fields, only what is in the unencrypted
field(s) is operative.  That way you can make changes to your
heart's content with simple editing.  When/if you get it working,
you can and should wipe out the unencrypted entry, do the encryption
(see the note in the YD_PARMS.DAT you printed out) and transfer
the encrypted password(s) into YD_PARMS.DAT.

Because of protection schemes your ISP providers may use, it may
not be possible to get mail or news from all of them while logged in
via modem to a different ISP.

You can add as amny ISP's to YD_PARMS.DAT as you like, setting
them active or not, also as you desire.  The only caveat is that the
first ISP should always be left active (ISP_ACTIVE.1=1).


4.00  COPYRIGHT NOTICE AND DISCLAIMERS
        YDINSTL.CMD is Copyright 1996-7 by Jerry Levy
           (all rights reserved)
        YARNDIAL.CMD is Copyright 1995-7 by Jerry Levy
                   (all rights reserved)
        YD.DOC is Copyright 1995-7 by Jerry Levy
                   (all rights reserved)
These are provided as-is and without charge, with no
warranty expressed or implied as to merchantability or
fitness for any particular purpose.  All responsibility for
any and all incidental and consequential damages is
disclaimed.  These programs and associated text files are
freeware.  They may be distributed without restriction
providing: (1) this notice and disclaimer remain intact, (2)
all programs and files are included and unchanged, and (3)
they are distributed either in the original .zip archive or
the archive after being unzipped into a folder or onto a
disk or other medium.  Use of either or both of these
programs constitutes acceptance of these terms by all users.

GO.EXE and GO_15.ZIP are  (c) 1993-95 by Carsten Wimmer and
are included with permission.
YARN.ICO is (c) by Chin Huang and is included with
permission.


5.00   PASSWORDS - DISCLAIMER
Some passwords are extracted from dialer setup files, and
while installing for use of the IBM/Advantis IAK Dialer,
we prompt for the Advantis password.  To keep these
passwords free from the casual eye, we scramble them before
they are written to YD_PARMS.DAT.  YARNDIAL unscrambles them
to use them.  Bear in mind that this is very low-tech
password protection.  It is minimal protection against a
threat posed by a skilled programmer or dedicated interloper.


6.00   HOW DOES THE INSTALLER WORK?
YDINSTL.CMD fetches information from one or more of: the IAK
dialer's DIALER.INI file, the TCPOS2.INI file, the IN-JOY
HOSTS.DAT file, and/or the YARN CONFIG file.

It goes after and processes other information
it finds on its own prompts you to enter.  YDINSTL then creates a
data file  (YD_PARMS.DAT) which is written to the home directory
for the Yarn user setup for which you are doing a YARNDIAL
installation.  YD_PARMS.DAT stores ALL of the installation-
specific parameters YARNDIAL needs in order to run.

YDINSTL also creates a folder on the desktop which houses program
objects for five objects; four for customized ReXX utility
programs created by YDINSTL for this user and a fifth object in
the folder for running YARNDIAL.

Another customized program (OBJECTS.CMD) is created that will
restore the Desktop Folder and its five Program Objects should you
need to.  This program is stored in the user's Home directory
also.

The folder name includes the name of the home directory of the
Yarn user setup you installed for.

The utility programs themselves (as opposed to their program
objects) are stored in the user's home directory.

YDINSTL IS RUN SEPARATELY FOR EACH YARN USER SETUP
If you set up more than one user when you set up YARN you need to
run YDINSTL separately for each one of them.


7.00   EXAMPLE: SETTING UP FOR TWO USERS (MY INSTALLATION)
In my setup I have two users, each with its own YARN directory,
For each, the HOME directories are the same as the YARN
directories.  This is somewhat unconventional but it works like a
charm and solves some problems I need not go into here (drop me a
note if interested).

I have set up one user for connection to the IBM/Advantis system
(using the IBM/Advantis IAK Dialer to establish a SLIP
connection), and I have set up a second user for connection via
PPP to the ATT WorldNet service (using IBM's Dial-Other-Internet-
Provider utility, SLIPPM.EXE, to connect, or the IN-JOY or ILINK/2
dialers to connect).

        NOTE:  When you set up SLIPPM, you will be asked to assign
        a name for that entry (first box on first page of the
        entry form).  Contrary to what I had once recommended, YOU
        SHOULD USE ALL UPPERCASE FOR THE NAME.

        WHY?   Because when slippm is run, some information, such
        as the running total of number of connections, is saved in
        TCPOS2.INI, under the same name, but the name in all-
        uppercase.  If the application name you specified was
        lowercase or mixed cases, you will store your application
        parameters under that name and you will create a separate
        entry (all uppercase) for the connect data.  If your
        application name is all-uppercase, your connect data are
        consolidated under a single uppercase .INI file
        "application" name.


Following is how I created my Yarn and Home Directories. Please
read Sections 27.00, 28.00 and 29.00 (Setting up Yarn and Souper)
for all the other things one needs to do in addition to setting
up directories.

   Unzip YRN2_09x.ZIP into a temporary folder.

   From an OS/2 command line after changing to that temporary
   directory run
         ENGLISH E:\ADVANTIS and then ENGLISH E:\WORLDNET.
   This creates separate E:\ADVANTIS and E:\WORLDNET directories
   for YARN.

   Add the following to your CONFIG.SYS file and reboot (We do
   this first for the ADVANTIS installation, then for WORLDNET):
        SET YARN=E:\ADVANTIS
        SET HOME=E:\ADVANTIS
        SET TZ=EST5EDT

   Open an OS/2 Window session, change to the E:\ADVANTIS
   directory, and run
        ADDUSER.EXE
   defining E:\ADVANTIS as the home directory, and filling in the
   other blanks.

STRONGLY RECOMMENDED:  for your reply-packet file (when you are
into the ADDUSER.EXE screen, name your reply-packet REPLY.ZIP
and use the path (for the example shown):
        E:\ADVANTIS\YARN\OUT\REPLY.ZIP
Replace E:\ADVANTIS with whatever you have as your HOME dorectory.

This will make your setup more consistent with that recommended for
VSoup than it would be if you used the usual YARN default.

   Repeat that process for the WORLDNET installation: re-edit
   CONFIG.SYS by replacing the ADVANTIS lines with
       SET YARN=E:\WORLDNET and SET HOME=E:\WORLDNET
   reboot; change to the E:\WORLDNET directory in an OS/2 window
   session; run ADDUSER.EXE from the command line, define
   E:\WORLDNET as the home directory, and fill in the other
   blanks.

(Also set up a NEWSRC file for each home directory, run
NEWGROUP.EXE to add new groups to each, create a signature file,
edited each of the Yarn CONFIG files, etc., etc., as detailed
below in Sections 27.00, 28.00, and 29.00)

I ran YDINSTL.CMD once for the Advantis user, and again for the
WorldNet user.  YDINSTL lets you key in home and yarn directories
for any correctly-set-up Yarn user so you do not need to fool with
CONFIG.SYS again.

NOTE:  For the WorldNet installation, when I had set up the Dial-
Other-Internet-Provider (SLIPPM) to dial in, I assigned the name
WORLDNET (all-uppercase preferred) to the dialup entry.  So, when
YDINSTL.CMD is run specifying E:\WORLDNET as the home and yarn
directories and choosing connection_type 4 and SLIPPM to connect,
YDINSTL presents me with a menu of TCPOS2.INI applications to
choose from, one of which is WORLDNET, in the exact upper-case/
lower-case form (all-uppercase) that I used as my SLIPPM entry
name when I configured SLIPPM for the connection.


8.00   WHAT DOES YDINSTL.CMD DO?
o Fetches information, parameters, etc.

o Wherever  it can, it presents menus for you to choose from when
you need to make selections

o Copies files from a temporary directory to the user HOME
directory

o Creates five customized ReXX programs for each installation,
copying them to the respective home directory

Functionality of four of these:
    - YARNSHELL.CMD   Opens (starts) YARN for that user
                        (to read news and mail, and to
                        create mail, posts and replies)

    - YARNUTIL.CMD    Prompts for and runs YARN utility
                        programs for that user

    - RENEWZIP.CMD    Allows you to restore a reply-packet
                        (.ZIP) if during sending of mail a
                        glitch was encountered

    - LOGOFF.CMD      Helps assure log off by shutting
                        down the IAK Dialer, SLIPPM, PPP,
                        SLIP, SLATTACH, IN-JOY.  Uses
                        IN-JOY's KILLJOY.EXE in order to
                        close down IN-JOY, if KILLJOY was
                        found when LOGOFF was created by
                        YDINSTL.CMD.

Another customized program (OBJECTS.CMD) restores the desktop
folder and its objects if you have intentionally or accidentally
deleted it.

o YDINSTL creates a Desktop Folder unique to each installation,
with objects for the four programs whose functions we have just
described, and a fifth object for running YARNDIAL.CMD.

The folder name contains the name of the user's home directory, so
YARNDIAL desktop folders, each for a different user, will be
distinct from each other.


9.00   .CMD FILES CREATED - MEANING OF CUSTOMIZATION
The ReXX files created by the installer are customized in the
sense that the OS/2 environment variables for HOME and YARN,
paths, and directory structures apply specifically to that
installation.

Unless you change where files are located, LOGOFF.CMD, regardless
of the home directory for which it is customized, will perform
very nearly exactly the same shut-down functionality.  Thus for a
multi-user installation, one "centrally available" LOGOFF.CMD
shadow can be used whatever the user for which it was installed.

Customizing ReXX utilities for each user means that once you've
completed installation of YARNDIAL with YDINSTL.CMD you no longer
need to have a HOME or YARN environment variable in your
CONFIG.SYS file.  Since some other programs want their own HOME
variable set and don't share well, this will prove a great
convenience to some of you and of no interest to others.


10.00   RECREATING OBJECTS (RUNNING OBJECTS.CMD): A PECULIARITY
OBJECTS.CMD as mentioned can recreate objects if you delete them.
Be aware (and this is identified as as a bug at the end of this
document even though in reality it may be a "feature" rather than
a "bug") that if you have moved the YARNDIAL desktop folder you
created during an installation with YDINSTL (for example into
another desktop folder), if you rerun YDINSTL or run OBJECTS.CMD
to recreate the folder on the desktop, the folder does not appear
on the desktop, but instead the one you moved to a new location is
refreshed.  Only if you delete the desktop folder (instead of
moving it) will it be RECREATED ON THE DESKTOP.


11.00   WARP, SOUPER, VSOUP, YARN: VERSIONS TESTED
This version of YARNDIAL and its installer have been tested by me
only on machines running OS/2 Warp Connect with TCPIP and Internet
stuff installed as part of the Warp installation.  Beta testers
have used it on machines running the Merlin beta.  Version 1.32
corrected an incompatibility created by the new format of output
from the NETSTAT utility.  NETSTAT is called by YARNDIAL.

YARNDIAL should run on any OS/2 Warp setup.  If you use the Dial-
Other-Internet-Providers utility (slippm.exe), you will need to
get the upgraded version of TCP/IP and SLIPPM (2.0 or higher).
That should be available by connecting to an updates ftp site.
See Section 33.00 for a link.

If you have installed TCPIP and the OS/2 internet stuff
successfully to OS/2 2.1, I would expect YARNDIAL and its
installer to work.  If anyone tries this under OS/2 2.1 or 2.11, I
would appreciate feedback and if there are problems, I will try
my best to help out.

Various YARN versions up to YRN2_092 have been tested, and
the same applies to SOUPER, tested through the v. 1.6 beta.

I started using VSOUP with version 1.2.5.  Only that has been
tested.

         11.10   VSOUP
VSoup is multi-threaded for news retrieval, which increases its speed
over Souper tremendously if you take advantage of the threading option
and of an ability to set the aggressiveness of how it is implemented
(see below).   If watching the news retrieval  process with Souper
generated all the excitement of watching paint dry, you will like VSoup.
Section 33.00 in YD.DOC in this archive indicates where VSoup can be
obtained.

So far VSoup (version 1.2.5) is single-threaded for mail and posting.
The reasons for this are given in VSoup documentation.

            11.11   VSOUP IS SUPPORTED
VSoup can now be elected as an alternative to Souper at installation
time.  No change in the YARN and SOUPER installation that is described
in YD.DOC (Section 29.00) is required in order to be able to use VSoup,
or to switch between VSoup and Souper.

That is, no change on your part.  Be aware that THIS VERSION OF YARNDIAL
DOES ALTER THE DIRECTORY STRUCTURE FROM WHAT WAS THE CASE
FOR EARLIER VERSIONS.  Section 11.121 describes these changes.

While installing YARNDIAL, you will be prompted for whether you want
to use Souper or VSoup, and if you use VSoup, for the number of threads
you want to use (normal starting point is 4 but I find the maximum of
10 works fine).  You will also be prompted for how aggressive the
mutithreaded news retrieval process is conducted; I use 2 (most
aggressive); 1 is recommended as a starting point.

Souper and VSoup employ different command line syntax.  Refer Section
11.122 for more information.

You must make sure the respective VSoup.exe and Souper.exe programs are
available to the YARNDIAL program and the best way to do this is to copy
VSoup.exe, Souper.exe, or preferably both, into the directory you have
identified as the YARN directory  (in my preferred installation, the
YARN and HOME directories are one and the same; that may not be the case
with your setup).  The VSOUP variable in YD_PARMS.DAT will be set to
whichever of these you indicate you will be using at time of installing
YARNDIAL, and you can change it later if you decide to switch between
one and the other.  YARNDIAL always  checks if the correct Souper or
Vsoup program is available (in the YARN directory) and informs you if
the one you elected to use is not found.

            11.12   CHANGES THAT HAVE BEEN MADE IN YARNDIAL TO ENABLE
                    VSOUP SUPPORT, AND APPLICABILITY TO SOUPER
               11.121   DIRECTORY STRUCTURE
My own personal, recommended, preferred (etc.) directory structure for
YARN/SOUPER is to use one and the same directory as both the HOME and
YARN directory.  Thus the environmental variables %HOME% and %YARN% will
be the same.

Whether you did this or not YARNDIAL was also set up to use a single
%HOME%\incoming subdirectory as a temporary for both mail retrieval and
news retrieval, at least up through v 1.41.

A common directory for %HOME% and %YARN% is still recommended and
as before is not required, but a change has been made starting with
v 1.42 in respect to what temporary directory or directories into
which mail and news are retrieved.  YDINSTL (starting with v 1.42)
sets up separate %HOME%\YARN\IN\MAIL and %HOME%\YARN\IN\NEWS
directories so that mail temporaries and news temporaries are in
different directories.  The YARN subdirectory in those paths
is the directory in which the Yarn CONFIG file resides.  In v 1.5x, the
directory structure was elaborated such that in the %HOME%\YARN\IN
directory, we create not only mail and news subdirectories, but for
multiple ISP's we create mail2, news2, etc. directoies so there
is both a news and a mail directory for each ISP.

Those %HOME%\YARN\IN\MAIL and %HOME%\YARN\IN\NEWS directories
are the directories in which the respective  SOUP.ZIP's are created upon
MAIL or upon NEWS retrieval.  YARNDIAL imports mail first, then news,
then posts, using successive subroutines.  Of course you can choose which
of those or all of those you want to run in a given session by how you
respond to the main menu prompts.  In each of the MAIL and NEWS
retrieval subroutines, YARN's IMPORT.EXE program is run after SOUP.ZIP
is created.  It both imports  SOUP.ZIP into yarn, and erases SOUP.ZIP
afterwards.

Separate temporary directories for incoming mail and incoming news, and
specifically the %HOME%\YARN\IN\MAILx and %HOME%\YARN\IN\NEWSx
subdirectory structure, and even the directory names used are adopted
from Hardy Griech's VSOUP, with appreciation.

               11.122   COMMAND LINES: SOUPER vs. VSOUP AND OTHER
                         COMMAND-LINE ISSUES

Souper and VSoup employ different command line syntaxes and some command
line options are different for the two programs, as shown here, with
news retrieval from the nntp server used as the example:

         souper.exe options newsserver userid password

         vsoup.exe different_options nntp://userid:password@newsserver

You may also be faced with the possibility that in either the Souper or
VSoup situation, you may need to specify pop ID and password, maybe
login ID and login password, or maybe neither or maybe just one of them.

Therefore three new variables were added to YARNDIAL's YD_PARMS.DAT
file:

     GETMAIL_AUTHO
     GETNEWS_AUTHO
     SEND_AUTHO

which allows you to switch between how ID and password authorizations
are handled on command lines for accessing the servers (see also
Section 11.124)

These AUTHOrization parameters apply to both Souper and VSoup and
the permissable settings of 1, 2 or 3 mean the following (illustrated
for
news retieval):

     GetNews_Autho=1         Uses POP ID and POP Password
     GetNews_Autho=2         Uses Login ID and Login Password
     GetNews_Autho=3         Uses servername without either ID or
                                Password specified in the command

The default for all three authorization parameters (GETMAIL_AUTHO,
GETNEWS_AUTHO, and SEND_AUTHO, is to set them equal to 1, which
means to use POP ID and POP Password.

               11.123   NO MORE YD_ALT.DAT PARAMETER FILE
This was added in v. 1.42 but removed in later versions.  Alternate or
additional ISP's can now be added to the end of the YD_PARMS.DAT file
that is created during installation.  There is rather complete
documentation for this in YD_PARMS.DAT itself, which is to be found
in the Yarn %HOME% directory.  Print it out after you have installed
YARNDIAL.   See also Section 3.20.

               11.124   AUTOMATIC BACKUPS OF SOUP.ZIP
YARNDIAL v 1.42 now creates backups of the MAIL-retrieval SOUP.ZIP file
as a default.  This idea was proposed by Robin Klitscher who, like me,
would occasionally suffer a botched mail reception or importation.
Though Robin puts backups in a directory separate from the one used as a
temporary, I put it in the same one.

By default we back up the mail SOUP.ZIP and not the news SOUP.ZIP.  You
can change this.  In YARNDIAL are two statements:
               make_mail_soupzip_backup = 1
               make_news_soupzip_backup = 0
1 backs up, 0 doesn't.

                  11.1241   RESTORING FROM THE BACKED-UP SOUP.ZIP
The following procedure is recommended:

- Run YARNDIAL and select and run the Rebuild option from the main menu
(Option 6).  This zips up any files left as debris from the previous
retrievals of mail and/or news, and imports the resulting SOUP.ZIP.
If the previous retrieval processes had already created the SOUP.ZIP
but not imported it, this imports it.

- Next, in an OS/2 window, change to the %HOME%\YARN\IN\MAIL directory
if you want to restore SOUP.ZIP, for a backed up mail retrieval, or
change to the %HOME%\YARN\IN\NEWS directory for news.

- Rename the appropriate backed-up SOUP.ZIP back to SOUP.ZIP or copy
it to SOUP.ZIP (renaming eliminates that particular backup; copying
it preserves it).  The "appropriate backed-up SOUP.ZIP" will be named
SOUP.ZIK for the most recent one, and SOUP.ZKK for the one just
previous to that one.

- Repeat the previous two steps for the other incoming dir if you want
to restore both a mail backed-up SOUP.ZIP and news backed-up SOUP.ZIP
at the same time.

- Start YARNDIAL and run the Rebuild option.

- Done.



               11.125   (CHANGES IN) HOW SCHEDULED OPERATION WORKS
This is for those of you that use a scheduler, such as CHRON or ROBO
(I do not).  My own kludge, TIMER.CMD, included with YARNDIAL v 1.41,
was left out of later distributions.

There is no longer a discrete variable, CHOOSE, in YD_PARMS.DAT.
Instead, YARNDIAL now takes a command line argument and internally
assigns it to the CHOOSE variable.  As before (v 1.41), if CHOOSE is
anything but a blank, prompting is suppressed and YARNDIAL starts,
dials, runs, and completes without interruption.  If there is no
command-line argument, YARNDIAL operates as before (="normally").
Consequently, YARNDIAL can be called up by a scheduler program and will
run in unattended fashion.

The command line argument that becomes the CHOOSE setting represents one
of the first five of the  choices (out of the original 7) that appear in
YARNDIAL's usual main menu.  Valid settings for CHOOSE are 1, 2, 3, 4,
or 5 for operation with shutdown of the dialer when YARNDIAL
finishes, or ~ ! @ # $ or %  (these are SHIFT-1 through SHIFT-5 on a US
keyboard) if the "do not kill connection' was opted for; these leave the
connection up upon completion of YARNDIAL.

A typical command line to run YARNDIAL with a scheduler program to get
mail and retrieve news (Main Menu option 3) would look like either
        YARNDIAL.CMD 3
or
        cmd.exe. /c YARNDIAL.CMD 3
depending upon whether your scheduler requires the command processor
that calls up YARNDIAL.CMD to be explicitly indicated in the executable
command.

This (these) command lines should both shut down the phone connection
after YARNDIAL has finished; and there will be suppression of prompting.

However, either
        YARNDIAL.CMD #
or
        cmd.exe. /c YARNDIAL.CMD #
would perform the same news and mail retrieval operations but the phone
and internet connections would remain up at the end (# is SHIFT-3).

Suppression of prompting occurs whenever the variable CHOOSE is set with
a valid command line argument.  So you could also enter an argument in
the Parameters field of the YARNDIAL object and it would behave as if
it were a command line argument.

In v 1.42, I have made it more difficult to run with a scheduler in the
"do not close connection when YARNDIAL is finished" mode.   If you
really want to do that, you must edit a variable I added to
YD_PARMS.DAT, namely OVERRIDE_DNK_DURING_REMOTE.

OVERRIDE_DNK_DURING_REMOTE is defaulted to 1 during installation.  That
overrides leaving the connection up when running YARNDIAL with a valid
command-line argument.

OVERRIDE_DNK_DURING_REMOTE must be set equal to 0 to retain the
"do NOT kill connection" option whenever CHOOSE is set as a command line
argument.  If you run in normal operation with no command line argument,
there is no override and the "do not kill connection" mode operates as
expected.

The risk in any unattended "kill connection" or "do not kill connection"
mode is that some error might cause YARNDIAL to fail and could
unintentionally keep your phone connection up so you generate excessive
phone and connect-time charges.

I do not use YARNDIAL with a scheduler program for that reason.

A change, begun in v 1.41 but cleaned up in v 1.42, and which
improves reliability of unattended operation for those of you with more
courage than I possess, is in local error trapping.

Local error trapping is now on by default (you must edit YARNDIAL.CMD
to turn it off).

The exit routines in the event of an error are more likely than before
to close YARNDIAL normally and shut down the phone connection.

Even if you have selected the "do not close connection" option and
have set  OVERRIDE_DNK_DURING_REMOTE to 0, if YARNDIAL does
encounter an error, it should, on exiting,, reverse that option and
close down the phone connection.

Since I do not use a scheduler, it would be helpful if someone who does
would check this out and see if the connection is really closed down
under unattended operation in "do not close connection" mode for the
whole gamut of error types: Syntax, Error, Failure, NoValue, Halt and
NotReady.  You of course will have to generate those types of errors in
controlled fashion.  I only generate them by misadventure.


12.00  YOU HAVE NOT INSTALLED YARN AND SOUPER?
Sections 27.00, 28.00 and 29.00 have very detailed instructions.


13.00  HISTORY
YARNDIAL started out as a ReXX program which in the beginning did
little more than do the work of an flock of OS/2 batch (.CMD)
programs to automate dialup, automate the operations of Souper and
Yarn to get mail and news and send mail and posts, and - to create
a user-friendly menu-driven installer and to creatthen close the
connection.  ReXX offered an easy-to-program user interface for
unattended operation once YARNDIAL was started. ReXX allowed me to
set up menus much more easily than with batch programs.

The earliest versions of YARNDIAL were configured by editing them
with a text editor.  As more and more features and variables were
added through a succession of beta versions, editing became more
extensive and required more knowledge on the part of the user.
Thus, configuration by editing YARNDIAL.CMD was both tedious and
prone to user error.

I decided -- starting with v. 1.3 -- to develop an installer to provide
a friendlier set up.  The installer (YDINSTL.CMD) creates a unique data
file in each Yarn user's home directory to store parameters.
YDINSTL.CMD does its thing with minimal need to study this external
documentation you are now reading.  Most input screens either request
the input of information twice so that verification is accomplished by
duplication, or it checks for existence of files or directories and
accomplishes verification automatically.

   13.10   VERSION HISTORY
      13.11   YARNDIAL.CMD AND ITS COMPANION INSTALLER YDINSTL.CMD

13 Mar 97     YARNDIAL.CMD v. 1.53
  Some fixes

04 Mar 97     YARNDIAL.CMD v. 1.52 (GA Release)
  Numerous small changes/customization/corrections so runs
  equally well under Object ReXX as well as Classic ReXX

25 Jan 97    1.50 (final beta)  with multiple ISP capability


07 Dec 96 to 24 Jan 97   Fixes, improvements, elaboration of v. 1.42

07 Dec 96   BETA Release 1.42 (YARNDIAL.CMD and YDINSTL.CMD)

   VSoup is supported (multithreaded, so faster alternative to Souper).

   Removed TIMER.CMD, but improved ability to use with  other, better
   scheduler programs.  CHOOSE variable is no longer in YD_PARMS.DAT but
   is instead expected as a command line argument for use with scheduler
   programs

   Improvement in how local-error-trapping functions

   A new data file (YD_ALT.DAT) to supplement YD_PARMS.DAT

   New directory structure: more like what VSoup uses

   Fixes applied to all outstanding problems for which root cause
   has been identified

24 Sep 96   BETA Release 1.41 and 1.41a (YARNDIAL.CMD and YDINSTL.CMD)

   Added TIMER.CMD as a program to run YARNDIAL.CMD remotely
   that is, to run it, unattended, at preset times.  TIMER.CMD can
   execute YARNDIAL.CMD unattended and re-run at set intervals,
   or it can execute YARNDIAL.CMD, unattended, but one time only.
   (TIMER.CMD was taken out in v 1.42)

   There are some new screens and a few changes in YDINSTL.CMD.
   Default for LOCAL_ERROR_TRAPPING in YARNDIAL.CMD is now
   set to 1 (local error trapping is enabled).

   INTERFACE_REMOVAL can now be set during the install and it is
   recommended you set it to 2 (unless you run with multiple modems
   simultaneously connected AND setting it to 2 gives you problems.
   In that event, set it to 0 which is no interface removal).

   YD_PARMS.DAT has a new variable: CHOOSE which is used when
   YARNDIAL is run in unattended fashion using the TIMER.CMD
   tool.

   v 1.41a was a maintenance release.


15 Aug 96 - 17Sep96 versions 1.32x - 1.34(beta) (several)
   For IN-JOY dialer, added ability (optional) to wipe out phantom
   router interfaces left up after IN-JOY shuts down.

   Further improvement in router interface recognition.

   Optional prompting during the install for all parameters
   needed to run Souper, so you do not absolutely need to set up
   slippm.exe to use (for example) in-joy.  Configuration of
   slippm for installation of YARNDIAL for dialers other than the
   IAK dialer and SLIPPM itself and ILINK/2 is still strongly
   recommended as it is a time-saver.

   Added feature that YARNDIAL can be run either to kill the
   connection or not to kill it when YARNDIAL finishes.
   Improved ability to distinguish which connection is up if one
   is up when YARNDIAL starts.

   Eliminated need for tempfile in wait-for-interface routines.

11 Aug 96 v. 1.32(beta)
   Changed the YARNDIAL wait-for-interface and related subroutines
   to accomodate a changed netstat.exe released as part of the
   Merlin beta.

   Changed menuing of dialer support in the installer.  ILINK/2 is
   now supported as a menu item. You can also specify other
   dialers not specifically mentioned in dialer menus.

25 Jul 96 v. 1.31 (beta)
   Improved error-trapping.  Added variable to toggle error-
   trapping on and off in both YARNDIAL.CMD and YDINSTL.CMD using
   the new local_error_trapping variable.

19 Jul 96 v. 1.3 (beta)
   Numerous additions, major cleanup of the code.  Added a
   separate installer (YDINSTL.CMD, v. 09(beta)).

11 Jun 95        YRNDIAL1 (v 1.1) (NO INSTALLER)
   Fixed screwed up backing up of replies .Zip file

11 Jun 95        YARNDIAL (1.0, original)


14.00  SHOULD YOU UPGRADE ANYTHING BEFORE YOU INSTALL?
If you are using the Warp IAK Dialer, or using (or intend to use)
the IBM Dial-Other-Internet-Providers utility (SLIPPM), you may
need to update. That should be available by connecting to an
updates ftp site.  See Section 33.00 for reference to a link.


   14.10   SOUPER
There were some major changes in recent SOUPER versions.  You
should be using SOUPER 14 or 15.  I cannot be sure earlier
versions will be able digest all of the command-line arguments I
have tacked on to Souper when YARNDIAL runs.


   14.20   IBM/ADVANTIS IAK DIALER
            (FOR CONNECTION TO ADVANTIS ONLY)
If your dialer is version lower than 1.33, you should upgrade.  As
of this writing the latest dialer is v. 1.65.  You can upgrade by
signing on to Advantis in the usual way, double clicking on the
Retrieve Software Updates Icon, and downloading the latest Dialer.
Installation is automatic if you go that route.  Upgrades may also
be available off ftp sites supported by IBM/Advantis.

   14.30   SLIPPM.EXE (DIAL-OTHER-INTERNET-PROVIDERS UTILITY
            AND SLIP UPGRADES)
This utility allows you to connect to a provider other than
Advantis by either SLIP or PPP, but you may need to get the most
recent version or update SLIP and TCPIP.

If you installed TCPIP and Internet Access as part of a Warp
Connect installation, you are OK.  (Note: If you installed Warp
Connect, you should have installed the Internet Connection
features only as part of the Warp Connect installation or in a
post-installation using one of the Selective Install icons in the
Warp Connect OS/2 System folder, not from the Bonus Pak).

If you are running Warp 3.0 (not Warp Connect) you will have
installed the Internet Access Kit from the Bonus Pak.  You should
upgrade to SLIPPM v 2.0 and the latest TCPIP, if you have not
already done so.  That should be available by connecting to an
updates ftp site.  See Section 33.00 for reference to a link.

        14.40   EMX
(See Section 29.10).  If you will be using VSOUP, you need EMX and
it must be v 09c.


15.00   BEFORE YOU RUN YDINSTL.CMD
Yarn and Souper must be correctly installed.

You must be able to connect with your Internet Service Provider
with the IAK Dialer, SLIPPM, IN-JOY, ILINK/2, a PPP dialup string,
or a SLIP dialup string, or some other dialer.

If you are just using the IAK Dialer,  you do not need to set up
to connect via SLIPPM, the Dial-Other-Internet-Providers
utility.  If otherwise, you should go through the motions of
setting up the SLIPPM to connect to your provider.  And in setting
up SLIPPM, you MUST fill in the names of your news server, your
mail gateway (i.e., your SMTP server), your POP mail server, your
pop login ID, and your pop password even though those are not
mandatory parameters for operation of SLIPPM.

WHY DO THIS?
Unlike SLIPPM, IN-JOY is a connect-only program and does not store
such information as news server, mail gateway, or other similar
information which programs like YARNDIAL needs as parameters.
SLIPPM and the IBM/Advantis IAK Dialer do, using their respective
.INI files, TCPOS2.INI and DIALER.INI.  Furthermore, SLIPPM.EXE,
PPP.EXE, SLIP.EXE use the TCPOS2.INI file to record information
about the current connection.  IN-JOY does not write to TCPOS2.INI
but does have some information aboutr the current connection in
the RESOLV file.

This behind-the-scenes use of the DOIP utility applies to use of a
PPP.EXE or SLIP.EXE dialup string, and use of most other dialers
including IN-JOY and excluding only the IAK dialer.  IN-JOY does
not store all of what is important for YARNDIAL's purposes.
Rather IN-JOY just dials and connects.


16.00   NOTES ON USING THE IN-JOY DIALER
When you set up IN-JOY, it is strongly recommended that you assign
a unique interface name for each IN-JOY host connection you set
up, and have this be different from interface names that may be in
use by other dialers or network connections.

"Interface Name" in IN-JOY is an option on the PPP page (and
presumably will be an option on the SLIP page when SLIP is
supported.  You can use up to 5 letters (all letters; no numbers)
and I suggest (it is not mandatory) you use all 5 positions.  This
gives you 11,881,376 different combinations ignoring upper/lower
case distinctions and makes it overwhelmingly likely that the name
you assign will not accidentally coincide with more common,
shorter names (most common - ignoring case: PPP, SL, SLIP, LAN,
L).  Case, though valid in some interface-name discriminations, is
not important to YARNDIAL's interface-checking routines.

How to identify the current connection if the TCPOS2.INI file is
not written-to by IN-JOY?  One very easy way is if we have a
UNIQUE name for the interface.  NETSTAT.EXE -r returns active
interface routing information, and YARNDIAL can analyze that
information.  Thus, by checking first whether IN-JOY is the dialer
in use, and then comparing the router interface name against the
one in the IN-JOY host configuration data file that we stored in
YD_PARMS.DAT, we can positively ID whether an IN-JOY connection
corresponds to our YARNDIAL user.

The logic is in the get_current_connection() subroutine in
YARNDIAL.CMD and is somewhat complex.  Future versions will no
doubt see changes focussed on that area.

A PROBLEM WITH IN-JOY
I have only encountered one major problem with IN-JOY and that
problem is that sometimes when IN-JOY terminates it does not
remove the interface routing that NETSTAT -r sees when it checks
to see if we are connected to our provider.  Thus if a phantom
interface is left, YARNDIAL dials in, waits for the interface to
appear in the NETSTAT -r output, and it of course sees one
immediately.  So it goes on to get/send mail and news.  But we
are not really connected, so YARNDIAL will sense an error
condition and quit.  Not good.

Starting with v. 1.34 of YARNDIAL, you can use (by editing
YD_PARMS.DAT) a new INTERFACE_REMOVAL variable that allows
you to optionally kill such interfaces when they are left "up" at the
conclusion of YARNDIAL.

I usually set INTERFACE_REMOVAL = 2.

SETTING INTERFACE_REMOVAL:
 INTERFACE_REMOVAL=0   Use this if you regularly establish
   simultaneous connections via SLIP or PPP through more than one
   COM port at a time.  But if phantom routings are left by
   IN-JOY, you will have to live with the problem.  Choose this if
   you never use IN-JOY.
 INTERFACE_REMOVAL=1   Deletes any routing entries left standing
   but only if IN-JOY is your dialer and if the interf_prefix in
   the routing entry matches IN-JOY's.  Suggestion: set the
   interface name in one of the IN-JOY OPTIONS pages to something
   unique for your connection to achieve maximum selectivity
   during operation of interface_removal = 1 (an IN-JOY interface
   name up to five letters long can be used.  Letters only.)
 INTERFACE_REMOVAL = 2    Regardless of the dialer and whatever is
   stored as the interf_prefix, deletes all routing entries at
   shut_down of YARNDIAL.  If you have a problem with phantom
   routings using IN-JOY and never expect to have to make
   simultaneous connections via SLIP or PPP through more than one
   COM port at a time or on your network, try setting
   interface_removal = 2.

If INTERFACE_REMOVAL is set equal to 1 or 2 and a routing is left up
when YARNDIAL exits, the routing is deleted and a message indicating
deletion of the routing appears, with indication of the destination
and router addresses.  The message appears after a line that starts:

   Killing dialers...

and will look like the following:

  delete net 166.72.0.0:  router 166.72.86.98

The two addresses in decimal dot notation are the respective destination
and router addresses that would be reported out were NETSAT.EXE -r to
be run while the phantom routing was up.


WHY SET UP SLIPPM EVEN IF USING IN-JOY?
It is a good idea to set up SLIPPM to connect to your provider
even if you have no intention of using SLIPPM to dial the
provider.  The SLIPPM setup stores parameters in the TCPOS2.INI
file in a manner which makes them most readily available to
YARNDIAL's installer.  As mentioned earlier, in setting up SLIPPM,
you MUST fill in the names of your news server, your mail gateway
(i.e., your SMTP server), your POP mail server, your pop login ID,
and your pop password.  YARNDIAL needs that information.  It is
not mandatory for SLIPPM operation.


17.00   ABOUT THE FIX-INTERRUPTED-IMPORT OPTION ON THE MAIN
        YARNDIAL MENU
What does that do when we've selected it?  First, it assumes
soup.zip might not have been properly created.  So we try to zip
up a file named areas and the various .msg files into an archive
named soup.zip. Shouldn't do any harm if soup.zip already existed
or if we could not find areas or any .msg files.

Then it tries to import soup.zip into YARN (by running import.exe
soup.zip).  Again, no harm done if there is no soup.zip.

Then REBUILD.EXE -s is run, which tries to fix YARN's spool and
history files.

Finally REBUILD.EXE -o is run.  This action tries to rebuild
YARN's history and overview files.

You may see some zip errors.  Ignore them.  They probably mean
that the .zip file being sought was already processed.  You may
also see strange errors such as

          Assertion failed inscur <size   etc. etc >

then after the Fix-Inerrupted-Import option has gone its course,
re-run it.  It should run OK and should (hope springs eternal)
still correct things.

I've only seen that error (once) when I was importing news.  I ran
my Fix option, saw the error first time through, then ran the Fix
option again and did not see the error again.  The rebuild went
OK.


18.00   SOUPER AND VSOUP COMMAND-LINE OPTIONS
YARNDIAL calls up Souper with command-line options to control
whether mail or news is retrieved, or mail, posts, replies are
sent.  These command-line options can be changed or added-to by
editing the YD_PARMS.DAT file created in your home directory after
installation is completed.

These six elements in YD_PARMS.DAT

        souper_getmail_xtra_options=
        souper_getnews_xtra options=
        souper_send_xtra_options=
and
        vsoup_getmail_xtra_options=
        vsoup_getnews_xtra options=
        vsoup_send_xtra_options=

are what gets edited.  Read the Souper documentation before you
make changes.  SOUPER(.EXE) is omitted from these statements.
Thus, if you wanted to have Souper (or VSOUP) to run as

        SOUPER.EXE -r

to retrieve news  without updating the NEWSRC file, you would
change souper_getnews_xtra options to read

        souper_getnews_xtra options=-r

or do the same with the corresponding vsoup_getnews_xtra options line.

The Souper (or VSoup)-get-news and Souper-get-mail options are divided
up into _std_ and _xtra_.  DO NOT ALTER OR EDIT the _std_ options.
They are set up to separate getting mail and getting news so that
you can choose one, the other, or both.

The _std_  options all have Souper running with its -i option.
Souper -i  ensures that the configuration settings for Souper such
as mail server, mail gateway, news server, etc., all come from
YD_PARMS.DAT.

YDINSTL allows you to choose the  -k option (set maximum size of
news-packet), the -l option (that's a lower case "L") (kills
articles that contain more than some number you set of lines in
the body), and the -a option (new newsgroups added).  YARNDIAL
allows you to revise settings on a one-time-only basis for -k and
-l options.  It also lets you choose the -r option on a one-time-
only basis but only lets you change it for mail.  If you select
read-only, you do not empty your POP3 mailbox of mail that you
retrieve.  I use this when I am retrieving mail at a machine other
than my "home" machine.

FROM YARNDIAL you can also call up the -c option on a one-time-
only basis (catch up on news: mark as read all but last n articles
in each newsgroup).

Any of the Souper command-line options except -c can be set by
editing YD_PARMS.DAT.  If you edit, edit (add, remove, change)
the _xtra_options entries.  Don't mess with the _std_options ones.

The -c option cannot usually be added as an option by simply
editing YD_PARMS.DAT because Souper expects -c to be used like so:

        Souper -c 100

or together with the -i option:

        Souper -i -c 100

YARNDIAL, when you select to do catchup, runs the latter example
of use of the -c option.

When you are connected to your news server and Souper -c xxx is
run, article numbers marked as read are appropriately incremented
in your NEWSRC file.  Then, while still logged on to your news
server, YARNDIAL then passes you to a new menu where you can hoose
to actually download the remaining unread ones, or get mail, or
send, etc.


19.00   ISSUES THAT MAY COME UP DURING OR AFTER INSTALL
A unique YD_PARMS.DAT parameter file is created for each
installation.  It is stored in the home directory which is also
unique for each user.  ALL user-definable parameters needed by
YARNDIAL are in that file so that in theory the file may be
manually created, without going through YDINSTL.


20.00   MANUAL INSTALL
If you are about to try a manual installation (not recommended),
an install option is provided that will prompt you for key
parameters.  It usually will provide a functional installation at
that point, but if it does not, you will need to edit YD_PARMS.DAT
to complete the installation.  Godd luck!  It is much easier to
configure SLIPPM!

"I'VE GOT MY PPP.EXE or SLIP.EXE DIALUP STRING AND IT WORKS"
Set up the SLIPPM Dial-Other-Internet-Providers utility anyway
because YDINSTL needs its parameter library.

Run YDINSTL.CMD  selecting connection_type as 3, and after the
installation is done, edit dialup_string in the YD_PARMS.DAT file,
setting

  dialup_string='start' /N abracadabra
        (where abracadabra your complete dial up string which will
        start with PPP.EXE or SLIP.EXE and extend on forever)

The 'start' is important (it is START.EXE).


21.00   MANUAL INSTALL: THE PASSWORD PROBLEM
We encode passwords in YDINSTL.CMD so they will not be exposed in
their original form in YD_PARMS.DAT to the casual eye.  When
YARNDIAL runs, it dencodes them.  If you are trying to manually
configure YD_PARMS.DAT, you may need to create encrypted passwords
for the adv_password, PWD and POP_PWD fields.

This can be done with YDINSTL.CMD using its ENCRYPT command-line
option.  If you run YDINSTL.CMD from an OS/2 command line as
follows:

        YDINSTL.CMD encrypt MyPassword

you will see a line on the screen

        encrypted=xxxxxxxxxxx

where xxxxxxxxxxx will be the encryption of MyPassword.  Other
help info will be displayed.  The number of characters in the
encrypted string will be indicated.

Reference will also be made to a file named word.$$$, which is
created in the same directory from which YDINSTL.CMD with the
encrypt option was run.  The file will contain the same line of
text that was echoed to the screen, and will also indicate the
length of the encrypted password to aid in accurately cutting-and-
pasting it into YD_PARMS.DAT.

Hint: Change to the directory in which YDINSTL.CMD resides before
running YDINSTL.CMD encrypt MyPassword


22.00  CONNECTION_TYPE: THE DIFFERENT CHOICES
CONNECTION_TYPE can be 1 or 3-7.  Very rarely are you likely to
use other than 1, 3 or 4.  Selecting 4 during install brings up a
sub-menu of dialer options.


   1 Installed for Advantis via IAK Dialer.
   2 (Reserved)
   3 Installed for use of a slip.exe or ppp.exe dialup string.
   4 Installed for SLIPPM (IBM's Dial-Other-Internet-Providers.
     Utility) or a SLIPPM replacement such as ILINK/2, IN-JOY,
     etc.
   5 You chose manual configuration: to be prompted for key
     parameters
     followed by manually editing this file as necessary.
   6 Pot-Luck:  Tries to use any connection that happens to be
     established.  Connection must be made BEFORE you start
     YarnDial.
   7 Like 6, but does not check for a connection, and uses the
     string
     in dialup_string to dial.
Anything but 1 or 3-7 for connection_type is an error
condition.


23.00  MORE ABOUT DIALUP_STRING: A PROGRAMMING NOTE
YARNDIAL executes dialup_string by doing:

                 interpret dialup_string

What you enter for dialup_string should consist of the OS/2
executable, the word start (which is the OS/2 executable
START.EXE), plus the dialer executable such as ppp.exe,
slippm.exe, etc., plus any arguments.  Quotes are used where
appropriate for OS/2 executables.  The positioning of quotes is
beyond the scope of this document, but if you have problems, I'll
be glad to try to help ([e-mail]).

Omit the word interpret but always include start.  Depending on
your dialer, you may or may not want to run 'start /N' or 'start'
without the /N or 'Start /c'.  For IN-JOY, the /c should be used
so the OS/2 window is closed after all is done; for SLIPPM it
should not be used.

Below are actual, working, verbatim dialup_strings for real
installations.  Where host_app or account or user, etc., appear as
arguments, those arguments are evaluated to what values the
variables in question have assigned to them.

A slippm dialup_string (connection_type 4):

        dialup_string='start SLIPPM.EXE' host_app

A dialup_string for use of the IAK Dialer (connection_type 1):

        dialup_string='start DIALER.EXE' account user password

A dialup_string for the IN-JOY Dialer ( connection_type 4).  Note
here we need to change to the IN-JOY directory before executing
IN-JOY.EXE (the line below should be all on one line):

       dialup_string=do; 'D:'; 'cd D:\IN-JOY'; 'start /N D:\IN-
JOY\IN-JOY.EXE' host_app; end

In all of the above, YARNDIAL's use of the ReXX function interpret
in execution of the string will mean that host_app is evaluated to
whatever is assigned to it in YD_PARMS.DAT.


24.00  ZIP AND UNZIP FILES
You can probably use a lot of different compression/uncompress
utilities.  Having used InfoZip OS/2 zip and unzip executables now
for years, there is in my opinion no reason not to prefer them.
The installation as much as invites you to be using them.  I am
assuming that if you don't use OS/2 InfoZip utilities you are in
their place using PkWare's version 2.04G zip and unzip programs.
If you are using something else, there is some help provided below
but my own experience curve is a blank.

25.00 COMPRESSION EXECUTABLES: OS/2 VERSUS MS-DOS
If the zip and unzip programs are OS/2 executables (e.g., as the
OS/2 ports from InfoZip), YD_PARMS.DAT will show only the program
names (with paths), along with the appropriate options.  The
latest InfoZip utilities for OS/2 can be downloaded as archives
unz520x2.zip and zip21x2.exe or zip21c2.exe.

If the compression utility programs are MS-DOS executables (e.g.,
PkWare's PkZip v 2.04G), you must have the OS/2 command processor
call them. OS/2's default command processor is CMD.EXE and it
should be used with the /c option, so set

         zip_exe=cmd.exe /c zip    plus options

Examples of zip and unzip options
        For OS/2 InfoZip                zip -0m
        For OS/2 InfoZip                unzip -o

        For MS-DOS PkWare        zip -m -u -o
        For MS-DOS PkWare        unzip -o

26.00  SOME OTHER BREED OF COMPRESSION UTILITIES?
If you want to use another pair of compress/uncompress utilitites,
you will need to set them up carefully.  Have the command
processor call the utilities if they are MS-DOS and not OS/2
executables, and set the respective compress and uncompress
options based on the documentation provided for the particular zip
and unzip utilities.

To help decide on options for some unconventional choice of zip
and unzip utilities, you must know what the options do.  Those for
the InfoZip programs are decoded below:

        ZIP -0m   (That's a zero not a letter "O") (This is
           the  -0 option combined with the -m option)
           -0 means we import the files into the zip package
           with no compression.

           The -m option means we move files in, replacing any
           of the same name, and once they are in we erase the
           originals.

        UnZIP -o  (That's a lower case letter "o" not a zero.)
           -o overwrites files without asking


27.00  FILES FOR SETTING UP YARN AND SOUPER FROM SCRATCH
        Section 29.00 is a detailed roadmap for the
installation of YARN and SOUPER.  It assumes you are doing a
single-user installation or installing for the first user in a
multi-user installation.  Section 28.00 covers the installation of
the three optional files.  Refer to Section 33.00 for sources of
these files.

Files needed:
   EMXRT09C.ZIP     EMX is optional if Souper is version 14 or
                        higher, but is still recommended.  Version 09C
                        or higher is required for VSoup
   METAMAIL.ZIP      (optional but recommended)
   MIME64.ZIP        (optional but recommended) (other mime en-
                        or de-coders are available)
   SOUPER15.ZIP      latest version
   YRN2_091.ZIP     latest version. YRN2_090.ZIP is more readily
                    available.


28.00  INSTALLATION OF EMXRT09C, METAMAIL, MIME64 (RECOMMENDED)

   28.10   EMXRT09C.ZIP (OPTIONAL DEPENDING ON SOUPER VERSION IF YOU USE
SOUPER; REQUIRED AND MUST BE v 09c IFYOU WILL BE USING VSOUP)
Souper versions 14 or higher do not require EMX.  However, EMX
is needed if you want to use metamail to handle mime-encoded
attachments.  It is also needed if you intend to use programs such
as mime64 to encode into mime for attachment to mail and posts, or
to decode mime messages outside of the Yarn and metamail
environment.  It is recommended you install emxrt regardless of
the version level of Souper you are using.

VSoup notonly requires EMX, it requires v 09c (or later).

Installation of EMXRT:
Copy emxrt09c.zip into an empty folder (on an HPFS drive if you
have a choice) and unzip, retaining directory structure.  Use of
the InfoZip utilities (latest unzip is in unzip520x2.zip)
automatically retains the directory structure as a default option.
If you use MS-DOS PkWare unzip utility (pkunz204.zip) you need to
unzip with the command:  unzip -d emxrt09c to retain the directory
structure.

EMXRT09C.ZIP when it unzips creates an emx parent folder (most
.zip archives do not create a parent folder).  There are a lot of
files in emxrt09c.zip and it just makes good sense to unzip it
into a separate directory to contain everything in case of an
unzipping error.  In which case there is only one folder cleanly
isolated to delete.

After unzipping, open the temporary folder and you should see only
one folder named emx.  If not, and you see a horrendous number of
files, that means you did not re-create the directory structure.
You need to!

Assuming you only see the one folder named emx, drag that to
whatever disk you want to install emx to (lets assume D:).  Now
you have a D:\emx subdirectory with all of the emx files in
subdirectories under d:\emx.  You can now delete the emxrt09c.zip.

Edit your CONFIG.SYS file.  Add
        D:\emx\dll to the LIBPATH statement
        D:\emx\bin to the PATH statement

Reboot to complete the installation of emxrt.


   28.20   MIME64.ZIP (OPTIONAL) (Utility to encode/decode mime)
Same procedure as for metamail.  Create a directory d:\mime64 and
unzip mime64.zip into it.  No need for any changes in CONFIG.SYS.

Using MIME64:  see Section 28.323  DECODING MIME WITH MIME64.EXE.


   28.30   METAMAIL.ZIP (OPTIONAL)
Metamail is needed if you want to be able to decode incoming mime
attachments, or attach encoded ones automatically from within
Yarn.

Installation of Metamail:
Create a subdirectory named metamail on the drive where you want
to install it (create, say, d:\metamail).  Place on an HPFS drive
if you have a choice.  Copy metamail.zip into that empty folder,
and unzip it, retaining any subdirectory structure.  I do NOT add
metamail to my path statement in CONFIG.SYS; but rather, I include
the full path to metamail in the Yarn CONFIG file so in Yarn's
CONFIG file I might have

      decode-mime=d:\metamail\metamail %f

That is the most common way.  Alternatively, you could use

      decode-mime=cmd.exe /c d:\metamail\meta.cmd %f

where you call metamail from a .CMD file (here META.CMD).  An
example of such a .CMD file is provided further on.  There are
advantages from calling metamail from a .CMD file which we will
cover later.

Finally, to complete the metamail installation, we will create a
file called MAILCAP.YRN, saving it to the d:\metamail directory.
Mine contains the following lines at present.  Your graphics
viewer could be different.  There are also text editors that do
more (in the context of metamail usage), but the basic OS/2 System
Editor (E.EXE) is adequate.  You get the idea, though, with this
example.  Section 28.32  (Metamail Attachments, Operation,
Decoding) explains a bit about what some of these lines do.

NOTE:  the FORWARD slashes below are correct, even for the paths:
a holdover from the UNIX origins of the metamail.exe port to OS/2

# MAILCAP.YRN
text/plain; e.exe %s
text/*; e.exe %s
image/gif; d:/pmview/pmview.exe %s
image/jpeg; d:/pmview/pmview.exe %s
image/jpg; d:/pmview/pmview.exe %s
image/*; c:/viewer/bin/ib %s


Finally, modify your CONFIG.SYS file, adding

                set mailcaps=d:\metamail\mailcap.yrn

For some (DOS) programs that some people like to call up from
mailcap files, it is useful to also add

                device=c:\os2\mdos\ansi.sys

After you have edited CONFIG.SYS, reboot.

My own preference is to write out e-mail with mime-encoded
messages to disk as files (when you read the message in YARN,
press the s key (lower case "S"), enter the full path and name to
save it as (say d:\thing.txt), and press enter to save.  Then I
decode with MIME64 (see Section 28.323  DECODING MIME WITH
MIME64.EXE).


      28.31  METAMAIL TRICKS
When the content-type of a mime-encoded attachment is not
supported by a local viewer, metamail gives you the option to save
the decoded attachment to a file.  You are asked for a file name
to save to (if you don't provide any -- that is, if you just press
ENTER -- nothing is saved even though you may see a default
filename on the screen).  You must type in a name.

You can specify drive and path, but if you do not specify drive
and path, the default path is your yarn home directory.  This is
not a good thing, since, if the name of the file happens to
coincide with the name of a file already in that destination
directory, you will overwrite the existing file.

To re-define the default directory for this operation, you can
call metamail with a command file that changes to a new default
directory first.

To make this change:
alter the decode-mime line in your yarn config file to

decode-mime=cmd.exe /c d:\metamail\meta.cmd %f

This will call metamail.exe from a .CMD file, META.CMD, an example
of which could be:

/* META.CMD */
/* alters default directory
and then runs metamail*/
parse arg fn
'@echo off'
'd:'
'cd d:\inetdata'
'metamail.exe' fn

d:\metamail is the directory where metamail resides and is where
META.CMD will be saved to.

d:\inetdata is a directory where you will save all decoded files.
it is a useful security practice to keep downloaded and decoded
files in one place where you can conveniently do virus-checking,
etc., before they travel far and wide into your file structure.

The new default directory MUST EXIST because metamail will not
create the directory if it does not exist.


     28.32  DOING MIME ATTACHMENTS UNDER YARN, METAMAIL
             OPERATION, DECODING MULTIPART MESSAGES, AND
             HANDLING NON-CONFORMING MIME ATTACHMENTS

In a MIME encoded attachment which has been correctly attached
from within YARN, the attachment will be at the end of the e-mail
or if several in number, in succession at the end with a lot of
boundary and other conditions met.  If conditions are not all met,
the message(s) will not be decoded directly by metamail, but
metamail may give you the opportunity to save the message (or
messages if more than one), or it may not.  Not to worry: if
metamail doesn't decode, you can still save the entire e-mail as
text and that text file can be readily decoded without grief by
MIME64.

     28.321  DOING MIME ATTACHMENTS UNDER YARN
To do a MIME-encoded attachment:
     Assumes you have metamail properly installed
     (refer sections 28.30, 28.31), and emx is installed,
     and your YARN config file is properly edited)
1.  Post an article, followup, send an e-mail, etc. and get the
ball rolling by pressing r, R, f, F or M from within YARN.
2.  After composing any e-mail text ("Hello, how are you? A file
is attached."), go to the very end of the e-mail and press enter.
The mime attachment will go where your cursor is and this ENTER
assures you of placing the MIME attachment AFTER a carriage
return-linefeed (for that reason I always put an extra carriage
return at the end of my yarn sig file so that my e-mails always
end on a CRLF and not on the last letter of my sig).
3.  Save, exit the editor.
4.  Yarn will present several choices (depending on Yarn version):
   CANCEL
   CHECK SPELLING
   EDIT
   ATTACH FILE
   SEND
5.  Select ATTACH FILE.  You will be prompted for the file name
and a description.  Then press enter and a mime-encoded attachment
will be placed where your cursor was.
6.  Not done Yet.  Save and exit the editor again and select EDIT
from among the choices presented by Yarn.
7. Go down to where the boundary for that attachment is.  Here is
a real-life example of what you will see.

   --1Pz6vtT0gbQ2XEw
   Content-Type: application/octet-stream; name="yrndl132.zip"
   Content-Transfer-Encoding: base64
   Content-ID: <[e-mail]>
   Content-Description: yarndial + ydinstl .cmd files +read.me

   UEsDBBQAAAAIAIc1CyHqvnr/3ms  (etc., start of encoded
attachment)


For a zip file, any other binary, or even a text file, metamail
will decode this and allow you to save it as a binary with a
default name suggested by metamail of yrndl132,zip.

But suppose this file was a graphic name MyDog.gif.  You could
leave it as is and let your recipient save it as a file.

Or you could edit the content-type line, e.g., changing from

   Content-Type: application/octet-stream; name="mydog.gif"

to

   Content-Type: image/gif; name="mydog.gif"

or just

   Content-Type: image/gif;

(refer Section 28.324)

If your recipient has the same MAILCAP file shown above as our
MAILCAP.YRN, when metamail asks: "process this mime attachment?"
and you respond "Y", it will decode the attachment, start up your
viewer (PMVIEW in our mailcap.yrn example), open the decoded .GIF
file and display it.  If you want to save it as a file, you do
that from PMVIEW (using save-as).

Note from this YOU NEVER WANT TO PUT a line like
   application/zip; unzip.exe %s
in your mailcap file, because it would unzip the .ZIP archive and
if there was a directory structure, it could replace existing
files with no opportunity for you to exercise control.

8a.  Still Not done Yet.  Save and exit the editor again.  You can
do another attachment (select ATTACH again, repeat steps 2-7).

   or

8b.  If you have no more attachments, just select SEND and you are
done.

In this example, after the first attachment, we really have a
multipart MIME message.  The first is the original text
("Hello...", and its content line will read something like

   Content-Type: text/plain; charset=ISO-8859-1

this will be opened by our E.EXE editor which our mailcap.yrn file
activates for text/plain content-types.

Then when you've read the message, and you exit the editor, the
second part (the image in our example) is opened by PMVIEW.EXE.


     28.322  DECODING NON-CONFORMING MIME ATTACHMENTS
If you were attaching a message and your cursor was not at the end
of your e-mail text (say it was above your signature), you would
be INSERTING and not ATTACHING (one way to think of it), so the
attachment would go at the cursor position instead of at the end
of the e-mail.  Metamail may not (will not?) recognize this e-mail
as having a valid attachment and will (may) present you with a
message to the effect: "can't recognize this, do you want to save
as text or ignore?".  This will also happen if the initial
boundary (something that starts with two hyphens and
looks like this

          --gc0p4Jq)M2Yt08jU534c0p

but is not preceded by a carriage return (.ie., is in the middle
of a text line like on this line--gc0p4Jq)M2Yt08jU534c0p.

Metamail may let you save the e-mail as text (say as THING.TXT).
Alternatively, From Yarn, after Metamail asks you ("Decode Mime?")
you could respond "N", then save the e-mail as text yourself.  To
do that, press s (lower case "S") while you are reading the e-mail
and after you have responded "N" to "Decode Mime?";  in the window
that appears enter the filename to save to with full path, and
press Enter to complete the save.

Now decode that with MIME64 (next Section).

     28.323  DECODING MIME WITH MIME64.EXE
Say we have saved d:\thing.txt as an e-mail with a single mime-
encoded attachment.  Even if the attachment did not exactly
conform to what metamail expects, running

        mime64 d:\thing.txt

will extract and simultaneously decode, producing a file
$$$$$$$$.$$$ which you can now rename to .zip or .JPG or .TXT or
whatever type it was supposed to be.

Or you could run

        mime64 d:\thing.txt yrndl132.zip

and have it create the correct filename.

Always: I virus check at that point before I do anything more with
it.

I've never mastered how to use the MIME64 program when the text
file being decoded contains more than one MIME-encoded
attachments, but if you use a text editor to separate the text
file you had saved into separate mime parts (each will start and
end with a boundary consting of a double hyphen (--) and some
gibberish, e.g.:

    --gc0p4Jq)M2Yt08jU534c0p

MIME64 will work flawlessly on each section.

So edit so as to preserve the initial and final boundaries for
each mime part, and once they are separated (precision is not
required as long as each separate part has at least the complete
initial- boundary-to-final-boundary encoding), simply run MIME64
on each.


     28.324   CONTENT-TYPE EDITING: MIME ASSOCIATIONS

Content-Type lines that appear in e-mail messages as part of the
MIME attachment (i.e., between the    --gibberish    boundaries)
may look like:

   Content-Type: application/octet-stream; name="yrndl132.zip"
   Content-Type: image/gif; name="mydog.gif"
   Content-Type: image/gif;

The Content-Type application/octet-stream represents the mime-
type/sub-type for binary files in general, i.e., for those with
extensions: .exe, .zip and so forth.  Any file -- binary or
otherwise -- may be typed and transmitted this way.

The Content-Type image/gif represents a mime-type/subtype for a
gif type image file and if the content type in the MIME attachment
header is
       Content-Type: image/gif; name="mydog.gif"

and the line
      image/gif; d:/pmview/pmview.exe %s

appears in your mailcap file (as it does in our MAILCAP.YRN
example, above, replete with its Unix-based forward slashes), when
metamail processes the coded attachment it executes the command

     d:\pmview\pmview.exe mydog.gif

The filename mydog.gif has replace %s and the program called
(pmview.exe) opens the .GIF file mydog.gif.

A list of all recognized MIME media associations is available and
a reference to such a list can be found in Section 33.00.

The general system for how these patterns and associations work in
terms of the practical construction of working mailcap-file lines
can be sketched out as follows:

        (1) For whatever kind of file are you transmitting, define
the content-type/subtype association:  Examples for some image
files: image/gif, image/jpg, image/bmp, image/tif, etc.

gif, jpg, bmp and tif are the subtypes; and correspond to the
.GIF, JPG, .BMP, .TIF standard file extensions (usually the same).

        (2)  Select the program you want to use to open or process
or in general act-on those kinds of files.  Construct one or more
mailcap lines in the form shown below (remember forward slashes
for the paths!)

      image/gif; d:/foodir/foobar.exe %s
      image/jpg; d:/foodir/foobar.exe %s
      image/bmp; d:/foodir/foobar.exe %s
      image/tif; d:/foodir/foobar.exe %s
      image/*; d:/somedir/somebar.exe %s

The last in this train says: any other file of Content-Type image,
if its subtype is not specifcally defined by the other four, try
to open with somebar.exe.


        (3)  Note that if the executable foobar.exe is an MS-DOS
program, it should be called by the OS/2 command processor and
what will appear in the MAILCAP file is

                cmd.exe /c d:/foodir/foobar.exe %s

instead of      d:/foodir/foobar.exe %s

           28.33  UUENCODED ATTACHMENTS (INSERTIONS)
                   UNDER YARN, USING YEP
Note: you need YEP15 or later for this.  See section 33.00
First install YEP.

     28.331  INSTALLING YEP
   1.       Create a folder, unzip YEPxx.ZIP into it.
   2.       Edit the YARN config file: replace what you
            had as editor=xxxxx with the following (use your
            path to yep.exe):
                editor=d:\yep\yep.exe
   3.       Edit the yep.cfg file (but keep it in the same directory
            as yep.exe).  Here is the yep.cfg I use (in its entirety).
            It is set up for use of the OS/2 System Editor.

;START OF YEP.CFG
; Yarn Editor Pre/Post Processor version 1.5 (YEP) config file
; as modified by JLevy
; editor codes: (in your Yarn CONFIG should be editor=yep.exe only)
; $L - line number (set to second line after message header if used)
; $l - (set line number to first line after quoted message if used)
; $F - Filename passed by Yarn...
; This line defines your text editor, and must be in double quotes.
; In this example the editor accepts the -# parameter for line number.
; FTE editor:
; Editor = "FTE -#$L $F"
;
; EPM editor (e.exe) or the Enhanced Editor (epm.exe):
; Editor = "cmd.exe /c e.exe $F 'goto $L'"
; Editor = "cmd.exe /c epm.exe $F 'goto $L'"
; NOTE that the final '" is a single quote (') followed by a double quote (")
Editor = "cmd.exe /c e.exe $F 'goto $L'"
;
; This value is added to (or subtracted from, if a negative number) the
; line number passed to the editor above; for fine tuning preference.
CursorAdjust = "0"
;
; Strip all the unused header lines? "No"/"Yes"
;CleanHeader = "No"

; display the progress dots when entering/exiting Yep? "Yes"/"No"
ShowDots = "Yes"
;END OF YEP.CFG

     28.332  UUENCODED ATTACHMENTS (INSERTIONS)
To do a UUENCODED attachment of the file c:\mydir\thisfile.ext,
insert this line anywhere in your e-mail message (I always put
it at the very end, after the signature):

{UUEN:c:\mydir\thisfile.ext}

The UUENCODED file will be inserted into your e-mail message
in place of that line when you save the message and exit the editor.

     28.333  DECODING UUENCODED ATTACHMENTS UNDER YARN
This works for YRN2_092.  I don't know which earlier Yarn versions
had the uudecoding feature, or had a "save-directory" setting in the
CONFIG file.

To decode while you are reading mail:
   Press B (SHIFT-B) and the attachment will be decoded and the
   decoded file saved to the directory you set in Yarn's CONFIG file as
   the "save-directory".

     28.334  DECODING UUENCODED ATTACHMENTS THE HARD WAY
1.  Save the e-mail message as a text file by pressing s while you are
reading it in Yarn, and then saving as a file to disk.

Let us assume you have named it text.txt.

2.  run a uudecoding program (see below)
       uudecode text.zip

and that's it.  The decoder separates the attachment from the rest of
the e-mail text.

UUCODERS/DECODERS
Of course you need a uudecoder program.  There are gobs of them.
Usually the distribution .ZIP contains a uucoder and a uudecoder.

Example:  UUCODE18.ZIP (see Section 33.00 for possible sites),
which preserves extended attributes, works with long filenames, etc.

Install the UUCODE and UUDECODE programs, which for some
involves no more than unzipping into a folder.  For others (such as
UUCODE18), you may also need to place its DLL file in a directory
on the LIBPATH.


29.00  STEP-BY-STEP-INSTALLATION OF YARN AND SOUPER
1.        Create separate temporary directories for each of
          YRN2_091.ZIP and SOUPER15.ZIP.  For example: create
          d:\yarntemp for yarn and d:\souptemp for Souper.

2.        Copy the yarn zipfile into d:\yarntemp and unzip.

3.        Copy the Souper zipfile into d:\soupzip and unzip.

4.        Decide on a name for a permanent yarn directory and a
          permanent home directory (let's assume you use d:\yarnxx
          and d:\homexx (don't bother to create these directories
          as they will be created for you).

HANDY HINT:  It is possible (my opinion, desirable) to use
the same directory as both the yarn directory and the home
directory.

5.        Edit your CONFIG.SYS file by adding
                SET HOME=d:\homexx
                SET YARN=d:\yarnxx
                SET TZ=EST5EDT

Set TZ to your time zone.  Do not fail to set the TZ variable.
VSoup (actually EMX v 09c which VSOUP demands) requires
TZ to be set, and if you set it incorrectly, you could seem
to be getting mail before it was sent and that is not a good
thing.

If you insist on using a version of SOUPER earlier than 14 also
add

   SET NNTPSERVER=news-01.ny.us.ibm.net        (or whatever your
                                                news server is)

If you are using VSoup, VSoup requires that the number of
file handles for EMX (the EMXOPT environmental variable be
set to at least 40.  YARNDIAL sets this for you by setting
EMXOPT=-h40 -c -n.

6.        If you have another program that uses a SET HOME
assignment, REM it out and temporarily add SET HOME=D:\HOMEXX to
your CONFIG.SYS file (then reboot).

You will be able to eliminate the SET HOME and SET YARN
assignments after the installation of YARNDIAL is complete (after
you've run YDINSTL.CMD).

7.        Do not overlook the TZ statement.  You can get errors if
you are way out on local time, and appear to be receiving mail
before it was sent.

8.        If you are not in the eastern time zone set TZ according
to what time zone you are in.  References at the end (Section
) can guide you n how to set up TZ if you live outside the US
or in some exotic location where the time zone is set up in a
weird way.

9.        REBOOT so your new CONFIG.SYS assignments take effect.

10.        Open an OS/2 window or full screen session, and change
directory to the d:\yarntemp directory.

11.        At the [d:\yarntemp] prompt type in ENGLISH D:\YARNXX
(ou s'il tu plais, FRANCAIS D:\YARNXX ).  This creates the
d:\yarnxx directory and copies files from the temporary directory
over to it.

12.        Copy Souper.exe from d:\souptemp to d:\yarnxx.  That's
as good a place as any to keep it.

13.        Add your first user.  In an OS/2 Window or Full Screen
session, change directory to d:\yarnxx.  At the [d:\yarnxx] prompt
type in ADDUSER.EXE and press enter.

Please note that the name and path for the reply-packet file are
not the same as shown in earlier documentation.  What is shown
below is preferred because it is more consistent with what is
required to install VSoup, and setting it up this way now may
save you grief later and doesn't hurt anything.  for d:\homexx
substitute what you have as your Yarn HOME directory.


ADDUSER.EXE will bring up a screen requiring input of 6
parameters.

For our example (remembering that I am [e-mail]), fill in the
blanks:

home directory                d:\homexx   (must be what you
                                        put in  CONFIG.SYS
                                        as SET HOME)
user ID                       jlevy
host system                   ibm.net
User's full name              Jerry Levy
editor program                cmd /c e.exe
reply-packet file             d:\homexx\yarn\out\reply.zip

Actually, I use the Enhanced Editor, version 6.03 which I
have in the d:\epm6 directory.  So I enter cmd /c d:\epm6\epm.exe
for my editor program.

Make sure these six items are exactly the same as what you
have in Yarn's CONFIG when you edit it (step 19).  Note that the
editor is always called by the command processor cmd.exe with the
/c switch.  This allows re-entry to the editor in the event of
successive calls.

Don't add any other users yet.  We'll get to that later.

14.        CREATE A NEWSRC FILE IN THE HOME DIRECTORY
Use the OS/2 System Editor to create an ASCII file listing all the
newsgroups you want to subscribe to.  After each name pace a colon
(no space between name and colon).  These are the groups that
SOUPER will retrieve news from.  You must also tell Yarn you want
to add them (distinction between getting the news and setting Yarn
up to display).  You must run NEWGROUP.EXE (see step 17) to get
Yarn to understand that these are newsgroups you want Yarn to play
with.

Example of a NEWSRC file with two newsgroups:

comp.os.os2.announce:
comp.os.os2.networking.tcp-ip:

        Save this file as NEWSRC in the home directory
(d:\homexx).  This NEWSRC file is owned by Souper and it records
the article numbers you have downloaded from the news server
("read from the news server" even if you never read the article in
Yarn).

        Another file named NEWSRC will be created automatically to
record which articles you have read from within Yarn (really read,
not just downloaded).  This second NEWSRC file resides in the
home\yarn\ subdirectory (in d:\homexx\yarn in our present
example).

        If you add newsgroups, you add them to the NEWSRC in the
home directory.  You do not add them to the NEWSRC file in the
home\yarn\subdirectory.  Leave that file totally alone.

Remember that whenever you add a new newsgroup, you must also run
NEWGROUP.EXE (step 17).

15.        CREATE A SIGNATURE FILE IN THE HOME DIRECTORY
        Use the OS/2 System Editor to create an ASCII file with
how you want to sign e-mail.  For example, it could consist simply
of something like.

                Jerry Levy ([e-mail])
                Marblehead, MA USA

Hit enter twice after the last character is typed so the file ends
in two carriage return/linefeed pairs.

        Save it to d:\homexx.  Whatever you name it and wherever
you put it (I recommend putting it in d:\homexx), its name and
path should be exactly what you set "signature" equal to in Yarn's
CONFIG file (see step 19).

16.        CREATE A LIST OF ALL NEWS GROUPS (this is a different
file from NEWSRC)

(SEE ALSO: NOTE ABOUT ADDING NEWSGROUPS AFTER STEP 22)
        Create a list of newsgroups you are interested in. It's
like the NEWSRC you created but leave out the colons.  Save it to
d:\homexx.  Name it what you wish (say, NEWSLIST.TXT).  We use it
for doing mass operations on keep days and max-keep days.

        Example:

                alt.org.team-os2
                comp.os.os2.announce

17.        SET KEEP AND MAX-KEEP DAYS FOR NEWS
(SEE ALSO: NOTE ABOUT ADDING NEWSGROUPS AFTER STEP 22)
        METHOD 1:        All groups set at the same time and all
                         set the same way
Change to the d:\yarnxx directory.  Then type in (assuming file
you created above is called newslist.txt):

        NEWGROUP.EXE @e:\homexx\newslist.txt 30 30

and press Enter.

        Don't forget the @ sign and the full path to newslist.txt!
This example sets keep days to 30 (first number) and the max we
keep to 30 (second number).  These numbers should agree with what
to indicated in Yarn's CONFIG file.


        METHOD 2:        Each newsgroup set one at a time, or to
                         add new groups one at a time.

Note that in option1 you used the @ sign so that NEWGROUP.EXE
acted on a file named newslist.txt.

        To set keep and max keep days for one single newsgroup
and/or to add a group to your list, you don't use the @ sign. Have
NEWGROUP.EXE act on the name of the newsgroup.  Type in:

        NEWGROUP.EXE comp.os.os2.announce 30 30

and press enter.

METHOD 1 is greatly to be preferred, because re-running METHOD 2
sometimes keeps adding duplicate menu entries into yarn.

18.        SET UP A MAIL FILTER RULE FOR INCOMING MAIL
This is very important:  Before you try to get mail, you must set
up filter rules and it is useful to have one that places all
incoming e-mail into INBOX.  I only set up this one filter rule.
Some people like to create a regular file system with lots of
rules.

Outline:
        o  At the d:\yarnxx prompt, type in FILTER.EXE and press
enter or
        o  If you've installed YARNDIAL using YDINSTL.CMD, open
the desktop folder you created, double click on the YARNUTIL
utility object, and at the prompt enter FILTER.EXE and press
enter.

You are now at the mail-rule window:
        -Press Insert to enter a new rule, give it a name, tab
         to each field, and press enter when done.
        -Press your keyboard INSERT key to insert a new rule
        -Name this first rule MyMail (example).
        -Select the TO field by tabbing to it or using
         combination of Tab and arrow keys.
        -Enter your e-mail address (e.g., [e-mail])
        -Tab to field to enter save-in folder
        -Enter INBOX as the name (all upper case)
         (it is suggested you use the folder name INBOX for
         your genral incoming mail)
        -Press enter to end the session.

If this went OK, you will see the rule MyMail.  If you don't see
it, you didn't do this correctly so repeat.  Usually this is
because some field (e.g, the save-to folder field) was not filled
in.

19.        Now open the d:\homexx\yarn\CONFIG file in your OS/2
System Editor and inspect all entries.  Edit as necessary with an
ASCII text editor.  Superimposing my own preferences, and
illustrating how some of the entries might look, the changes you
might make are:

       =====START OF YARN CONFIG EDITING=====
These lines (at least) are changed

user=nobody     change to your pop mail user id
                (mine, e.g., is jlevy)

name=No Name    your name (mine is Jerry Levy)

host=nowhere    e.g., mine is ibm.net (stuff after

reply-packet=d:\homexx\yarn\out\reply.zip
                Here I like to use precisely what VSoup
                expects to see so why not use it???
                If you use something else, still keep it in the home
                directory, though (d:\homexx in this example)

compress=zip -kjm %f %d/*   I recommend adding full path to the
                               zip file
uncompress=unzip -o %f      Same here

#Reply-To=[e-mail]     Remove the # and change to yours(mine
                            is [e-mail])

#signature=c:\jim\sig       Remove the # and change to
                            d:\homexx\sig.txt, where sig.txt
                            contains how you want to sign your e-
                            mail (e.g.,  name, city, university,
                            etc.)

#address-comments=on        Remove #
#sent-mail=mailed           Definitely remove #
#sent-news=posted           Definitely remove #

Remove the # from each of these 10 items (there is also 1
line you leave the # in for.  It is continuation of a text
line)

# %a            article number
# %C            current newsgroup name
# %f            From: header
# %i            Message-ID: header
# %n            Newsgroups: header
# %t            reply mail address derived from Reply-To: or
                     From: header
# %[name]       value of the header named between the square
                     brackets
# %%            % character
# %?            space character if the WORLDNETribution is
                     less than 80 characters
# \n            new-line character


#mail-attribution=%f wrote:     Remove the #

#followup-attribution=In article %i,%?%f wrote:    Remove the #

#reply-attribution=In article %i, you wrote:       Remove the #

#save-directory = e:\inetdata\newsmail   Remove the # and enter
path
                                          to a default directory
into
                                          which save-to-file mail
goes.
                                          The directory (newsmail
here)
                                          must exist, so create
it.

keep=7            I changed this to 30 (days)

#max-keep=30       I removed the #

#next-screen-context-lines=0       Remove the #.  2 or 3 works
                                   nicely here.
#charset=iso-8859-1               Remove the #

#join-truncated-subjects = 21     Remove the #

#confirm-quit = on                I removed the #

#decode-mime=metamail %f     If you intend to use mime,
                             remove the # and then insert
                             the full path e.g.,
                             decode-mime=d:\metamail\metamail %f)

This final bit of editing of the file concerns colors.  I don't
like the way the default colors show up in a window, so I changed
to this.  Purely my personal preference.

# USENET headers
color header lightgray blue

# specific USENET headers
color header-From yellow blue
color header-Subject yellow blue

# article body
color body white blue

# quoted text
color quote lightgray blue

# more line
color more white cyan

# display colors
color window-border       cyan black
color window-title        cyan black
color window-text         lightgray black

color list-border         cyan blue
color list-title          yellow blue
color list-text           white blue
color list-select         white green

color form-border         yellow blue
color form-title          white blue
color form-text           lightgray blue
color form-active         white cyan
color form-inactive       lightcyan blue

color menu-border         cyan blue
color menu-text           white black
color menu-select         cyan black
color menu-hotkey         lightgray black
color menu-select-hotkey  lightgray white

If you want to try these color settings, just copy and paste this
whole colors Section in place of the defaults in the Yarn CONFIG
file. Save a backup of your original Yarn CONFIG first.

       =====END OF YARN CONFIG EDITING=====



20.   THIS COMPLETES SETTING UP YARN AND SOUPER (SINGLE USER)
At this point you can REM out or remove the SET HOME and SET YARN
environmental settings in CONFIG.SYS.  If you don't need to, of
course, don't bother, but if you had installed another program
which needed its own SET HOME assignment, and you temporarily
REMMED that out, you can now restore it.  Do not remove the SET
TZ=   statement from CONFIG.SYS.

21.   At this point you no longer need your temporary yarn
or Souper directories unless you plan on setting up for multiple
users or multiple providers.  You might consider printing out
documentation files before you wipe these temporaries out.

22.   INSTALLING YARNDIAL WITH YDINSTL.CMD AND TESTING YARN
      AND SOUPER

(SEE ALSO: NOTE ABOUT ADDING NEWSGROUPS AFTER THIS STEP)

SET UP DIALERS
If you are using either SLIPPM (the IBM Dial-Other-Internet-
Providers utility) or the ILINK/2 dialer, you MUST set up
SLIPPM and verify it can connect to your provider successfully
before you run YDINSTL.CMD to install YARNDIAL.

If you are using either the IN-JOY dialer, or a SLIP.EXE or
PPP.EXE dialup string to connect, you SHOULD set up
SLIPPM and verify it can conect to your provider successfully
before you run YDINSTL.CMD to install YARNDIAL.  This is
because the YARNDIAL installer (YDINSTL.CMD) can extract
parameters from the TCPOS2.INI file used to store SLIPPM
setup information.

In setting up SLIPPM, you MUST fill in the names of your news
server, your mail gateway (i.e., your SMTP server), your POP
mail server, your pop login ID, and your pop password (page 3 of
the SLIPPM settings page).

If you are using the IBM/Advantis IAK Dialer and it is
configured correctly, you are ready to run YDINSTL.CMD to
install YARNDIAL.

After that installation is completed (refer Section 1.00) you can
test YARN and SOUPER with a correctly, fully installed YARNDIAL.

A PRIMER ON USING YARN -- TESTING YOUR INSTALLATION
Start it by opening the desktop folder (YARNDIAL) created after
you ran YDINSTL.  Double-click on the YARN-program object.  When
the window opens, click in the upper-right corner to maximize the
window.

        Press F1.  Brings up the help menu (all functions).

        Press Escape.  Returns you (to Yarn).

        SEND AN E-MAIL TO YOURSELF:  Press Shift M.  Fill in the
blank(s) in the window that comes up.  Press Enter and your editor
should start.  Type in your message.  Do SAVE, close the editor.
The Yarn window will return.  Select SEND (should already be
selected, so press Enter).  Press Escape to exit Yarn.  Now start
YARNDIAL, and when the menu comes up, select the Export option.

        GET THE E-MAIL YOU JUST SENT:  (allow time for your
Internet Service Provider to process it, at most a few seconds if
you provider is worth anything, a minute at most).  Start
YARNDIAL, and select the Get-Mail option to retieve it.

        LOOK AT YOUR FOLDERS:  Now start Yarn again, maximize the
window, do Shift-F.  You should see a Mailed folder and an INBOX
folder (if you retrieved your e-mail). If you'd posted something
to a news group, there would also be a Posted folder.  Select one
of these, press Enter, and you can read your INBOX (in-mail), what
you've Posted or wht you've Mailed.
qqq
        PRINT IT:  While the mail is opened (reading your
message), press s (lower case "S").  In the window that appears
enter prn and press Enter.  You can alternatively enter a file
name (path, too) and save it as a file.  There's an entry in your
Yarn CONFIG file for a default directory where to save news, and
if you omit the path when you enter the save-to filename, it
it goes there.

        To back out successively from where ever you might be in
Yarn: use the Escape key.

        To see command-help: Press F1.  Great function summary!

END OF PRIMER.

30.00  NOTE ABOUT ADDING NEWSGROUPS
Sometimes, and I haven't tried to figure out exactly what has to
happen for YARN to behave this way, even after you add groups to
the home directory NEWSRC, and run NEWGROUP.EXE to add a group and
set keep days, or add a host of groups and set keep days all at
one time by running NEWGROUP.EXE @newslist.txt 30 30 (example),
all groups do not show up in YARN's newsgroup lists when YARN
opens.  Not to worry.  If you press either the minus key or your
Insert key, the groups will show up in a list and you can select
them one by one to add them.  These keys are among the commands
listed when you press F1 to bring up YARN's command-help file.

31.00  SETTING UP AND INSTALLING FOR MULTIPLE USERS
If you do use Yarn and Souper for e-mail, and even if you don't,
you really should set up yourself as a user with ADDUSER.EXE even
if you intend to be the only user.  Most installations are for a
single user and involve only one provider.  (Some guides to
setting up Yarn and Souper advise against doing so, but do it!).

After you have set up for a single user, the best way to add other
users is as follows
        a.   You should already have run YDINSTL.CMD and have set
up YARNDIAL for your first user.
        b.  If you haven't wiped out your temporary yarn and
Souper directories, go back and do steps 10, 11 and 12 again,
setting up a completely new yarn directory.  (If you wiped these
temporary folders out, you'll need to repeat steps 1-12).
        c.  Open up the YARNDIAL SUITE folder which YDINSTL
created on your desktop for your first user, double-click on the
YarnUtil icon and enter ADDUSER.EXE as the utility you want to
run.  Set up a new home directory for this new user by filling in
the parameters called for, just as you did for the first user.
        d.  Run YDINSTL.CMD again (the one you ran for the first
user or the on first user or the one copied over into d:\homexx,
doesn't matter which).  When prompted for your Home and Yarn
directories, key in the ones for this new user.
        d.  Repeat steps 14-16.
        e.  Double-click on YarnUtil in the desktop folder you
just created for the second user, and run  NEWGROUP.EXE (see step
17) and FILTER (see step 18).
        f.  Edit the CONFIG file in the YARN subdirectory of the
new users HOME directory (see step 19).
        g.  You're done setting up for a second user or provider.


32.00   CONNECTION KILLED OR NOT WHEN YARNDIAL ENDS
YARNDIAL was originally designed to shut down the dialer and
disconnect from the phone line when it finishes.  This was part of
the original premise of automating off-line retrieval and sending
of news and mail: letting you walk away from the machine without
racking up unnecessarily high phone bills or access times.

Sometimes, however, you may be on-line, and want to get or send
mail, and then return to whatever you were doing on-line without
having to reconnect.  This feature was implemented to allow you to
do that.

The main menu has seven selections.  If you select the "do-not-
kill-connection" option (either at install time or by making
DO_NOT_KILL_CONNECTION=1 in YD_PARMS.DAT, your seven-selection
choice becomes

       1 2 3 4 5 6 7   Executes functions as shown; goes
                       off-line when done
or
       ! @ # $ % ^ &   Same functions; connection remains up


Note: The ! @ # $ % ^ & choices represent shift-1, shift-2,
through shift-7 on a US-English keyboard.  Those alternate "stay-
connected" keys may be changed to suit your own national keyboard
by editing DNK_STRING in YD_PARMS.DAT.


33.00  WHERE TO GET SOFTWARE AND HELPFUL DOCUMENTATION
(this Section is work in progress)

  ftp-os2.nmsu.edu
  ftp site (hobbes.nmsu.edu)
These two are really the same site.
They are the old-reliables and I rely on them below.

Equally, either of these (also these two are the same site):
   ftp.leo.org
   ftp.informatik.tu-muenchen.de

The OS/2 Shareware BBS (703-385-4325) will also likely have
these files.  It can be accessed on the Web as well at
   http://www.os2bbs.com.

A good Web site for searching for software by name or keywords is
   http://castor.acs.oakland.edu/cgi-bin/vsl-front
(those are lower-case "L"'s not "one"'s)

EMX v 09C.ZIP
Optional if you use Souper and Souper is version 14 or higher, but
still recommended because you need emx (can be earlier versions)
for metamail, and for mime64.

If you use VSOUP, you not only need emx but it must be
EMX v 09C.
   ftp-os2.nmsu.edu/os2/unix/emx09c/emxrt.zip

METAMAIL.ZIP
(optional but recommended)
   ftp-os2.nmsu.edu/os2/unix/metamail.zip

MIME64.ZIP
(optional but recommended.  Other mime en- or de-coders are
available)
   ftp-os2.nmsu.edu/os2/unix/metamail.zip

UUCODE18.ZIP
   ftp-os2.nmsu.edu/os2/archiver/uucode18.zip

SOUPER15.ZIP        latest version
  ftp-os2.nmsu.edu/os2/network/tcpip/souper15.zip
  also, links to it on http://www.vex.net/yarn

VSOUP
   ftp.cdrom.com/pub/os2/internet/vsoup127.zip
   ftp.leo.org/pubcomp/os/os2/tcpip/news/vsoup127.zip

YRN2_09x.ZIP        latest version is _092.
   ftp-os2.nmsu.edu/os2/network/tcpip/yrn2_090.zip
   links to yrn2_092.zip are on http://www.vex.net/yarn

INfoZip Utilities (ZIP and UNZIP)
   ftp-os2/nmsu.edu/os2/archiver/zip21x2.zip
   ftp-os2.nmsu.edu/os2/archiver/unzip520.zip

UPDATES OF TCP/IP AND SLIPPM
In addition to the usual IBM sites, a good bet is John
Summerfield's web page.
  http://www.iinet.net.au/~summer/os2/
You will find links to service packages. The IC12657 package is
the latest I could find.  It will take only about 10 minutes to
install.

PPP.DOC
Look for it in the c:\tcpip\etc directory or use the Warp SEEK
utility to find it.

PPPINFO.ZIP
Links to it in
   http://www.vex.net/~x/bells2.phtml

YEPxx.ZIP  (you want YEP15 later)
Links to it in
   http://www.io.org/~tm/bells2.html


SLIPPM.FAQ
   http//www.gnatnet/lstone/FAQ.HTML
   (That's an "L" stone not a "one" stone)

PPDIAL29.ZIP
   ftp-os2/nmsu.edu/os2/network/tcpip/ppdial29.zip
   (Not only for the software but for its documentation)

TZ SETTINGS (Config.sys, time zones)
There is an excellent (readable, complete) discussion in the help
file of the time868 program which can be found at
     ftp-os2/nmsu.edu/os2/network/tcpip/time868b.zip

   Start time868, click on help, and then search 'all sections'
   for TZ.

There is also TZ information in the Master Help Index (it's in the
Warp Information folder).  Search for 'time zone' in the Master
Help Index.

COMPLETE LIST OF MEDIA-TYPES (MIME ASSOCIATIONS)
(MIME TYPE or SUBTYPE and APPLICABLE FILENAME EXTENSIONS)

example : application/octet-stream represents mime type/subtype
for binary files in general, i.e., those with extensions: .exe,
.zip and so forth.
   http://www.isi.edu/in-notes/iana/assignments/media-types
   (document: media-types, plus others in that directory)

ACCESSING RFC's and FYI's, General Internet Information
   General:  try these and wade into them
      http://www.isi.edu/
      http://info.internet.isi.edu/
   Specifically: for RFC's, FYI's:
      http://info,internet.isi.edu/1/in-notes/
        and you will see links
      (note:  that /1/ is a "one" not an "L")
      RFC's that may be of interest for people already confused by
      Mail, MIME and eager to know just how complex it gets:
         RFC1049  Content-type Headers
         RFC1341  Multipurpose-Internet-Mail-Extension (MIME)
         RFC822   ARPA Standard for Internet Messages

GENERAL INFORMATION AND LINKS TO YARN AND SOUPER
FILES, DOCUMENTATION, UTILITIES
   http://www.vex.net/~x/bells2.phtml and links contained therein
   http://www.vexnet.net/yarn and links contained therein
   http://www.nic.com/~cannon/getyarn.html and links contained
        therein
   ftp://hobbes.nmsu.edu/os2/comm/soupinst.zip
         Steve Withers' install notes



34.00  BUGS AND ERROR-TRAPPING
If you have moved the YARNDIAL desktop folder you created during
an INSTALL (for example into another desktop folder), if you rerun
YDINSTL or run OBJECTS.CMD to recreate the folder on the desktop,
the folder does not appear on the desktop, but instead refreshes
the one you moved into the location you moved it to.

We can trap and identify various types of ReXX error conditions:
Error, Syntax, Failure, Novalue, Halt and Notready, by setting

        local_error_trapping = 1

For some kinds of trapped errors when local_error_trapping is
set =1, the line number returned in SIGL is either the end of the
.CMD file or the line jumped to upon the error.  In most cases,
however, SIGL returns the offending line.

JL     Marblehead, MA