INTRODUCTION

Telnets is a set of macro files for Rbcomm, for using the internet to
connect to various telnet sites. Telnets requires Rbcomm; it will not work
without Rbcomm.

Telnets is easy to use, but hard to learn. Telnets is constantly remapping
the keyboard; if you press a hotkey at one telnet site, something happens;
if you press the same hotkey at a different telnet site, something different
happens. That is good, because it means that you always have hotkeys that
are relevant and customized for the current telnet site; but it makes
telnets hard to learn, because you have to learn several different hotkey
sets and you have to remember which one is currently loaded. But if you take
the time to become a telnets expert, you can use telnets to accomplish a lot
in a short period of time.

If you have ever used a communications program to call in to a BBS, then you
need to forget everything you know. Rbcomm is different from other
communications programs because Rbcomm has macro files instead of scripts;
and telnets uses Rbcomm in such a way that the result is completely unlike
any other communications program.

When you use a communications program to call in to various BBSs, you have a
seperate script for each BBS, each BBS is a seperate call. But when you want
to call in to the internet and connect to various telnet sites, then you can
save time and telephone costs by doing it all in a single telephone call.
This requires that you combine all your scripts into a single script which
does everything. Also, different telnet sites will have different commands
for doing the same thing; for example, at one telnet site you would enter a
certain command to download a file; at another telnet site the command to
download a file might be completely different. Therefore, if you want to
have a hotkey for downloading a file, you would need to have one hotkey for
each telnet site, and you would have to remember which hotkey to use at
which telnet site, and you might run out of hotkeys because most
telecommunications programs do not allow many hotkeys; or else you need to
remap the hotkeys every time you change telnet sites. The scripting
languages of most telecommunications programs cannot handle this degree of
complexity; if this is what you want to do, you want telnets.

Telnets is divided into modules. Each module is an rbcomm macro file. For
each module, there is a *.mac source file and and *.rbm compiled file. The
first letter of the name of each module file tells what the module does:
m*  initialize modem
d*  dial and log into hub
h*  hub
t*  telnet to somewhere from the hub
w*  web site modules
There are also ftp and lynx modules, which do not fit into any of the above
categories.

The hub is where you telnet from. When you run telnets, you call and login
to the hub, then telnet somewhere, then exit back to the hub, then telnet
somewhere else, etc.

Files named i*.mac are include files, intended to be included from module
source files; the include files should not be compiled, so there should not
be any i*.rbm files. l*.txt files are log files which are created or
appended to when telnets runs, and which need to be deleted regularly; if
you add any txt files to telnets, do not name the text files something like
l*.txt so they will not be deleted when someone does "del l*.txt" to clean
up the log files; that is why the file "_lynx.txt" is not named "lynx.txt".
*.txt files which do not begin with 'l' are documentation files.

Telnets is controlled with flags. Flags are empty files, files with a size
of 0. Telnets tests whether or not a flag exists, and telnets does one thing
if the flag exits, and does something else if the flag does not exist. Most
flags are task flags; if the flag exists, telnets does the task; if you want
to do the task, you create the flag. Most task flags just push a hotkey,
which does something like getting mail, sending a message, exiting the
current module, or loading a different module. Thus most task flags are a
way to fully automate something which is already mostly automated.

To run telnets, you first edit the file telnets.bat with a text editor.
Check the flags. If a line is 'rem flags/a', then the flag will not be
created. If the line is 'rem >flags/a', then the flag will be created. So
add the '>' if you want to create the flag, and remove the '>' if you do not
want to create the flag. You might want to select the m*, d*, and h* modules
to be used. You might want to comment or uncomment the commands to recompile
some of the modules. Then you might want to edit the ftp or lynx modules, to
create some special hotkeys. If you do edit any modules, you need to be sure
you uncommented the command to recompile the module in telnets.bat. Now you
are ready to run telnets.bat. First it cleans out the flags directory to
remove any flags left from the last time you ran telnets. It creates the
flags you selected, recompiles some modules if you selected that, and sets
the m*, d*, and h* modules if you selected that. Then telnets.bat runs
rbcomm with the m* module, the m* module initializes the modem and loads the
d* module; the d* module dials and logs in to the hub, and loads the h*
module; the h* module checks the flags and may telnet to various telnets
sites, or may do nothing. After telnets is done, it deletes all remaining
flags.

