Copyright (c) 1994, 1995, 2002 Timothy Rue (3seas@threeseas.net)
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the file fdl.html
-------------------------------------------------------------------------------
*** AI is the Virtual Interaction configuration (VIC) launch program ***
(AI) Alternating-Interface
Brief:
AI - Setup, Start and Stop a VIC, and VIC external control.
This includes VIC to VIC communication and control.
Specific:
(AI) Alternating-Interface - The concept of "AI" is to start-up a
Virtual Interaction Core (VIC) with options of setting the basic
starting contents of the configuration parts and to also shut a VIC
down. AI is also used to allow one VIC to communicate and control
another. It is one way to access a VIC from an external program.
ON VIC NAMES and NUMBERS:
A name may be given to a VIC to allow accessing a VIC by name
but also a number is automaticly assigned to each VIC at startup.
The number is automatic and unique but the name need not be unique.
Both name and number are used together to distinguish between VICs
of the same name. If a name is given more than once, the number is
in relationship to the active count of the name use. If no name is
given the number is in relationship to VICs with no name. Numbers
start with '0' and any new VIC with the name will be numbered one
higher than the highest existing given name number.
In using VIC name/# as arguments, if the number part of the
argument is omitted the VIC with the given name and *Highest*
number will receive the line. This applies to all references of VIC
name/# arguments given below.
ON UNIQUE ACCESS and CONTROL:
AI is unique from the other external access points of a VIC. It
is unique in that the VIC does not need to know ahead of time where
it is getting input from. SF, IQ, and ID are other ways to
externally access a VIC.
From a programmers perspective AI makes use of SF and PK in
setup, start, control, and shutdown of a VIC. AI also keeps an
internal list of all information or data it needs to perform its
functionality. This could be in the form of a list of directory
paths to all VICs, and inherently included VIC name(s) and number
counts. This internal list might be a simple ASCII alpha-numeric
list of VICs, each followed by its directory path and then
software code address. This is of course, to be determined in
creating the VIC program code.
On initial startup of a VIC, AI works as a typical command with
argument/options. Once up, the VIC can be accessed by the name/#
by running AI again with the existing name/# argument. The
limitation of this is: only one SF line can be entered at a time,
but if more than one line is needed, the one line can tell the VIC
where to get the rest.
AI TOP PRIORITY:
AI has top priority over the other commands within a VIC. AI
can be considered the master external control of a VIC. Any AI
command given to a VIC, is processed ASAP. Meaning the current step
in progress will finish, then the AI command.
If run from a command line shell or another VIC, the VIC
detaches itself from the shell or VIC, allowing the shell or VIC to
continue it's work.
On initial execution of a new VIC, AI sets up the PK-file and
makes available the internal commands. The PK-file, default or
otherwise, is loaded first so that any other arguments are written
over in their proper location within the PK-file.
ON DIRECTORY CREATION AND USE:
(Note: Due to the abilities of the VIC, it is easy to get around
much of the following in regards to file alteration. But not
through built-in abilities of the VIC. Also, for most applications
the following will be little used or should be used as little as
possible, in effort to keep things simple. In other words, don't
use more than you really need.)
A default "home" directory can exist while not needing to be in
the system path or current directory. This is done by assignment of
"VIC-HOME" to the selected directory. If this assignment is not
made prior to the initialization of the first VIC, then the current
directory will be the "VIC-HOME" directory. In any case, it is
possible to have two "VIC-HOME" directories. One by assignment via
user/system and the one that is used upon initialization of the
first VIC. These may be the same but the user/system assignment may
be changed. In determining which "VIC-HOME" to use, the user/system
assignment is looked for first. If not found, then uses the initial
"VIC-HOME".
Each VIC, including the first, will have it's own directory
"room", if it doesn't exist it will be created. The placement of a
VIC directory "room" will be as a sub-directory of either the
"VIC-HOME" directory or as a sub-directory of the VIC "room" that
started it. The name of the directory "room" is taken from the
"name/#" the VIC is given at startup.
The purpose of doing this is to allow the possibility of VICs
using the same files but modifying and saving different versions.
And has the added benefit of creating a SPAWN MAP (from the
directory tree.) Thus, giving a method of organization, structure,
and control of multi-VIC file usage.
THE RULES OF USE: NO VIC is allowed to modify or delete another
VICs "room" files but can make copies into it's own "room".
However, a VIC can be commanded, by another VIC, to modify or
delete it's "room" files. These files will generally be the
PK-files, OI-files, and KE-files, but may also be ID-files,
IQ-files, SF-files, output files and other VIC room files.
The "VIC-HOME" directory is a special directory following rules
of file protection. Typically, write protected files are files you
want to keep unaltered, such as default.?? files, specific start-up
files and VIC sub-process files. If a VIC tries to write to a write
protected "VIC-HOME" file, it will instead write the file to it's
"room". "VIC-HOME" read/write files are treated as global and may
be modified by any VIC. But only if the VICs accessing it use the
"VIC-HOME" assignment. VICs accessing files in the "VIC-HOME" via
real path or other assignment will only make a copy for their own
"room", and only in the event of modifying the file.
(NOTE RELAX: The use of "room"s and "room" files is not as scary or
messy as it may sound. For the most part the rooms and files are
temporary and few, unless you get into heavy experimentation. But
even here there is structure. Also such directories and files are
likely to be removed upon exit of the complete VIC system. It makes
possible easy data and VIC process passing between VICs.)
ON (optional VIC-HOME:) AND (optional PATH:) USE:
The use of (optional VIC-HOME:) in the following arguments all
work in the same manner. Any files created will be placed in the
VIC-HOME directory and noted in the PK-file. Existing files in the
search path are copied to the VIC-HOME directory, if not already
there. If a file already exist in the VIC-HOME directory and is
write protected, it is copied to the VIC "room" directory and noted
in the PK-file. Specifying the path (optional PATH:), and if the
VIC-HOME is also specified, a copy is placed in the VIC-HOME
directory. Otherwise a copy is placed in the VIC "room" directory.
However, if a file(s) is not found in a specified "PATH:", the VIC
exits with an error message(s) noting the problem(s).
(Note: If there is need to have a non-write protected copy, of a
VIC-HOME write protected file, in the VIC-HOME, simply rename a
copy of it and save it to VIC-HOME. Also, to update files for
other VICs to use, it is best to update in the "room" then move
or copy the update over the older version in the older versions
directory. The use of "room"s adds a measure of safety in updating
and using files, even though they may be just temporary files.)
ON VIC DEFAULT FILES and DATA CREATION:
On initialization of a new VIC any required files and data not
supplied or not found in search path will be created as follows
(with exception of specified "PATH:" option mentioned above):
If a PK-file is created it will contain all the default required
data not otherwise supplied on the command line. Minimum required
files and data are: the PK-filename "default.pk", OI-filename
"default.oi" (created if not already existing), IP set-options to
console keyboard (stdin), OP set-options to console window (stdout),
SF-filename set to (default.sf) or interactive mode if the
default.sf file does not exist, IQ-filename set to "default.iq"
(if exist), ID-filename "default.id" (if exist), KE-filename
"default.ke" (if exist.) Any files created will be placed in the
VIC "room" directory, unless "VIC-HOME" is specified. All other
data, unless specified on the command line is left unset.
SEARCH PATH:
Unless a path is specified, the search path for all the following
arguments are: first the current directory, the VIC "room",
"VIC-HOME", then system path. If a path is specified, only the
specified path is checked and if the file is not found, the VIC
produces an error message.
ERROR OUT WINDOW and SF USER INTERFACE:
AI does have a single error/info out window, regardless of how many
VICs are in use. This window may be closed but AI will re-open it
in the event it is needed. All error messages are proceeded by the
VIC name/# they are generated from.
Debug mode: An SF user interface is opened whenever an error occurs
from any VIC already up and running. This interface contains the
VIC name/# of the VIC it is connected to. The VIC causing the error
is set to step mode and the line in error is made the current line.
Giving the user an opportunity to correct the error.
Command options:
Initial setup arguments and options:
-------------------------------------
(These options are only available on the initial start-up
command-line of a new VIC)
AI (optional VIC-HOME:)(optional PATH:) (optional -n name)
The minimum command for starting up a VIC. If used with no options
then a "default.pk" file is looked for in the search path. Where
any required default files are not found then one is created but it
will be empty (except for the creation of default.pk). All files
created will be placed in the VIC "room" directory unless the
"VIC-HOME" is specified. In this case, any (default.??) files
created or found will be placed in the "VIC-HOME" directory and
this will be noted in the PK-file. All existing files, listed in
an existing default.pk file will be copied to the VIC "room"
directory except for files specified in the default.pk for
placement in "VIC-HOME". Keep in mind that any files found in the
"VIC-HOME" that are write protected will be copied to the VIC
"room" directory. The PATH: option is defined above and errors
on any missing default.?? files not in specified path, as well as
any missing required files, in a found default.pk file.
If used with the -n name option, gives the VIC a name and is set
in the PK-file.
AI -pk (optional VIC-HOME:)(optional PATH:)filename
or
AI (optional VIC-HOME:)(optional PATH:)filename.pk
(Note: By creating a PK-file manually or in step mode with save,
and before regular VIC start-up, this command can simplify VIC
start-up of a specific VIC process. It may be the best way to
start-up a VIC with extensive PK-file contents. Keep in mind that
the PK-file is loaded first and any other options and arguments
used are written over in the PK-file).
Checks to see if the PK-file exist, if not and no path is
specified, creates it. Otherwise AI exits with and error message.
If found, makes a copy of the file in either it's "room" or the
"VIC-HOME", if specified. Then loads the PK-file. Any required
filename or data, not in the PK-file, is created and/or inserted,
as mentioned above. If the PK-file is obtained from another VIC
"room", the VIC name/# (dir) it got it from is also listed in the
PK-file. This VIC name/# can be different from the SPAWN MAP
directory tree. There can be the spawning VIC and a different VIC
process PK-file used for the new VIC, using this argument/option.
AI -oi (optional VIC-HOME:)(optional PATH:)filename
or
AI (optional VIC-HOME:)(optional PATH:)filename.oi
Checks to see if the OI-file exist, if not and no path is
specified, creates it. Otherwise AI exits with an error message.
If found or created, places the filename in the proper location
within the PK-file as well as makes a copy, if not created, of
the file in either it's "room", or VIC-HOME if specified.
AI -ip (set-options) or AI -i (set-options)
The set-options are: (sample- not listed here)
AI -op (set-options) or AI -o (set-options)
The set-options are: (sample- not listed here)
AI -f (flags)
The flag options are: (sample- not listed here)
AI -sf (optional VIC-HOME:)(optional PATH:)filename(opt. @line#)
or
AI (optional VIC-HOME:)(optional PATH:)filename.sf(opt. @line#)
A filename without optional "@line#" starts at first line in file.
Otherwise the file starts at given line number.
Checks to see if the SF-file exist, if not and no path is
specified, creates it. Otherwise AI exits with an error message.
If found or created, places the filename in the proper location
within the PK-file as well as makes a copy, if not created, of
the file in either it's "room", or VIC-HOME if specified.
AI -iq (optional VIC-HOME:)(optional PATH:)filename(opt. @line#)
or
AI (optional VIC-HOME:)(optional PATH:)filename.iq(opt. @line#)
A filename without optional "@line#" starts at first line in file.
Otherwise the file starts at given line number.
Checks to see if the IQ-file exist, if not and no path is
specified, creates it. Otherwise AI exits with an error message.
If found or created, places the filename in the proper location
within the PK-file as well as makes a copy, if not created, of
the file in either it's "room", or VIC-HOME if specified.
AI -id (optional VIC-HOME:)(optional PATH:)filename(opt. @line#)
or
AI (optional VIC-HOME:)(optional PATH:)filename.id(opt. @line#)
A filename without "@line#" starts at first line in file.
Otherwise the file starts at given line number.
Checks to see if the ID-file exist, if not and no path is
specified, creates it. Otherwise AI exits with an error message.
If found or created, places the filename in the proper location
within the PK-file as well as makes a copy, if not created, of
the file in either it's "room", or VIC-HOME if specified.
AI -ke (optional VIC-HOME:)(optional PATH:)filename
or
AI (optional VIC-HOME:)(optional PATH:)filename.ke
Checks to see if the KE-file exist, if not and no path is
specified, creates it. Otherwise AI exits with an error message.
If found or created, places the filename in the proper location
within the PK-file as well as makes a copy, if not created, of
the file in either it's "room", or VIC-HOME if specified.
AI -s Forces step mode for new VIC. (Also, see below)
AI -w Only works on initial start-up. Opens a watch window
of the PK-file. Note: through SF it is possible to
open and close this window after initial start-up.
AI -u Only works on initial start-up. Opens the user SF user
interface. Note: through SF it is possible to open
and close this window after initial start-up.
AI -e Creates an "error.log" file in the initial VIC-HOME.
Other Options: (available before, during or after initial set-up)
-------------
AI -? Opens the hypertext help system window, at AI help.
(???)(an AI command call to a VIC instance to run IQ
on a VIC-help.iq file for AI help which may contain an
external call to load a web browser and hypertext/html
AI help page.)
AI -l List all current VIC name/#. This may be redirected
using the standard redirection or pipe character. If
not redirected, it is sent to the AI error out window.
AI -s Force step mode on all VIC configurations.
Exception - if used in initial start-up only forces
step mode on the new VIC configuration.
AI -s name/#, name/#,...
Force step mode on given VIC configurations.
Wildcards may be used.
AI name/#, name/#,... SF (single sf command line)
This is the command argument for inserting a command
line into an existing VIC(s), from an external process
and without the VIC(s) knowing where it is getting the
command line from. Only one SF command line may be
entered at a time. Wildcards may be used for the VIC
names/numbers. Any command line may be used. What SF
does not process it sends to the output. If a VIC is
in a step mode, the line given is forced to be
processed. Otherwise it is the next line processed
(consistent with AI's priority mentioned above). See
SF and OP for more information on command lines.
AI exit (optional name/#'s)
Exit given VIC configurations. Wildcards may be used
for name/#'s. If no name/#'s given, exist whole VIC
system. This includes removing the given VICs "room"
directories and files that are not delete protected.
The "VIC-HOME" directory files are only deleted on a
complete exit and only if they are not write protected.
AI exits filename.vic (optional name/#'s)
This halts VICs, saves PK-files, writes a VIC script
then exits VICs. This VIC script can then be used to
restart the VIC processes from where they left off.
This script may be executed from any command line that
could be used to start a VIC, and has access to the
directories of the filename.vic and VIC AI program. In
halting VIC(s) wildcards may be used for the name/#s.
If no name/#'s given, does the whole VIC system. Note:
If VIC system is done in ram:, it needs to be moved to
hard storage before turning off the computer :-)
Examples:
AI -pk DF1:Testfile script.sf -ke Holder