HELP EXAMPLESETSMENU                          Julian Clinton  Feb 1990
                                          Updated J. Clinton  Aug 1992


This file describes the options available on the Example Sets Menu.

         CONTENTS - (Use <ENTER> g to access required sections)

 -- 'New'
 -- . Naming The Fields
 -- . Field Direction
 -- . Specifying The Field Datatype
 -- Specifying The Data Source And Destination
 -- . File
 -- . Procedure
 -- . Example Set
 -- . Literal
 -- 'Generate'
 -- 'Display'
 -- 'Edit'
 -- 'Copy'
 -- 'Delete'
 -- 'Set Current'
 -- 'List All'
 -- 'Load'
 -- 'Save'

-- 'New' --------------------------------------------------------------

This option allows  to create a  new example set.  After selecting  this
option, you will be asked to enter  the example set name. You will  then
be asked to enter the number of  fields there are in each example  (this
is not the same as the number  of distinct data items in each  example -
remember a datatype might read more than 1 data item). This will include
both input and/or output  data and any other  items which may appear  in
each example but can be ignored.

-- . Naming The Fields ------------------------------------------------

You will then be asked if you want to name the fields. This is useful if
you have many different fields which have some kind of semantic meaning.
If you do then you should type in a field name followed by <RETURN>
until all the fields have been named.

-- . Field Direction --------------------------------------------------

Next you will be asked to enter  the direction of each field. This  will
be one of: in, out, both or none.  If you wish, you can enter the  first
letter of the option you want.

If are defining a large number of  field directions, you can do this  by
giving a number <n> followed by the direction. The next <n> fields  will
then be declared to have the specified direction. For example:

    Direction of field 1 - in, out, both or none (default in) ? 5 in

will declare the next 5 fields to be input fields. If you want the  rest
of the fields to have a particular direction, you can use "*" instead of
a number e.g.:

    Direction of field 5 - in, out, both or none (default in) ? * out

will declare all remaining fields to be output fields.

Note that when multiple fields are  being defined, the default value  is
ignored. This means that if you try:

    Direction of field 5 - in, out, both or none (default out) ? *

because you want all the remaining fields to have the default value, you
will actually get an error and be asked to re-enter the value.

-- . Specifying The Field Datatype ------------------------------------

You will now be prompted  for the datatype of  each field. This will  be
checked against the known datatypes and  if what you have typed has  not
already been defined then you will be asked to re-enter it. You can  use
the same syntax used for defining multiple fields by giving a number  or
asterisk before the datatype name.

Note that if you  are using file  datatypes then all  fields have to  be
file datatypes.

-- Specifying The Data Source And Destination -------------------------

Now you have defined entered the  example format, you will be asked  how
the examples themselves are created and where the results obtained  from
the network  are  to be  sent.  Each of  these  will be  one  of:  file,
procedure, exampleset or literal. Again, you can simply enter the  first
letter of  the data  source or  destination flag.  For each  source  and
destination option, you will be prompted for appropriate values.


-- . File -------------------------------------------------------------

For both source and destination, if you have not used any file datatypes
in the example set, you will be prompted for a single file name.

If you have used file datatypes then you will be prompted for a filename
for each relevant  field. For source,  this will be  one for each  field
(since both input and  output data can  be specified). For  destination,
you will  be prompted  for a  filename for  each field  where the  field
direction is either output or both.

When you  specify a  pathname, you  can include  any special  characters
allowed by the operating system (such as "$" for specifying  environment
variables in UNIX). You  can also include  wildcards whose meaning  vary
depending on whether they  are specified in  source or destination  file
names.

For source filenames, these are simply  matched against any file in  the
specified directory  (or current  directory  if the  file name  did  not
include a directory component). This means that you can use "*" and  "?"
on  UNIX  or  "*"   and  "%"  on  VMS.   Filenames  are  matched   using
*SYS_FILE_MATCH and will be read in the order they were matched against.
This may cause confusion if you have files called:

    file1.ex, file2.ex, ..., file9.ex, file10.ex, file11.ex, ...,
    file20.ex,... etc.

since the order they will be matched in is:

    file1.ex, file10.ex, file11.ex, ..., file2.ex, file20.ex, ... etc.


For destination filenames, only "*" has a special wildcard meaning. Each
time a file is to  be written, the "*" is  replaced by the index of  the
result being written and this produces the output filename.


-- . Procedure --------------------------------------------------------

If you specified a procedure then  you should enter the procedure  name.
You may enter  a procedure name  or a  closure of a  procedure. In  both
cases, the procedure  must already  be defined.  For source  procedures,
whenever you generate  the example  set, you  will be  prompted for  any
arguments required  by the  procedure. For  destination procedures,  the
procedure should only require a single  argument (which will be the  set
of converted high-level datatypes).