You probably think that is complicated, but once you get used to it, you
will see that it is easy. You just edit telnets.bat, select the tasks you
want to do, run telnets.bat, and it does the tasks you selected. Simple and
fast. As I said before, hard to learn and easy to use. For example, I could
edit telnets.bat to telnet to A and read mail, then telnet to B and download
a file. Then suppose I want to reconfigure telnets to telnet to C and send a
message, then telnet to D and upload a file; the reconfiguration would take
me less than 1 minute.

Note that some things, like initializing the modem or dialing in, are always
done automatically. Some things, like telneting to some computer or getting
mail; can be done manually, or you can press a hotkey to do it, or telnets
can press the hotkey automatically. Other things, like lynx and web stuff,
must be done manually. Some of the things which must be done manually could
easily be automated. For example, we could define a flag to call the alt-d
hotkey and download files, or we could define a flag to call the shift-f1
hotkey and send a message (or we could use the message file as the flag; if
the message file 1 exists, send message 1). ftp could be fully automated.
However, it would be difficult to automate web tasks done with lynx, because
lynx does not send a prompt, so it is hard to know when lynx is ready for
the next command.

The alt-g flags tell telnets to exit the module when telnets has finished
its tasks for that module. The absence of an alt-g flag tells telnets that
telnets should not automatically exit that module. The absence of an alt-g
flag tells telnets that you have some manual task that you want to do with
that module. For any one module, telnets does the automatic tasks first,
then waits for you to do the manual tasks, thus automatic tasks are always
done before manual tasks. But the all the tasks of one module are done
before the tasks of the next module, so you may do the manual tasks of one
module before the automatic tasks of the next module. So you do some
automatic tasks, then some manual tasks, then some more automatic tasks,
then some more manual tasks, etc. The alt-g flag selects an alt-g task, but
you may prefer to think of it as the absence of the alt-g flag selects a
manual task.

If you want to run telnets unattended, just remember to select all the alt-g
tasks, do not select any of the tasks which are always manual, and set the
flags to hangup on errors. Also, I suggest you set the modem quiet flag when
running unattended.

INSTALLATION

I suggest that you make the telnets directory a subdirectory of your rbcomm
directory. This makes it easy to #include macro files from the parent rbcomm
directory into telnets and vice versa. Therefore, you should make your
rbcomm directory the current directory before you unarchive telnets.

CONFIGURATION

The set of files I am including with telnets is the what I actually use,
except I have sabotaged it by removing my passwords. You cannot use it the
way it is because: the modem initialization commands and telephone numbers
are probably wrong for you; you probably do not want to use the same hubs I
use; and the passwords are missing. Configuration is much more than just
filling in a little configuration information; you have to rewrite much of
telnets to match your situation. telnets is not really a program; it is an
example you can study; it is a set of ideas you can use when writing your
own programs.

The first step is to read the rbcomm documentation and learn the rbcomm
macro/scripting commands. But you can skip the parts about the dialing
directory, because telnets does not use the rbcomm dialing directory.

m* modules initialize the modem. You need to make an m* module for your
modem. Make it like one of the m*.mac files. Then you need to add the name
of your m* module to make.bat and telnets.bat. If you have more than one m*
module, you need to select one every time you run telnets. telnets.bat
selects an m* module by copying an m*.rbm file to m.rbm, and then
telnets.bat uses m.rbm as the m* module. If you have only one modem, then
you probably have only one m* module; you might prefer to skip copying an
m*.rbm file to m.rbm and just use your m*.rbm file as the m* module. I have
only one modem, but my modem is slow, so I borrow other people's modems when
I can; I made it easy to change m* modules because I was trying to make it
easy for me to borrow other people's modems.

