.ds f. vroutines.sec
.NH 1 "WRITING A VROUTINE"
.XS
\s12\*(SN  WRITING A VROUTINE\s0
.XE
.sp
.PP
The information provided in this section concerns the process of 
writing a vroutine.  This is prefaced by an outline of the steps
involved in writing a vroutine, followed by more detailed information
concerning each step in the process.  It is \fIstrongly\fP suggested that
you install any new programs in the KHOROS_CONTRIB (or \fIcontrib\fP) 
source tree.  This will allow you to easily update or install patches 
to the Khoros system as they become available.  Note that if you install 
new programs in the KHOROS_HOME (or \fIKhoros home\fP) source tree, then it will
be much more difficult to maintain the Khoros system and install patches.
New programs installed in KHOROS_CONTRIB will still be accessable
under \fBcantata\fP, from the contrib pulldown menu.
.PP
One of the first things to do when writing a new vroutine is to decide
where to put your program within the contrib source tree.  In the 
Khoros home source tree, we have grouped routines with a similar theme
into a common category.  For example, routines that have two input images
and perform an arithmetic operation on the images, are grouped into a
category called \fIarith_binary\fP.  You may want to create a category
for your own routines in contrib, or follow a grouping similar to that
in the Khoros home source tree.  More information about integrating your
program into \fBcantata\fP is provided in Section E of this chapter.
.sp
.IP 
\fB1) Creating the UIS file - \fP First, create your User Interface 
Specification (UIS) file (ie, *.pane file) which will contain the 
definitions and specifications for both the Command Line User Interface 
(CLUI) and the Graphical User Interface (GUI) of your program. 
This necessitates that all input and output parameters be defined and 
specified prior to writing of the source code.  You may do this by using 
an existing UIS file as a template, and modifying it as desired 
using \fBpreview\fP; alternatively, you may use \fBcomposer\fP to 
interactively generate your UIS file.
.sp
.IP
\fB2) Using the ghost routines - \fP The \fBghost routines\fP help to automate 
writing of the source code and ensure consistency throughout the Khoros system. 
\fBGhostwriter\fP is a code generator that generates your main driver, 
include file, library file, and man pages.  Attention must be paid to the
[-type] flag, since it indicates whether the routine links against FORTRAN
code.  Specify [-type fprog] if your routine links against FORTRAN, otherwise
use [-type prog], which is also the default.  The first time 
\fBghostwriter\fP is run, a template Program Specification (PS) file is 
created for you, which contains key fields for the documentation 
and source code.  DO NOT DELETE any of the \fItags\fP that \fBghostwriter\fP
will insert into your source code and man pages! The \fBghost routines\fP 
facilitate the writing and maintenance of new programs via this PS file, 
which, once completed, contains all of the necessary information to 
re-generate the manual pages and associated source code files at any time, 
thus making the future addition or deletion of command line arguments a 
trivial process.  
.sp
.IP 
\fB3) Writing the new program -\fP As you add your code and documentation 
to the files generated by \fBghostwriter\fP, run \fBghostreader\fP 
occasionally to update your PS file.  Documentation and source code will
be inserted into the program specification (PS) file between 
the appropriate keys.  Several important points are discussed later in this 
chapter concerning arguments, error handling, data structures, and memory 
allocation.
.sp
.IP 
\fB4) Installing the new program & integrating it into cantata-\fP 
Once the new program is completed to your satisfaction, you must read
it in as a UIS pane file and verify it, then you can install 
it in the Khoros Source Tree, and integrate it into the \fBcantata\fP
visual language. To ensure that your vroutine gets installed and added to
\fBcantata\fP correctly, the \fBkinstall\fP utility program should be used.
.LP
The following sections describe each of the above steps in greater detail.
.sp 2
.NH 2 "CREATING THE UIS FILE"
.XS
      \*(SN  CREATING THE UIS FILE 
.XE
.sp
.PP
The first step in creating a new program is to create a UIS (*.pane) file for 
the new program.  A thorough discussion of UIS files and the methods 
for creating a UIS file is provided in Chapters 2 through 4 of 
the Khoros Programmer's Manual.  The UIS file can be thought of as a
program.  That is, each line of the UIS file has a strictly 
defined syntax and meaning.  Therefore, particular attention must be paid to 
order of occurrence and syntax.  
.PP
The *.pane file for your vroutine will be used for two purposes: it will
be used as input to \fBghostwriter\fP to generate the command line user
interface for your vroutine, and it will be used to integrate your vroutine
into \fBcantata\fP.  For the purpose of using \fBghostwriter\fP, it is
important to make sure that the *.pane file provides a complete description
of all desired program arguments.  On the other hand, for the purpose of
using the *.pane file to integrate your vroutine into \fBcantata\fP, you must
make sure that the *.pane file describes a visually coherent I/0 pane that 
will fit into the appropriate subform of \fBcantata\fP, that it includes 
a Help Button, and that it has a Routine button so that the user will be 
able to access your new vroutine through \fBcantata\fP.  No extraneous UIS 
lines should appear in your *.pane file. 
.PP
There are currently 28 different types of 
UIS lines, some of which are required to appear in every UIS file.
Certain UIS lines contain information that is used by both the command-
line and graphical user interfaces, whereas others contain information that
is used only by the graphical user interface.
.PP
There are several \fBrequired lines\fP for all UIS (*.pane) files.  
The \fBrequired lines\fP include:
.sp
.in +.5i
.IP \(bu
\fBStartForm (-F) -\fP The (-F) line begins the user interface specification.  
This line contains several fields which contain information concerning the 
version number of the \fIxvforms\fP library, the geometry of the form, and 
the title of the form among others  (the -F line is required in every UIS file).
.br
.IP \(bu
\fBStartSubForm (-M) -\fP The (-M) line contains information describing the 
size, position, and title of the subform (the -M line is required in every UIS
file).
.br
.IP \(bu
\fBStartPane (-P) -\fP The (-P) line describes the graphical user interface 
pane that provides a backplane for selections and action buttons to allow 
input to the application program (the -P line is required in every UIS file).
.br
.IP \(bu
\fBHelp (-H) -\fP The (-H) line describes a specialized button on the user
interface which will bring up an on-line help file when selected. The -H line
is required to appear on all \fBcantata\fP panes;  therefore your *.pane file
should contain a -H line that references the man1 page for your vroutine, for
when it is integrated into \fBcantata\fP). Note that the -H line is ignored by
\fBghostwriter\fP.
.br
.IP \(bu
\fBEnd (-E) -\fP The (-E) line is used to end a set of definitions in a 
UIS file.  The (-E) line closes a corresponding definition line in the UIS
file.  For example, a (-F) line must have a corresponding (-E) line to complete
the form definition, a (-M) line must have a corresponding (-E) line to
complete the subform definition, and a (-P) line must have a (-E) line to
complete the pane definition.
.in -.5i
.sp 1
.PP
\fBOptional lines\fP for structuring the user interface include:
.sp
.in +.5i
.IP \(bu
\fBToggle (-T) -\fP The (-T) line defines a set of one or more \fIselection\fP
items of the same type.  The value of the toggle group will take on the default
value of the selected item (except in the case of a Logical toggle, which 
takes on the number of the selected item, where logical members of the
toggle are numbered starting at 1 with the first item).
.br
.IP \(bu
\fBMutualExclusion (-C) -\fP The (-C) line defines a mutually exclusive group
of \fIselections\fP.  Members of the mutually exclusive group may be of
the same or different types. The value of the mutually exclusive group will
take on the current value of the selected item.
.in -.5i
.PP
Other lines that may appear in the UIS pane file pertain to \fIselections\fP
and \fIactions\fP,
which are used to identify the inputs, outputs, and program arguments.
These include the following:
.sp
.in +.5i
.IP \(bu
\fBInputFile (-I) -\fP The (-I) line specifies an \fIinput file selection\fP.
.br
.IP \(bu
\fBOutputFile (-O) -\fP The (-O) line specifies an \fIoutput file selection\fP.
.br
.IP \(bu
\fBInteger (-i) -\fP The (-i) line specifies an \fIinteger selection\fP.
.br
.IP \(bu
\fBFloat (-f) -\fP The (-f) line specifies a \fIfloat selection\fP.
.br
.IP \(bu
\fBString (-s) -\fP The (-s) line specifies a \fIstring selection\fP.
.br
.IP \(bu
\fBLogical (-l) -\fP The (-l) line specifies a \fIlogical selection\fP.
.br
.IP \(bu
\fBRoutine (-R) -\fP The (-R) line describes a specialized action button
which will appear on the pane when it is integrated into
\fBcantata\fP.  When the user clicks on this button, the vroutine
will be executed (this line is ignored by \fBghostwriter\fP).
.br
.IP \(bu
\fBBlank (-b) -\fP The (-b) line is used for adding comments and extra titles
into the pane,  for extra clarity on the pane when it is integrated into
\fBcantata\fP.  Note that the -b line is ignored by \fBghostwriter\fP.
.in -.5i
.sp 1
.LP
A complete description of each of the UIS lines can be found in Chapter 2,
section B.3 of the Khoros Programmer's Manual.
.sp
.PP
An example of a UIS pane file is presented below.  This illustrates the use and
placement of the various lines in a UIS pane file. 
.sp
.DS L
.ps 9
.vs 11
\f(CW
-F 4.2 1 0 170x7+10+20 +35+1 'CANTATA Visual Programming Environment for the KHOROS System' cantata
  -M 1 0 100x40+10+20 +34+1 'Histogram' histogram
    -P 1 0 80x38+22+2 +0+0 'Enhancement Using Local Standard Deviation and Mean' venhance
      -I 1 0 0 1 0 1 50x1+2+2 +0+0 ' ' 'Input Image   ' 'input image filename' i
      -O 1 0 0 1 0 1 50x1+2+3 +0+0 ' ' 'Output Image  ' 'output image filename' o
      -i 1 0 0 1 0 50x1+2+5 +0+0 1 100 3 'Window Width ' 'window width of local area' w
      -i 1 0 0 1 0 50x1+2+6 +0+0 1 100 3 'Window Height' 'window height of local area' h
      -f 1 0 0 1 0 50x1+2+8 +0+0 0 1 0.5 'Tuning factor' 'specifies scale factor' k
      -f 1 0 0 1 0 50x1+2+9 +0+0 0 2000 1 'Min Std Dev  ' 'specifies minimum standard deviation' v
      -R 1 0 1 13x2+1+13 'Execute' 'do operation' venhance
      -H 1  13x2+39+13 'Help' 'man page for venhance' KHOROS_HOME/doc/manpages/venhance.1
    -E
  -E
-E
\fP
.DE
.ps 11
.vs 13
.sp
.PP
In this example, there are three lines for structuring the user interface.  
These include the \fBStartForm (-F)\fP line for starting a user interface 
specification, a \fBStartSubForm (-M)\fP line
beginning the definition of a subform, and a \fBStartPane (-P)\fP line 
beginning the definition of an I/O pane.  Note that each of these lines has 
a corresponding \fBEnd (-E)\fP line
to terminate the respective set of definitions.  Chapter 2 discusses other
types of UIS lines that are used to structure that graphical user interface
into multiple subforms, and multiple panes;  however, these lines are
generally not used by vroutines, and are always ignored by \fBghostwriter\fP.
This particular example has 
both an \fBInputFile (-I)\fP line and an \fBOutputFile (-O)\fP line to 
specify the input and output file selections.  
There are also lines for \fBInteger (-i)\fP and \fBFloat (-f)\fP
selections, as well as a \fBRoutine (-R)\fP action button line and a 
\fBHelp (-H)\fP line for access to the on-line man page.
.PP
Next we will provide a brief discussion of some of the more common fields
in the UIS file to get the reader started in constructing one of their own.
.PP
The \fBStartForm (-F)\fP line always has the version number as its first field. 
This provides 
a way of keeping track of outdated UIS files.  The next field in the (-F) line,
and the first field in most other lines, is the activation field.  This field 
allows various parts of the form to be disabled, thus is should always be set
to 1 (TRUE), unless that part of the form is to be deactivated.  The next field
that is found on most lines is the selected field, which is used by the 
\fIxvforms\fP library to indicate if an item has recently had its value changed
by the user.  The \fIselected\fP field should always be set to 0 (FALSE) with
a few exceptions as noted in Chapter 2. 
.PP
Lines that appear only in the pane definition contain either three or four 
additional fields prior to the geometry string field.  The \fIoptional\fP field,
which is the third field, determines whether a selection is optional. The
\fIoption selected\fP or fourth field specifies whether the default value is 
to be used, and the \fIlive\fP or fifth field specifies if the selection is to 
return immediately when the user hits <cr>.  The I/O lines contain a sixth
field called \fIfile type\fP that will be used in the future.
.PP
A geometry string appears in each line associated with a form, button or 
selection.  The geometry string, which is of the form [width x height + xoffset
+ yoffset], specifies the overall geometry of an item,
where the offsets are referenced from the upper left hand corner of the
parent widget.  The geometry string determines the size of the master form for
the StartForm (-F) line, the subform for the StartSubform (-M) line, and the
pane for the StartPane (-P) line.  Default values for the geometry string are 
produced for these lines when \fBcomposer\fP is used to design the pane file.
If the decision was made to design the pane file yourself, then it is suggested
that you use an existing UIS pane file as a template.  \fBPreview\fP can be used
to display the UIS pane and make editing changes once it has been created.
.PP
The next field specifies the offset for the \fItitle\fP.  These are generally set
to +0+0 for I/O and other selections within the pane definition.  Other fields
that are found in the pane definition lines include selections for the upper and
lower bounds of the input, the default value or file, the title, and the
description.  
.PP
This brief introduction to the common fields associated
with the lines of a pane definition is provided to familiarize the user with
a UIS pane file.  The reader is urged to consult Section B.5 of Chapter 2 for
a detailed description on the use of each field.
.PP
There are three other lines that may be used to simplify selections on UIS
panes.  These include \fILogicals\fP, \fIToggles\fP, and \fIMutual Excusions\fP.
A \fBLogical (-l)\fP line allows the user to specify a boolean value as a 
response to a question or selection.  An example of a \fIlogical\fP selection 
is provided below:
.sp
-l 1 0 1 1 0 20x1+1+5 +0+0 1 'Display Grid?' 'No' 'Yes' 'request grid display?' grid
.sp
This line illustrates the use of an optional logical selection.  This means that
the selection will appear with an optional box in front of the title.  Since the
\fIoption selected\fP field is set to TRUE,
the optional box will be initially highlighted, indicating that the
default action will be to use the value of the logical.   This value, according
to the value of the \fIdefault\fP field, will be 1 (TRUE), interpreted in this
case as a response of "Yes" to the question, "Display Grid?" 
.PP
A \fBToggle (-T)\fP line allows the user to specify one of a predefined number of 
choices.  The choices may be of any type of argument, as long as they are all
of the same type.  For example, it is possible to define a toggle of integers,
a toggle of floats, or a toggle of strings.  The (-T) line begins the definition
of a set of toggles.  The following example illustrates the use of a \fItoggle of
logicals\fP:
.sp
.ps 10
.nf
-T  1  0  0  1  0  20x1+1+5  +0+0   4  'Plot Type'  'type of plot'  plot_type
     -l  1  0  1  0  0  10x1+0+1  +3+0  0  '2D'  '2D plot'  dummy
     -l  1  0  1  0  0  10x1+14+1 +3+0  0  'Discrete'  'discrete plot'  dummy
     -l  1  0  1  0  0  10x1+28+1 +3+0  0  'Histogram'  'histogram plot'  dummy
     -l  1  0  1  1  0  10x1+7+2  +3+0  0  'Polymarker'  'polymarker'  dummy
     -l  1  0  1  0  0  10x1+21+2 +3+0  0  'Linemarker'  'linemarker'  dummy
-E
.fi
.R
.LP
This example illustrates one way in which the (-T) line might be used to create
a toggle which yields a value for the plot_type variable.  This example
demonstrates the use of a required logical toggle.  The toggle (ie. the integer
variable "plot_type") will take on values of 1, 2, 3, 4, or 5, depending on
which one of the logicals is selected.
.PP
In contrast to integer toggles and string toggles, the \fIdefaults\fP 
of the logicals in a toggle do not matter - they are all set to 0.  
In all UIS lines that
are members of a toggle, the \fIvariable\fP fields on the logicals will not 
be used - we put in "dummy" to remind us of this fact.  Check to make sure 
that the default
of the toggle is set correctly - the \fIdefault\fP field on the (-T) line is
set to 4, and the fourth logical is the only one to have its \fIoption
selected\fP field set to 1.  Thus the default of the toggle will be the value 
4, corresponding to the
selection 'Polymarker'.  Finally, check the geometry, to make sure that you have
specified the \fIy\fP field relative to the (-T) line;  the geometry of the 
logicals will specify 2 rows of toggle items, the top row with three selections,
and the bottom row with two selections.
.PP
A \fBMutExcl (-C)\fP line defines a group of two or more arguments that need 
not have predefined values and may be of different types.  
The only field on the (-C) line
specifies whether a selection is required or is optional (ie. a value of 0 
indicates that the selection is optional).  If the selection is required (ie. a
value other than 0 is provided), then the user will be able to
provide and use a value for one and only one of the selections in the group.
Unlike the toggle (-T) group, which is limited to a single type of selection, 
the mutually exclusive group may contain a mixed group of Integer, Float, 
String, Logical, InputFile, or OutputFile selections.  All selections in a 
mutually exclusive group MUST be specified as optional.  The user will only 
be able to "turn on" one of the mutually exclusive selections 
(by highlighting the optional box) at any one time; this is the only one 
of the selections' values that is guaranteed to be valid at any one time.
.PP
The following example illustrates the use of a \fImutually exclusive\fP group:
.sp
.ps 10
.nf
-C  1
     -I  1  0  1  1  0  1  45x1+1+13 +0+0  './'  'Input Path'  'input path selection'  input_path
     -O  1  0  1  0  0  1  45x1+1+14 +0+0  './'  'Output Path'  'output path selection'  output_path
     -s  1  0  1  0  0   45x1+1+15 +0+0  ' '  'String Sel'  'string selection'  string1
-E
.fi
.R
.LP
This example demonstrates the use of a required argument for a mutually exclusive
group.  The only field on the (-C) line requires a value specifying one and only 
one of the items within the mutually exclusive group.  In this example, the first
item is selected as the default.  Note that the \fIoption selected\fP field 
(fourth field) is selected with a 1 in this location.
.PP
The operation of a mutually exclusive
group in the command line user interface is slightly different from the
operation of a mutually exclusive group in the graphical user interface. Note
that the default values for the input_path and output_path parameters are both
set to "./".  When using this mutually exclusive group on the command line,
these defaults are unused -- the user will be forced to specify a value
for one of the selections, and if they choose the input_path or output_path
parameters, will still have to explicitly enter a value, even if they want the
"./" directory specified.  However, for the graphical user interface, it
is good to specify these defaults - the selections will come up in the order
listed, and the input_path and output_path selections' parameter boxes will
have "./" appearing inside them.  The optional box in front of the input_path
selection will be highlighted -- if the user wishes to specify the input_path
selection as their choice from the group (the default of the group) and they
also wish to have "./" as the value of the input_path selection (the default
of the input_path selection), they need not do anything.
.PP
The reader is once again urged to consult the detailed discussions provided in 
in Chapter 2 of the Khoros Programmer's Manual for a complete description 
of the proper syntax and use of each line in a UIS pane file.
.PP
Once the UIS pane file has been created, the next step is to create a driver
program for the routine, using all of the arguments specified in the UIS
pane file.  This is easily accomplished using the \fBghost routines\fP provided
for this purpose.  The next section describes how to use the \fBghost
routines\fP to create a driver program and generate the framework for the
library routine.
.sp 2
.NH 2 "USING THE GHOST ROUTINES"
.XS
      \*(SN  USING THE GHOST ROUTINES
.XE
.sp
.PP
To help speed up the process of writing a program and to ensure
consistency in the code, Khoros contains code generators 
that help to automate part of the procedure of programming.
The code generators belong to the \fBghost routines\fP, which includes
\fBghostwriter\fP and \fBghostreader\fP.
.PP
To get started, create a new directory that can be used as the
development directory for the new routine.  Create a UIS (*.pane) file
using either \fBcomposer\fP or a modification of an existing UIS (*.pane)
file, as detailed in Chapters 2-4.  
.PP
The first tool you will use is \fBghostwriter\fP.  However,
keep in mind that \fBghostwriter\fP requires a UIS file as input
(discussed in the previous sections).  \fBGhostwriter\fP can be run with 
the UIS file to create a template for the PS file, the include file, 
the source code files for the main driver, the library file,
and the manual pages for the program.
Alternatively, you can begin with an empty template PS 
file, fill in the appropriate fields, and run \fBghostwriter\fP to
generate the source code and manual page files.  We have found that a hybrid
method is most popular with the Khoros group;  however, after writing one or 
more programs under the Khoros system, you will find your own preference.
.LP
The following example demonstrates the use of \fBghostwriter\fP to generate 
a vroutine:
.PP
\f(CW
% ghostwriter -name vroutine
\fP
.sp
.LP
This will generate the files "vroutine.c", "lvroutine.c", "vroutine.1",
"lvroutine.3", "vroutine.h"\fP.  Note that in order to use \fBghostwriter\fP,
a valid UIS file (in this case, "vroutine.pane") must exist 
in the current working directory.  
\fBGhostwriter\fP will look for a valid PS file in the current working
directory; if one does not exist, a template PS file ("vroutine.prog") 
will be created.  In addition, \fBghostwriter\fP will also look for a 
configuration file in the current working directory;  if one does not exist, a 
template configuration file ("vroutine.conf") will be created as well. 
The configuration file simply specifies the paths to each of the files
associated with the new routine.  
An example of a template configuration file is located in 
KHOROS_HOME/repos/config/src_conf and is called "TEMPLATE.conf".
The use of the configuration file is explained later in this chapter.  For more 
detailed information about the configuration file, see Chapter 5 of the Khoros
Programmer's Manual.
.PP
There are several options with \fBghostwriter\fP which allow use of a
configuration file, formatting, debug statements, and generation of
certain files.  The various options may be listed using the [-U 1] option; or,
you may wish to run the program with prompts for each command line
option using the [-P 1] option.  
An answer file, which specifies the desired arguments to \fBghostwriter\fP,
may be created by using the [-A ghost.ans] and [-P 1] options together, making 
it easier to perform successive runs of \fBghostwriter\fP (a certainty!).
.PP
In this example, if we had used the [-A ghost.ans] option to \fBghostwriter\fP, 
for the vroutine, its answer file, "ghost.ans", for future executions 
of \fBghostwriter\fP would look like:
.in +.5i 
.sp
-name vroutine
.br
-config f
.br
-lib t
.br
-man3 t
.br
-install f
.br
-format 1
.br
-debug f
.br
-tag t
.br
-force f
.br
-prog t
.br
-type prog
.sp
.in -.5i
.LP
Now, for successive runs of \fBghostwriter\fP, we need not provide arguments
on the command line, or interactively with the [-P 1] option.  To execute
\fBghostwriter\fP with the exact same arguments as before, all that is 
necessary is to run:
.sp
\f(CW
% ghostwriter -a ghost.ans
\fP
.sp 2
.LP
If your code links against FORTRAN (note that the
\fIlinpack\fP and \fIeispack\fP libraries are in FORTRAN), you must provide
the [-type fprog] flag, or your code will not compile.
Notice that executing \fBghostwriter -name vroutine\fP generated the files: 
"vroutine.c", "vroutine.1", "vroutine.h", "lvroutine.c", and "lvroutine.3".  
\fBGhostwriter\fP will also make calls to \fBimkmf\fP and \fBmakemake\fP 
for you, thus generating (respectively) the appropriate "Imakefile" and 
"Makefile" files for this program.  The vroutine is now ready to be compiled; 
of course, lvroutine() will simply return to the main program (initially,
it is generated with only a \fIreturn(TRUE)\fP statement).  You may wish 
to compile at this point, checking for any errors in the driver 
and include files.  To compile, simply type:
.sp
\f(CW
% make
\fP
.sp
.LP
No errors should occur, unless you modify these files in some way.  
However, if compile errors do occur 
in any of the source files, you can fix the problems in the source 
files, but remember to follow any modifications with a call to 
\fBghostreader\fP.  Note that \fBghostreader\fP has a subset of the complete
set of \fBghostwriter\fP arguments - those arguments that are identical for
the two programs have the same meaning,  and neither program checks for
invalid arguments, so that you may provide the same answer file, "ghost.ans"
for both programs.  To execute \fBghostreader\fP, then:
.in +.5i
.sp
\f(CW
% ghostreader -name vroutine
\fP
.sp
or
.sp
\f(CW
% ghostreader -a ghost.ans
\fP
.sp
.in -.5i
.PP
The Program Specification (PS) file contains key fields for the insertion
of Khoros system documentation, man page documentation, and source code.
A template "vroutine.prog" file is created when \fBghostwriter\fP 
is run for the first time, containing all of the key fields for 
constructing a complete PS file.  Each key field in the "vroutine.prog" file
is delineated by 
\fIbegin\fP and \fIend keys\fP.  All comments, code, and documentation is 
placed between the appropriate \fIbegin\fP and \fIend tags\fP for a 
particular field.  An example of a template PS file is presented in 
Chapter 5. Chapter 5 should be consulted for specific descriptions 
and guidelines concerning the information to be included in each of 
the key fields of the PS file.  An example illustrating the use and format 
of each key field of a *.prog file is included in Chapter 5.  This format 
should be adhered to when creating a PS file to ensure maintainability of 
the Khoros System.
.PP
\fBGhostwriter\fP creates the source code, include files, and man pages 
with pre-defined \fPtags\fP, that are recognized by \fBghostreader\fP.
Thus, segments of code and/or documentation between these tags 
may be modified by the programmer and then reinserted into the 
PS file by running \fBghostreader\fP.  \fBGhostreader\fP takes as 
input the 5 files: "vroutine.c","vroutine.h", "vroutine.1", and "lvroutine.3",
as well as the old PS file "vroutine.prog".  It looks for the tags, and pulls
any text between a pair of begin and end tags into the corresponding place in
the PS file.  In this way, a new PS file may be generated containing the 
new information.
.PP
Running \fBghostreader\fP insures that all modifications are correctly 
updated in the "vroutine.prog" PS file; thus, when \fBghostwriter\fP is 
run again (perhaps with the [-A 1] flag), the updates will be written to 
the appropriate files.  BE WARNED that if you modify the source or man page
files, and forget to run \fBghostreader\fP 
before running \fBghostwriter\fP again, \fIall your changes to source code
and man pages will disappear!\fP
.PP
.sp 2
.NH 2 "WRITING THE NEW PROGRAM"
.XS
      \*(SN  WRITING THE NEW PROGRAM
.XE
.sp
.PP
All functionality for your program should go into the "lvroutine.c" file,
often referred to here as the library routine.  The "vroutine.c" is 
referred to as the driver program, which calls the "lvroutine.c" file.  
Note that it is possible to write a driver that simply makes calls to 
other library routines, in which
case there would not be an "lvroutine.c" file for this particular routine.
The driver is generated by
\fBghostwriter\fP from the information contained in the UIS (vroutine.pane)
file.  
.PP
It is STRONGLY recommended that you read the man pages on the \fIverror, 
vgparm, vmath, vrast,\fP and \fIvutils\fP libraries.  These are public Khoros
libraries, and contain many useful routines for I/O, math, and 
reading/writing/checking of images that help the programmer avoid
"re-inventing the wheel".  
.PP
When the source code for the library routine is completed, you are reminded 
(again!) to use \fBghostreader\fP to update your PS file in preparation for
any future runs of \fBghostwriter\fP.  The program should then be 
carefully tested for proper operation, using all possible options both
separately and in different combinations.
.PP
If your routine does not have a library file (lvroutine.c), then there
is no need to complete a man3 page for your routine.  If your routine
has a library file, then you will need to complete the man3 page information 
for your new library routine.  The purpose of the man3 page is to provide a 
detailed description of the library routine.  This should include a discussion 
of the algorithm used and any parameters that are passed to or from the 
routine.  If the algorithm was taken from another source, be sure to 
provide references to the source.  No examples of the library call are 
necessary unless they clarify the call to the library routine.  
.PP
Recall that \fBghostwriter\fP created a skeleton 
"lvroutine.3" file for your program. If you are writing a vroutine, you
should update this file with careful documentation of your library routine,
following modifications with calls to \fBghostreader\fP.
.PP
The "lvroutine.3" file may be edited directly.  Modifications
should be followed by a call to \fBghostreader\fP;  however, when updating
man pages the programmer often prefers to edit the PS file.  If you
like, you may edit the PS file ("lvroutine.prog"), looking for keys that mark
the man3 information. WARNING: you should run \fBghostreader\fP immediately 
before editing the "lvroutine.3" file, and run \fBghostwriter\fP immediately 
afterwards.  It is best to look at some of the man3 files for 
other library routines to get the feel of how to write one.  Man3 
files can be found in \f(CWKHOROS_HOME/man/man3\fP.  
The man3 file should include
usage information about all of the parameters passed into the library 
routine including any restrictions.  
.PP
Finally, you will be required to complete the man1 page information for your
new program.  The purpose of the man1 page is to provide a detailed 
description of the function of your new program.  This should include 
descriptions of the input files, output files, and arguments to the program.  
Try to be as complete as possible in your descriptions of the inputs, 
outputs, and arguments to the program.  This information will be of 
valuable assistance to anyone using your program.  Man1 pages are very 
similar to man3 pages, except that they discuss the program in general. 
The procedure for modification of man1 pages is identical 
to that for modification of man3 pages. You may want to 
look at some of the man1 files for other Khoros programs to get the feel 
of how to write one.  Man1 files can be found in \f(CWKHOROS_HOME/man/man1\fP.
.PP
Formatting for both types of man pages should be done in \fInroff\fP 
format.  This is to ensure that the on-line manual pages are generated
correctly and to maintain consistent formatting throughout the documentation.
Certain fields found in the PS file need no formatting since they must consist 
of only a one line description (notes on the PS file will follow later).  
A few of the more common \fInroff\fP formatting commands that you may
find useful include:
.sp
.DS
	.IP/.LP - for new block paragraphs
	.RS/.RE - for indenting
	.DS/.DE - for non-formatted sections
	.SH    - for section headers
	.sp #  - for adding # blank lines
.DE
.sp 2
.NH 3 "Conventions used for Image Processing Algorithms"
.XS
              \*(SN  Conventions used for Image Processing Algorithms
.XE
.sp
.PP
It is common to have multiband images in an image processing system,
and Khoros has provisions for handling multiband images.  The convention
for addressing multiband images within Khoros is to refer to the first
band as band number 0, and the second band as band number 1, etc.  Therefore
when writing a new routine that works with multiband images, you should
follow this convention.  (For details on VIFF see section H of this chapter.)
.PP
Classification routines often deal with multiband images, as they
frequently work with multiband cluster and class images.
The cluster number and class images should output as data storage type 
\fIinteger\fP.  This is to ensure that there are plenty of available 
numbers for clusters.  The numbering convention should start with 0 and
increase.  Cluster number 0 should correspond with cluster center 0, etc.
In most cases the numbering scheme will be from 0 to N-1, where N is the
number of cluster centers.
The convention is to make cluster center vectors of data type float.
Also, variances of the centers should be of type float.
.PP
During the course of processing an image for classification, a border
is often created around the image due to windowing algorithms.
Therefore, all clustering/classification and labeling/shape algorithms should
have the provision of ignoring image borders.  The default output pixel 
value for borders should be 0, but this should not matter if it is ignored.
.PP
Classification routines should not assign NULL to any cluster center.
There may be cases when a cluster number does not have a corresponding 
center, and in cases like this the cluster number should be 0, and the 
corresponding center vector will be 0's.  The program \fIviso2\fP can
produce a situation like this, and in this case there will be N+1 centers
(0 ... N).  This will still actually provide valid input to other 
algorithms, but will produce strange results.  Therefore the programmer
must be aware of cases such as this, and thoroughly document it in 
the manual page for the routine.
.sp 2
.NH 3 "Conventions used for Digital Signal Processing Algorithms"
.XS
              \*(SN  Conventions used for Digital Signal Processing Algorithms
.XE
.sp
.PP
There are two representations of signals recognized in the DSPL library.  
The first is vector signals, which will be called \fIvector oriented\fP.  
In this data representation, adjacent elements of a signal can be found in 
the same location in the previous or next data band.  In this way, data is 
processed \fIthrough\fP the bands.  The second representation of signals is 
what is referred to as \fIband oriented\fP.  That is, each band contains a 
single, complete signal that is arbitrarily related, or not related at all, 
to signals occurring on other bands.  In this way, data is processed 
\fIon\fP the bands.
.PP
Two constants are defined for use by dspl routines: DSP_BAND and DSP_VECTOR. 
These are used when referring to these data types in a program.  These 
representations allow much flexibility because the band orientation is 
more common, while the vector representation allows the band row-column 
dimensions to encode spatial, time, frequency gradient or other information.  
Signals that are organized on a band should generally be 1 column by n rows, 
where n is the length of the data sequence.  
This follows established conventions and simplifies numerical
analysis when implementing linear equations.  
.PP
Two programs have been 
written to simplify the use of these two formats. They
are \fIdload_vector()\fP and \fIdunload_vector()\fP.  \fIDload_vector()\fP 
is used to reorganize the data into an array of pointers to data vectors, 
(i.e, float **).  This allows a simple for loop to be used to process all 
data sets in a VIFF file.  \fIdunload_vector()\fP returns the data to its 
original organization.  The UIS file should have an entry using a 
logical variable named 'd' to select which organization the data is assumed 
to be organized in.  There is no information on data organization inside the 
VIFF header structure.  For more information on these routines, please refer 
to the section on the vutils library in Chapter 8 in the Khoros Programmer's
Manual.
.PP
Occasionally there are times when it is desirable to handle the real and
imaginary components of a complex data set separately.  In this case, they
are treated as independent, real vectors of data.  Where appropriate, dspl
programs written for Khoros will have a processing option referred to in the
pane file as 'j'.  All programs written for the Khoros dspl library will
handle real and complex data.  
.sp 2
.NH 2 "INSTALLATION OF NEW PROGRAM"
.XS
      \*(SN  INSTALLATION OF NEW PROGRAM 
.XE
.sp 2
.PP
The installation process of a new routine consists of moving all the associated
files of a new program into their proper places in the Khoros contrib source 
tree, and compiling the program.  As explained previously, you are not
prevented from installing a new routine into the Khoros home source tree;
however, it will be much easier to maintain Khoros and install patches 
if new user routines are installed in the Khoros contrib source tree.  
The Khoros contrib
directory structure mimics that of Khoros home.  A source tree is provided
in Khoros contrib for the purpose of installing new user routines.  You might
want to examine the structure of the Khoros home source tree to get a feel
for the organization of the Khoros system.  The layout of the Khoros home 
source tree and contrib is provided in Chapter 9 of the Khoros Programmer's Manual.
.PP
The following sections give detailed explanations on the use of Khoros 
configuration files, and the step-by-step process for installing your vroutine.
.sp 2
.NH 3 "Configuration Files"
.XS
              \*(SN  Configuration Files
.XE
.sp 
.PP
Before installing a program, you must ensure that a correct configuration 
file exists for your program.  The configuration file is simply an ascii 
file that specifies 
the location within the Khoros source tree for all of the source code files, 
document files, UIS files and PS files associated with your program.  
Once your program is installed, the configuration file is used by 
by \fBkinstall\fP to find the appropriate locations for installing files.
Later, \fBghostreader\fP will use the configuration file to locate the 
appropriate files for input before creating a new PS file, and by 
\fBghostwriter\fP to specify the appropriate directory paths for writing 
the new files. 
.PP
A template configuration file is created automatically for 
you the first time that \fBghostwriter\fP is run; the default locations 
for files in the template file is the local "." directory.  As long as you
have your program in your working directory, this is sufficient;  however,
once you are to install your routine, this configuration file must be manually
updated to specify the pertinent locations of the files associated with
your program.  There are ten \fIfile keys\fP in the configuration file that 
identify a particular file associated with your program;  each file key is 
followed by the path that specifies the directory in the Khoros source tree
where that file is to be located.  An example configuration file is presented 
below for the vroutine, "vadd".  It has each of the 10 file keys filled out 
with the appropriate path information.
\f(CW
     cfile: vipl/arith_binary/vadd
.br
     hfile: vipl/arith_binary/vadd
.br
     lfile: vipl/Lib
.br
     progfile: vipl/arith_binary/vadd
.br
     man1file: $KHOROS_HOME/man/man1
.br
     man3file: $KHOROS_HOME/man/man3
.br
     panefile: $KHOROS_HOME/repos/cantata/subforms/arith_binary
.br
     helpfile: $KHOROS_HOME/doc/manpages
.br
     subhelpfile: $KHOROS_HOME/doc/cantata/subforms/arith_binary
.br
     topsrc: $KHOROS_HOME/src
\fP
.PP
Each file key specifies the path where a specific file will be 
installed.  All of the keys except "helpfile", "subhelpfile", and "topsrc"
are also used by the \fBghost\fP routines, and are explained in Chapter 5
of the Khoros Programmer's Manual.  The \fBkinstall\fP program uses all of 
the keys, the remainder of which are used as follows: 
.IP helpfile - 
All man1 (*.1) pages are formatted slightly differently for use in the 
\fBcantata\fP online help pages.  Online help pages for \fBcantata\fP are 
always located either in \f(CW$KHOROS_HOME/doc/manpages\fP or
\f(CW$KHOROS_CONTRIB/doc/manpages\fP.  The \fBkinstall\fP program will
format your man1 file for \fBcantata\fP's online help, and install a copy
of it here.
.IP subhelpfile - 
This is the path to the \f(CWOverview.doc\fP file that provides the online help
for the subform of \fBcantata\fP to which the pane associated with your 
program will be added.  You will edit this file and add a short description 
of your new program to the short descriptions of other programs that already 
exist on the subform in question.
.IP topsrc - 
The "cfile", "hfile", "lfile", and "progfile", will be called the \fIsource\fP 
file keys, and can be specified using either full paths
(ie. cfile: \f(CW$KHOROS_HOME/src/vipl/arith_binary/vadd\fP) or relative paths
(ie. cfile: \f(CWvipl/arith_binary/vadd\fP).  If you decide to use relative 
paths, then you MUST have the "topsrc" file key filled in with the path to the
\fItop level\fP of the source tree;  that is, either \f(CW$KHOROS_HOME/src\fP
or \f(CW$KHOROS_CONTRIB/src\fP.  Of course, you may choose not to
bother with the "topsrc" key, and simply provide the full path in the
source keys.  In this case, you may delete the "topsrc" line from the 
configuration file.
.PP
Further information on the configuration file can be found in Chapter 5 of the
Khoros Programmer's Manual.
.sp 2
.PP
.PP
.NH 3 "Installing Your Vroutine"
.XS
              \*(SN  Installing Your Vroutine
.XE
.sp 
.PP
There are several tools available to aid the programmer in maintaining
and installing new programs in the Khoros system.  In addition, the tools 
also include several "low-level" programs that manage the Khoros source tree 
configuration, which are designed to be used by managers of the Khoros system.
From the programmer's perspective, the only tool that is required for
installing a new vroutine is \fBkinstall\fP.  To use \fBkinstall\fP,
you must be familiar with the configuration file and the
\fBghostwriter\fP and \fBghostreader\fP programs.  The configuration file
was discussed previously in this document, as well as in Chapter 5 of the Khoros
Programmer's Manual. Chapter 5 also describes the \fBghostwriter\fP and 
\fBghostreader\fP programs.  
.PP
One other file that is used by the \fBkinstall\fP program is
a \fImach\fP file.  The mach file specifies the paths to the source directories
of your program and to the corresponding \fIsrcmach directories\fP within the
\fIsrcmach tree\fP. A srcmach tree is established if a particular site is 
supporting different machine architectures.  For example, if your site is 
supporting both Decmips and SUN4 architectures, the Khoros system for your
site would include a srcmach tree whose layout and contents mimic the 
"real" Khoros source tree.  The srcmach tree consists of symbolic
links to files in the original source tree, along with object files 
compiled for that particular architecture.  The mach file specifies
the machine names for a site, as well as the path for the srcmach directories.
Normally the mach files for a particular site would be configured by
the manager of the Khoros system; however, to completely understand the 
installation process, it helps to understand how the mach file ties in with 
the installation process.
.PP
The "low-level" tools are called by the installation program which takes
care of creating the Makefiles and establishing any symbolic links to
other \fIsrcmach\fP directories if they exist.  
.PP
The syntax for the \fBkinstall\fP program is as follows:
.sp
\f(CW
% kinstall -name xxxx -conf xxxx.conf [-mach yyyy] [-force z] [type wwww]\fP
.sp
where,
.IP xxxx
is the name of the vroutine that is being installed.
.br
.IP yyyy
is the path and filename of the mach file that is being used for the 
current install.
.br
.IP z
is a boolean that specifies whether to use the force option which bypasses 
the overwrite prompts and edit sessions.  The default is FALSE, which does 
not bypass the overwrite prompts and edit sessions.  Note that the force 
option of TRUE is not allowed if the vroutine has never been installed, or 
has been removed from the system.
.br
.IP wwww
is the type of program to be installed.  If you have a vroutine, use "prog".  
If you have a vroutine that links against FORTRAN, use "fprog".  
.br
.sp
.PP
The following scenario is provided to illustrate the installation of a routine 
into the Khoros system using the \fBkinstall\fP program.  It is
assumed that you are installing a vroutine from a directory in
your work area, and that all the necessary files for the 
routine are present in the work directory.  The necessary files include:
a *.pane file, *.prog file, *.c file, *.h file, *.1 file, and a *.conf 
file.  Optional files include: l*.c file, l*.h file, and a *.3 file.
The optional files would be necessary if a vroutine includes library
source files.  It is further assumed that the programmer has run
\fBghostwriter\fP to generate the necessary files from the *.pane and
*.prog file.  The step-by-step procedure for installing the program 
"vroutine" in the Khoros contrib source tree appears below.
.IP 1) 
From your work directory, initiate the \fBkinstall\fP program as follows:
.sp
\f(CW
% kinstall -name vroutine -conf vroutine.conf -mach contrib_mach
\fP
.sp
.PP
Note that the optional argument [-mach] is not used in this
example.  This assumes that the manager of the Khoros system has configured 
the mach files for your site.  Information on mach files is found in 
Chapter 9 of Volume II, on Configuration Management.
The [-force] argument would not be allowed 
if the vroutine you are installing is a new routine.
.IP 2) 
The \fBkinstall\fP program will prompt you for a destination
path to an additional library include file.  This is only necessary if
your program requires additional defines and/or includes, as in the
case for many of the file format vroutines.  If no path is required, simply
respond with "n" to the prompt.
.IP 3) 
The \fBkinstall\fP program will check to make sure that the supplied
paths are correct (ie. that they exist, and have the correct permissions).
\fBKinstall\fP will also provide you with some information about
the mach file that is being used and will indicate which program is about
to be installed.  The paths for the library and driver source will also
be provided and \fBkinstall\fP will prompt you to continue with the 
install.  Answer "y" to continue with the installation, or "n" to abort
the installation.  If you continue with the installation, \fBkinstall\fP
will create a lock file in the Khoros home directory which will prevent
other programmers from installing vroutines simultaneously.  If someone
else is installing a vroutine, a message will be displayed indicating
that another user is installing a vroutine, and to try again in a few
minutes.
.IP 4) 
Once the installation has begun, you will be provided
with some information along the way to indicate what file is being
installed and the location where it will be installed.  Do not be 
concerned if the information scrolls off the screen, since all of the
information will be mailed to you indicating the status of
the installation.  Basically, \fBkinstall\fP copies the files associated
with your particular routine to the destinations indicated in the configuration
file.  Symbolic links are created in srcmach directories if your site
supports multiple machine architectures.  Imakefile & Makefiles are created 
and updated in each associated directory, and the source files are compiled
for each architecture.
.IP 5) 
The \fBkinstall\fP program will put you into a session with the editor
so that the new vroutine can be added to the appropriate \fBcantata\fP UIS file.
This file is located in the directory specified by the "panefile" entry 
in the configuration file.  In the same directory will be another file with 
the extension ".sub".  This UIS file contains the specification for the subform 
within \fBcantata\fP to which you will be adding the pane that defines the GUI 
for your program.  Programs with a common theme are grouped together in one 
subdirectory and are accessed under the same menu selection within cantata.
This step is explained in greater detail in the section labeled, 
"INTEGRATING THE NEW PROGRAM INTO CANTATA".
.IP 6) 
The \fBkinstall\fP program will again put the programmer into an
editor so that the \fBcantata\fP help file can be updated with a short 
description of the new vroutine.
.IP 7) 
The \fBkinstall\fP program will then update the Makefiles
and compiling the program for each machine architecture.  Finally,
\fBkinstall\fP will remove the lock file, so that another vroutine 
may be installed.  The last thing you must do is to read
the mail that \fBkinstall\fP sent to you regarding the status of the
installation.  The number of mail messages sent to you will
depend on the number of machines for your particular site, and whether
library source files were installed in addition to the driver program.
.IP 8)
Now, test your program to make sure that all is well.  Don't forget to first
execute:
.br
\f(CW
% rehash
\fP
Since you are installing your program for the first time, forgetting to run
\fIrehash\fP will result in the operating system error, "Command not found".
Extensive testing is usually not necessary on installation, as you should 
have already completed the testing and debugging process in your work area,
before installation.  However, \fInever\fP neglect to do at least cursory
testing on your installed program!  Sometimes a compile looks successful,
but in fact is corrupted due to system problems or corrupted library files.
When this is the case, the result is usually an immediate segmentation 
violation and/or core dump. If this happens, repeat step (7).
.sp 2