-- . Example Set ------------------------------------------------------

For both source and  destination, you will be  prompted for the name  of
the example set. For source, the contents of the EG_OUT_DATA slot of the
named example set will be assigned to the EG_IN_DATA of the example  set
currently being generated.

For destination, the EG_OUT_DATA slot of the example set currently being
applied is assigned to the EG_IN_DATA slot of the named example set.

In neither case is the data structure copied so destructive modification
by one example set may affect the other.


-- . Literal ----------------------------------------------------------

If the examples  are entered  directly, then  you type  one example  per
line. If  the example  is long  then  you can  use the  backslash  ('\')
character at the end of the line  to continue the example onto the  next
line. You  should press  <RETURN>  without a  backslash  at the  end  to
signify the end of  an example. If  you make a  mistake then keep  going
with the rest of the  examples because you can  go and edit them  later.
Press <RETURN> again to show that you have finished typing in examples.

Finally, you will be asked if the examples should be generated (see  the
'Generate' section below).  If you have  made a mistake  in the  example
data then you should not generate the examples until you have  corrected
the mistake as this is likely to cause a *MISHAP.


-- 'Generate' ---------------------------------------------------------

Each example set has a slot holding a function which is used to generate
examples. The function can be used  to create new examples according  to
some pre-defined algorithm, or read data from a file or call some  other
process to  create  the  data.  Selecting  this  option  will  call  the
generator function.

If you  specified a  procedure  source, you  will  be prompted  for  any
arguments which the generator  function might need  (e.g. the number  of
examples to be  returned, filenames  etc.). Multiple  arguments must  be
separated by commas since  any arguments are collected  into a list  and
passed to  *POPVAL (which  will de-reference  any variable  names  which
means that  any arguments  which are  words or  strings must  be  quoted
appropriately  e.g.  '/usr/local/examples.dat').  If  no  arguments  are
needed, just press <RETURN>.


-- 'Display' ----------------------------------------------------------

This option allows you to  display information about an already  defined
example set. This will display the datatype and field name of each field
in the  example set  and  give any  other  information which  should  be
useful.


-- 'Edit' -------------------------------------------------------------

This option allows you  to change the values  associated with a  example
set. This  allows  you  to  edit the  generator  function,  the  example
template, the source or destination flags and the information associated
with them.

After you finished editing, you  will be asked if  you want to call  the
generator function. Note that if you have simply altered the destination
information, there is no  need to re-generate since  this will not  come
into effect until the example set is applied to a network.


-- 'Copy' -------------------------------------------------------------

Sometimes it is useful to create a copy of a example set. This is useful
for creating separate teach  and test example sets  which have the  same
input and output format and generator function but which hold  different
data. Selecting this option will prompt  you for the source example  set
and then the name of the example set copy.


-- 'Delete' -----------------------------------------------------------

This option allows you to delete example sets which you have created and
no longer need. You will be prompted  for the example set name and  then
asked to  confirm the  deletion. THIS  OPERATION CANNOT  BE UNDONE.  You
should ensure that you have already  saved any example sets you want  to
keep.


-- 'Set Current' ------------------------------------------------------

This is  defined to  be  the current  example set  and  is held  in  the
variable NN_CURRENT_EGS (used as the default value when a example set is
required). This option allows you to change the current example set.


-- 'List All' ---------------------------------------------------------

This options prints the names of all currently defined example sets.


-- 'Load' -------------------------------------------------------------

This option  allows you  to load  a example  set from  a file  on  disk.
Example set  files have  a  '.egs' suffix.  You  will prompted  for  the
directory and this will then be scanned for all files ending in  '.egs'.
The list of example sets in the current directory will be displayed. You
should then enter the names of the  example sets which you want to  load
from this list. Press <RETURN> after  each name. When you have  finished
entering names, press <RETURN> again.  The example sets will be  loaded.
Note that if you  want to load  all of the example  sets in the  current
directory, type 'all' as the first example set and then press <RETURN>.


-- 'Save' -------------------------------------------------------------

This option  allows you  to save  a example  set to  disk. You  will  be
prompted for the  directory and  then a  list of  the currently  defined
example sets will be printed. Type the name of each example set you want
saved followed by <RETURN>. Type  <RETURN> again when you have  finished
entering names. The specified example sets will be saved, one per  file.
The filename will by the  name of the example  set followed by a  '.egs'
suffix.


--- Copyright Integral Solutions Ltd. 1990. All rights reserved. ---