Next you need to make your d* and h* modules. First you have to choose your
hubs. You only need one hub, but it is ok if you have more than one. Any
computer which you can call in to and telnet from can be used as your hub.
BBSs, libraries, universities, freenets, public unix nodes, or a shell
account at an ISP can be used. If you are not allowed to telnet directly,
you may be able to run lynx, and to use lynx to go to a telnet URL. Ideally
you should get a list of hubs and pick one; in reality lists are hard to
find, and when you do find a list it is usually inaccurate. Ask your friends
what is available as a local call. If you cannot find anything locally, try
searching the internet for lists of freenets, BBSs, public unix nodes, etc.
Then you need to make you d* and h* modules, and add them to make.bat and
telnets.bat.

You can use any m* module with any d* module. Each d* module will only work
with its corresponding h* module. Any h* module will work with any t*
module. Since d* and h* modules are always in matched pairs, we could
combine them into a single module. But the d* functions are only used once;
when the d* module loads the h* module, the d* functions which are not
needed any more are removed from memory; if the d* functions were integrated
into the h* module, the h* module would use a little more memory. Also,
having seperate d* and h* modules allows us to have different hotkeys in d*
and h* modules. An alternate solution would be to select the d* module
before running telnets, then have the d* module select the h* module. This
would guarantee that we always use the correct h* module for the current d*
module. However, it would slow down telnets by a millionth of a second. I
chose to select the h* module before running telnets in order to save that
millionth of a second worth of time; I do things before going online instead
of while online whenever possible; and I have never had a problem with
selecting the wrong h* module. On the other hand, we could have the d*
module select the h* module while dialing; that would slow down the dialing
by a millionth of a second, but dialing time does not count as online time
because the phone company does not bill me for dialing time. Or we could
have the d* module select the h* module after dialing, while the d* module
is waiting for it to connect; it does not waste time to do something while
you are waiting for something else.

You can make a t* module for any computer you can telnet to. Note that there
are telnet BBSs which run traditional BBS software like Pcboard and Wildcat,
but which you can telnet to. I have not included any examples of using
telnets to telnet to telnet BBSs because I have not created any. But there
is no reason why you cannot use telnets to telnet to a telnet BBS.

You can make a w* module for any web site. Telnets does not include many
examples of w* modules because I have not created many w* modules because I
do not do much with w* modules. If you are trying to create a w* module, and
you need to go through a form, the obvious way is to send the URL, send
vt100 down arrows to select the appropriate field, send the text, send more
down arrows, etc, send enter when you get to the submit button. And if they
change the form so that it requires a different number of down arrows, then
you will have to change your script. However, a better way is to understand
how html forms work. When you select the submit button, it sends a URL which
is built up out of the information you entered into the form. If you
understand how that URL is created, you can send that URL in the first
place, and bypass the form.


Note that telnets.bat calls 'c:\fwd\n\grabasc.exe', and ifiletrn.mac calls
'C:/FWD/N/TXZM.EXE' and 'C:/FWD/N/CEXYZ.EXE'. These are free DOS utility
programs which I like to use with telnets. You may want to use different
programs or get these programs or change the directories or eliminate these
references. I downloaded grabasc, txzm, and cexyz from simtel. (If you are
wondering why I have a directory named 'fwd\n', I collect free DOS program
and organize them in a directory named fwd, FreeWare for Dos. Major programs
get their own subdirectories of fwd; files for minor programs are put in
subdirectories of fwd: documentation files go in fwd\d; source code files go
in fwd\s; configuration files go in fwd\c, like unix etc; files which need
to be in the path go in fwd\p, like unix bin; and files which do not need to
be in the path go in fwd\n, n is short for notpath, n is like unix lib.)
Also note that telnets.bat and make.bat expect the rbcomm files to be in
c:\fwd\rbcomm; you will need to change that if your rbcomm files are
somewhere else.




EXIT CODES

If you run rbcomm telnets from a batch file, you can check the exit code to
decide what to do next. This is a good idea if you are running telnets
unattended.

An exit code of 0 means telnets was successful, and the batch file should
not try again.

1 means the script failed, probably because the line was busy, and the batch
file should wait a few minutes and try again. The batch file should continue
to try the script until it gets an exit code of 0, 2, or 3.

