.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.  
.PP
If your intention is to create a set of programs that extend the
Khoros system, then you will eventually have to learn about toolboxes.
You should not modify any of the source code in the Khoros source
tree if you want to maintain or update it with patches supplied by
the Khoros group.  You can completely create a simple new vroutine 
without knowledge of toolboxes.
.PP
When you are ready to install a vroutine, and an appropriate toolbox does 
not exist, you must create one.  For example,
if you are writing a group of routines to do medical imaging, you might create
a "medical" toolbox; all programs written to address medical imaging
problems would then be added to the "medical" toolbox.  For complete
instructions on creating and using a toolbox, please see Section I. 
.PP
After you read through this section, it is appropriate to go to
Chapter 4 and experiment with \fBcomposer\fP.
.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 install 
it in the appropriate toolbox, 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.  In addition, 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 many 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. A help button
is required to appear on all \fBcantata\fP panes;  therefore your *.pane file
should contain a -H line that references the version of the man1 page for your 
vroutine that is formatted for online help.  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 must 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 it 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 you decide to design the *.pane file yourself, then it is suggested
that you use an existing *.pane file as a template.  \fBPreview\fP can be used
to display the GUI described by the *.pane file and make modifications 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 call it "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 the mutually exclusive group
is required or is optional (ie. a value of 0 
indicates that the group is optional).  If the selection is required (ie. a
value other than 0 is provided), then the user will be required to select
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.  
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 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 -toolbox {toolbox name}
\fP
.LP
If you have not set up a toolbox yet, you may execute the command:
.PP
\f(CW % ghostwriter -name vroutine \fP
.LP
Note that if you later decide to
create a toolbox for your program, you will need
to delete the Imakefile and Makefile for your program and run \fBghostwriter\fP
with the toolbox flag.
.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.  In general, the configuration file is ignored while
writing the new program;  it is not used until the program is to be installed
in the appropriate toolbox.
.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
.br
-toolbox {toolbox name}
.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:
.br
\f(CW
% ghostwriter -a ghost.ans
\fP
.br
.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:
.br
\f(CW
% make
\fP
.br
.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
.br
\f(CW
% ghostreader -name vroutine
\fP
.br
or
.br
\f(CW
% ghostreader -a ghost.ans
\fP
.br
.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 are 
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, \fIall your changes to source code
and man pages will disappear the next time you run\fP \fBghostwriter\fP!
.PP
.sp 2
.NH 2 "WRITING THE NEW PROGRAM"
.XS
      \*(SN  WRITING THE NEW PROGRAM
.XE
.sp
.PP
\fBThe main driver -\fP The main() generated in "vroutine.c" is often
referred to as the main driver program. It calls the library routine
in the "lvroutine.c" file.  Usually, not much coding is done in the
main driver, although command line arguments are often checked for 
accuracy, and input filenames are read in before the associated structures
are passed to the library routine.  Note that it is possible to write a 
driver that simply makes calls to existing library routines, in which
case there would not be a library routine for this particular program; in this
case, run \fBghostwriter\fP and \fBghostreader\fP with the options [-lib 0]
and [-man3 0].
.PP
\fBThe include file -\fP Here is where you declare any #defines, C macros,
global variables, and other include items for your new program.  Be sure that
all added declarations appear between the appropriate pairs of ghostwriting 
keys, so that they are not erased when \fBghostwriter\fP is re-run.  For
example, if you add #include references to any other *.h files, these should
appear between the \fI/*-include_includes */\fP and 
\fI/*-include_includes_end */\fP keys, so that they are preserved.
.PP
\fBThe library routine -\fP In general, all functionality for your program 
goes into the library routine generated in the "lvroutine.c" file.
Be sure that you do not add code outside the \fIlibrary_code\fP and 
\fIlibrary_code_end\fP tags generated by \fBghostwriter\fP.
All library routines \fImust\fP return an integer status flag to the calling
program - 1 (TRUE) on success, or 0 (FALSE) on failure.  A library routine
may \fINEVER\fP call exit()!  When opening a file, you should \fIalways\fP
call the \fIvfullpath()\fP routine to expand the file string, except when
the filename is to be passed to \fIreadimage()\fP or \fIwriteimage(), which 
will call \fIvfullpath()\fP for you.  If you allocate memory in your 
library routine, it is your responsibility to free that memory before 
exiting the library routine.  A library program should not have any
side effects.
.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
\fBThe man3 page -\fP If your routine has a library file, then you will need 
to complete the man3 page information for your new library routine.  This
man3 page is contained in the "lvroutine.3" file.  When the man3 page is
installed in \f(CW{toolbox name}/man/man3\fP, it will be available for perusal 
via \fBvman\fP by other Khoros users that have access to that toolbox.
The purpose of the man3 page is to provide a detailed description of 
the library routine to other programmers who may find your new routine useful.  
It should include a discussion of the algorithm used and a complete description
of all parameters that are passed to or from the routine.  If the algorithm 
was taken from another source, be sure to provide acknowledgment of that 
source.  If there are restrictions or limitations to the library routine,
document them here. It is best to look at existing 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.  
.PP
The "lvroutine.3" file may be edited directly.  Modifications
should be followed by a call to \fBghostreader\fP.  However, when updating
man pages, many people prefer to edit the PS file.  If you like, you may 
edit the PS file ("lvroutine.prog"), looking for keys that mark
the man3 information, and insert appropriate information there. Remember to
include \fInroff\fP formatting commands when necessary. WARNING: you should 
run \fBghostreader\fP immediately before editing the "lvroutine.3" file, and 
run \fBghostwriter\fP immediately afterwards.  
.PP
\fBThe man1 page -\fP Finally, you will be required to complete the man1 
page information for your new program.  The man1 page is contained in the
"vroutine.1" file.   When the man1 page is installed in 
\f(CW{toolbox name}/man/man3\fP, it will be available for perusal via \fBvman\fP
by other Khoros users that have access to that toolbox.  The purpose of the 
man1 page is to provide a detailed description of the function of the new 
program.  This should include complete descriptions of the input files, 
output files, and other arguments to the program.  
.PP
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
\fBFormatting man pages with nroff -\fP
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
This sub section is specifically for those writing image processing
programs, a more complete list of conventions is in Section E.
.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 J 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
ignore 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 toolbox source 
tree, and compiling the program.  You first might
want to examine the structure of the Khoros home source tree to get a feel
for its organization;  the layout of the toolbox in which you will be 
installing your new routine will mimic that organization, although it may
be considerably simplified.  The layout of the Khoros home source tree 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 toolbox 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.
During maintenance of the installed program, \fBghostreader\fP will use the 
configuration file to locate the appropriate files for input before updating 
the PS file file for the program; \fBghostwriter\fP will use the configuration
file to specify the paths for the various 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 toolbox source
tree where that file is to be located.  An example configuration file is presented 
below for the vroutine, "vfrog", which will be added to the "amphibian" toolbox.  
It has each of the 10 file keys filled out with 
the appropriate path information. ( The $ indicates that AMPHIBIAN is
an environment variable.)
\f(CW
     cfile: $AMPHIBIAN/src/vfrog
.br
     hfile: $AMPHIBIAN/src/vfrog
.br
     lfile:  $AMPHIBIAN/src/Lib
.br
     progfile:  $AMPHIBIAN/src/vfrog
.br
     man1file: $AMPHIBIAN/man/man1
.br
     man3file: $AMPHIBIAN/man/man3
.br
     panefile: $AMPHIBIAN/repos/cantata/subforms
.br
     helpfile: $AMPHIBIAN/doc/manpages
.br
     subhelpfile: $AMPHIBIAN/doc/cantata/subforms
.br
     topsrc: $AMPHIBIAN/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 -"
The man1 pages are formatted slightly differently for use in the 
\fBcantata\fP online help pages than the format used by the
\fBvman\fP command.  Online help pages for Khoros
programs are always located in \f(CW$KHOROS_HOME/doc/manpages\fP;  online 
help pages for new programs will be located in 
\f(CW{toolbox name}/doc/manpages\fP.  The \fBkinstall\fP program will format 
your man1 file for online help, and install a copy of it in the 
\f(CW{toolbox name}/doc/manpages\fP directory.
.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.  If this file does not exist yet, you will 
have to start it from a template that will be created for you by \fBkinstall\fP.
In any case, the subhelpfile directory will be located in 
\f(CW{toolbox name}/doc/cantata/subforms\fP.
.IP "topsrc -" 10 
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$AMPHIBIAN/src/vfrog\fP) or relative paths
(ie. cfile: \f(CWvfrog\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, \f(CW$AMPHIBIAN/src\fP.
.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 once a toolbox has
been created.  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 \fImachine\fP file. 
The machine file is located in \f(CW{toolbox_name}/repos/config/src_conf/\fP.
It MUST be named {toolbox_name}_mf;  in the example above, our machine file
would have been named "amphibian_mf".  The machine file specifies your user name 
for automatic mailing purposes, and the path to the source directory of the 
toolbox in question.  If you are not supporting multiple architectures, there 
are only two fields in the machine file which must be filled out correctly:  
the KHOROS_USER and LOCAL_SRC_TOP fields. The other fields MUST be empty.
There is a template machine file in 
\f(CW$KHOROS_HOME/repos/config/src_conf/template_mf\fP.
.PP
If your site is supporting multiple architectures, the machine file also
contains paths to the corresponding \fIsrcmach directories\fP within the
\fIsrcmach tree\fP. Note that a srcmach tree is \fIonly\fP established if 
a particular site is supporting different machine architectures.  
The srcmach tree consists of symbolic links to files in the original 
source tree, along with object files compiled for that particular 
architecture.  The machine file specifies the machine names for a site, 
as well as the path for the srcmach directories.  You must have one machine file
for each machine architecture, named for the machine itself. For complete details and
examples on the use of machine files with multiple architectures, see Chapter 9,
Section C.
.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 aaa -conf aaa.conf -toolbox bbb [-force c] [-type ddd]\fP
.sp
where:
.IP aaa
is the name of the vroutine that is being installed.
.br
.IP bbb
is the name of the toolbox in which the vroutine is to be installed.
.br
.IP c
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 ddd
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".  
.sp
.PP
The following scenario is provided to illustrate the installation of a routine 
into the Khoros system toolbox amphibian 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 and that you have created
the toolbox AMPHIBIAN.  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 
"vfrog" in the "amphibian" toolbox appears below.
.IP 1) 
From your work directory, initiate the \fBkinstall\fP program as follows:
.sp
\f(CW
% kinstall -name vfrog -conf vfrog.conf -toolbox amphibian
\fP
.sp
.PP
.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 machine 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 \f(CW/tmp\fP 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 already installing, 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 placed.  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 G, 
"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