2 means the script failed, and the batch file should wait a few minutes and
then try running the script one more time.  Then the batch file should go on
to the next thing.  There should be no third attempt.

3 means the script failed and the batch file should not try again.





FLAGS

general flags, which control how telnets works; set these before
  starting telnets; delete these after telnets is done.
MODEM_QU.IET  keep modem speaker off at all times, even when dialing
  This is for when you program your computer to call in the middle of
  the night when the computers are least busy and the telephone rates
  are lowest, and you do not want the sound of the modem to wake you up.
  You might want to use this when running telnets unattended; probably
  you do not want to use this when running telnets attended.
XONERR   abort, hang up, and exit telnets on any error. If xonerr is not
  set, telnets will stop when an error occurs and wait for the user to
  fix the problem or something.
  Probably you want to use this when running telnets unattended; probably
  you do not want to use this when running telnets attended.

inter-module communication flags, used to pass information to modules;
  set as needed, modules check these when loading, modules delete
  these after checking them.
NOT_RETU.RN  set before starting telnets. Checked by h* modules.
  If it exists, h* module assumes that we have just logged on; if it
  does not exist, h* module assumes we are returning from a lynx, ftp,
  or t* module. This is because on some systems, we
  might get a different prompt after login than after returning from a
  telnet. If there is no difference in prompts, h* modules may ignore
  NOT_RETU.RN.
ERROR    set by alt-o. Also set by alt-h in d* modules. Checked by lynx,
  h*, and t* modules. Lynx and t* modules do not need to check ERROR
  unless RETURN exists. If ERROR exists, module should not expect any
  prompt or do anything; module should wait for user to fix whatever is
  wrong.
RETURN   set by ftp and lynx modules when loading return module; set by
  w* modules when loading lynx module. Checked by lynx, h*, and t* modules.
  h* modules do not need to check RETURN if NOT_RETU.RN exists.
  If lynx module sees RETURN, that means it is returning from a w*
  module and should not expect a prompt. If t* module sees RETURN, then it
  is returning from lynx or ftp module and should not expect to login. If h*
  module sees RETURN, then it is returning from a lynx or ftp module,
  probably this is no different than returning from a t* module, so h*
  module probably does not have to take any special action,
  but still needs to delete RETURN.
LYNX.HUB set by d* module for hub running lynx, deleted after telnets
  is done. checked by lynx module. If LYNX.HUB exists, lynx module should
  not expect a prompt, and not send lynx exit command before loading
  return module.

  The purpose of the NOT_RETU.RN flag is similar to the purpose of the
RETURN flag. It would be possible to skip the NOT_RETU.RN flag and use
the RETURN flag instead; but that would result in more flag sets and
flag deletes, which would make telnets a few microseconds slower.
  It would more precise to replace NOT_RETU.RN and RETURN with HMOD.X,
TMOD.X, LYNX.X, FTP.X, and WMOD.X; which mean exit from h* module,
exit from t* module, exit from lynx module, exit from ftp module,
and exit from w* module. Thus each module could check the flags to
find out which module was the previous module, and act accordingly. That
would be more flexible, and would make it easier to add more features.
But it also means more flags to create, check, and delete; which makes
the code more complicated and slower.

task flags, used to tell telnets what tasks to perform. set these
  before starting telnets, telnets checks these when it is looking for
  the next task to perform, telnets deletes these just before starting
  the task. Each task flag is assigned to a specific module; only that
  module should check or delete the flag or perform the task. Note that
  there is an alt-g task for each hub, lynx, ftp, t*, and w* module.
  The alt-g task does the same thing as pressing alt-g: it logs off and
  exits the current module, and loads the next/previous module. You would
  usually want to do all other tasks before doing alt-g, thus each
  module should not check or do the alt-g task until after it has completed
  all of its other tasks. Alt-g task flags do not need to be deleted
  before doing the alt-g, because the alt-g should not be done until
  all other tasks have been done, and if all other tasks have been done
  you will not need to load the current module again, and if you do not
  load the module again it will not check its task flags again, and if
  it does not check its task flags again, then it does not matter if the
  task flags were not deleted. Alt-g task flags are very important when
  running telnets unattended, because the alt-g task flags tell telnets
  to go on to the next module. You leave out the alt-g task flags when
  you are running telnets manually. The absence of an alt-g task flag
  tells telnets that you have some manual task you want to do. If the
  alt-g task flag is missing, then the module will do all its tasks and
  then stop and wait for you to do your manual tasks. You have to press
  alt-g when you are finished with your manual tasks.
W3.TLN  hub: telnet to w3.org line mode web browser
GDFN.TLN  hub: telnet to GDFN (Greater Detroit FreeNet)
GDFN.EML  tgdfn: read and delete email
GDFN.FTP  tgdfn: run ftp
GDFN.LNX  tgdfn: run lynx
GDFN.AG  tgdfn: alt-g
OSFN.TLN  hub: telnet to OSFN (Ocean State FreeNet)
NCF.TLN  hub: telnet to NCF (National Capital Freenet)
HUB.AG  hub: alt-g


hotkeys

alt-c  continue, look for a task to perform. If there are no
  more tasks for the current module, do nothing, even if
  there are more tasks for other modules. Note that alt-c occurs
  automatically every time a lynx, ftp, h*, t*, or w* module is loaded,
  unless ERROR is found; you may be able to abort the
  automatic alt-c by pressing escape at the correct time. If there
  are no tasks for the current module, alt-c does nothing. If you want
  to look for a task for the next module, try alt-g. If you do not want
  alt-c to occur automatically when a module is loaded, do not set any
  tasks for the module, and then alt-c will do nothing.
alt-d  download or dial, in lynx, ftp, h*, t* and w* modules
  send command to start download, perhaps selected files, perhaps all
  files in current directory, perhaps zmodem, perhaps UUEncode files
  and display, perhaps start file receive program, whatever is
  appropriate for current module. Sometimes the best way to download
  files is to ftp the files to a temporary directory on a remote unix
  computer, then zmodem the files to your computer; in this case alt-d
  should delete the files after zmodem. In d* modules, alt-d sends phone
  number to dial.
alt-e  endwhen, ENDWHEN ALL_XFER if the module allows autodownloads,
  otherwise ENDWHEN ALL. Usually telnets tries to read all mail and news
  as fast as possible, and you read it offline later from the logs.
  Press alt-e when you want to read something online, then press
  alt-w to resume normal telnets operations.
alt-f  ftp, set return module, open ftp log, send ftp
  command, load ftp module
alt-g  goodbye, logoff current lynx, ftp, t*, w*, or h* module. If current
  module is a w* module, load lynx module. If current 
  module is lynx or ftp, load return module. If current module is a t* 
  module, load h* module. If current module is an h* module, hangup and
  exit telnets. alt-g is intended for when you have been doing something
  manually with a module, and are done with that module. Note that alt-c
  will occur automatically after loading a different module after pressing
  alt-g. So depending on what module you are in and what tasks are left,
  alt-g could do just about anything. If you want to hang up, you may
  have to press alt-g and escape several times, depending on what
  module you are in and how many tasks have not been performed
  yet, or you might find it easier to just press alt-x. If all tasks
  except alt-g tasks have been completed, and you have the alt-g tasks set
  correctly, then pressing alt-g will log you off everything and hang up.
alt-h  html, hub   in any module using lynx, alt-h writes the html source of
  whatever is being displayed to a file in the current directory, using a
  filename which is the same as the name of the original file. Are sure
  you know what lynx thinks is the current directory? If there is already
  a file with that name in the current directory, some (all?) versions of
  lynx prompt for whether to overwrite or enter a new file name; alt-h
  fails at this point, which is good because it allows you to enter a
  new filename.
  in d* module alt-h sets ERROR and loads h* module. The only time you 
  might want to do this is if something goes wrong with the d* module; and
  if something goes wrong with the d* module you will probably abort and
  start again, so you will probably never use alt-h in a d* module except
  when debugging.
alt-l  lynx, login    In t* and h* modules, set return module, open lynx log,
  send command to start lynx, and load lynx module
  In w* modules, send the login URL; in other words, send the URL which
  would be sent if you select the submit button of a correctly filled in
  login form.
alt-m  mail   start mail reader, open mail log, read and delete all messages
  without pausing, open telnets log, exit mail reader.
alt-n  name    in d* and t* modules send username/login;
  if there is no username/login, alt-n does nothing.
  alt-n should occur automatically to send name in d* and t* modules,
  so you should not have to press alt-n except when debugging modules
  or when some problem occurs. In ftp module, alt-n sends 'anonymous'.
  In lynx module, and in h* modules if the h* module runs lynx, alt-n
  sends the command to number the links. In w* modules, alt-n sends name;
  but if there is no name, alt-n sends the command to number the links.
alt-o  oops    like alt-g, except do not send exit/logoff commands,
  and set ERROR so next module will not expect a prompt and not do alt-c.
  If you telnet somewhere, but then the telnet connection gets cut off or
  fails to connect, then telnets will be in a t* module but you are actually
  at the hub; you need to switch back to the h* module. That is what alt-o
  is for. Ideally the t* modules should be able to detect a failed
  telnet connection, but when you have a failed telnet connection, you
  usually get an error message from the hub. So for the t* module to
  recognize a failed telnet connection, the t* module would have to ask
  the h* module what error message to watch for, which is not possible;
  or else the t* module would have to watch for all possible error messages,
  which is not practical. You may need to go back more than one module,
  in which case you need to press alt-o more than once. Also note that
  if a connection fails, you may prefer to reconnect. For example, suppose
  you login to some hub, and then telnet somewhere, and then the telnet
  connection fails and dumps you back to the hub. You could press alt-o
  to reload the module for the hub, or you could type in the command to
  make a telnet connection, press alt-t to send the name of the telnet site,
  press alt-n and alt-p to send your name and password, etc.
alt-p  password   send password. alt-p should occur automatically,
  so you should not have to press alt-p except when debugging modules
  or when some problem has occurred. In ftp module,
  alt-p should send your email address.
alt-r  read    in t* and h* modules with email and/or usenet news messages,
  alt-r changes to the lmessags.txt log, reads the current message, then the
  next message, and the next, until it has read the last message,
  then changes to the ltelnets.txt log. alt-r reads as fast as possible;
  you can read the messages later from the message log at your leisure.
  in tw3 module, alt-r pages through the current web page and then lists
  links
alt-s  search    in w* modules, alt-s goes to the search page of the web
  site.
  in tw3 module, alt-s is like alt-r except it does not list links
alt-t  telnet or telephone number    In t* modules, send name of telnet
  site. In w* modules, send URL of web site. In d* modules, send telephone
  number to dial. alt-t should occur automatically, so you should not have
  to press alt-t except when debugging modules or when some problem has
  occurred. Note that alt-t only sends the data part of the command;
  the command part of the command is sent by a different module. For
  example, if telnets was going to send the modem dial command "ATD 888",
  the m* module would send "ATD", load the d* module, and the d* module
  would run alt-t, and alt-t would send "888" and a carriage return.
alt-u  upload or URL   in w* modules send URL of the web site.
  I am assuming this is not a conflict because we will not want to
  upload to web site, we will only upload from lynx, ftp, h*, and
  t* modules.
alt-w  when   restore normal WHENs, see alt-e
alt-x  exit    do not log off, do not load a different module, just hang
  up and exit telnets. Note that it is rude to hang up without logging off;
  you should try to avoid using alt-x; try alt-g instead. 


In d* modules, alt-t and alt-d do the same thing, send the telephone
number to dial. 
This is because I could not decide whether to use alt-t or alt-d to dial,
so I did both. It seems easier to remember that d stands for
dial. However, dialing makes a connection. In t* modules, a connection is
made by sending the name of the telnet site, and it w* modules a connection
is made by sending the URL of the web site. I think it would be more
consistent to have the same hotkey for making a connection in all modules.
C for connect and n for name were already taken, and I was already using
t for telnet site name, so alt-t became the standard hotkey for making
a connection. Likewise, in w* modules alt-t and alt-u do the same thing,
send the URL of the web site.

