.\" @(#)sItems	2.10 12/8/92
.H1 "Items that appear in a defstar"
.pp
The following items can appear in a
.c defstar
directive.
Some of these can also appear in a
.c defgalaxy
directive, as explained below.
.UH name
.pp
.IE "name { }"
This is a required item, and has the syntax
.(c
name { \fIidentifier\fP }
.)c
It provides the name of the class to be defined, and (together with
the domain) determines
the names of the output files.
.UH domain
.pp
.IE "domain { }"
This is a required item; it specifies the domain, such as SDF.
Syntax:
.(c
domain { \fIidentifier\fP }
.)c
where
.i identifier
specifies the domain.  Currently, the SDF, DDF, and DE domains
are fully supported; for the Thor domain, a separate preprocessor
is normally used.
.UH derivedfrom
.pp
.IE "derivedfrom { }"
This optional item indicates that the star is derived from another class.
Syntax:
.(c
derivedfrom { \fIidentifier\fP }
.)c
where
.i identifier
specifies the base class.  The
.c .h
file for the base class is automatically included in the output
.c .h
file.
.pp
An important thing to remember for derived stars is that the
real C++ classname is formed by concatenating the user-visible
name and the domain name.  Thus the C++ classname for the star
.c LMS
in the
.c SDF
domain is
.c SDFLMS .
The
.c derivedfrom
statement, which may also be written
.c derivedFrom
or
.c derived ,
allows you to say either
.(c
derivedfrom { FIR }
.)c
or
.(c
derivedfrom { SDFFIR }
.)c
to specify the base class.
.UH descriptor
.pp
.IE "desc { }"
.IE "descriptor { }"
This item defines the descriptor for the class.  It has the syntax
.(c
descriptor { \fItext\fP }
.)c
or
.(c
desc { \fItext\fP }
.)c
where
.i text
is simply a section of text that will become the short descriptor
of the star or galaxy.  A principal use of the short descriptor
is to get on-screen help, so the descriptor should not include
any troff formatting commands.  Unlike the
.c explanation
(described below), it does not pass through troff.
The following are legal descriptors:
.sp
.nf
	\f(\*Fdesc { A one line descriptor. }
	desc {
A multi-line descriptor.
The same line breaks and spacing will be used when the descriptor
is displayed on the screen.
	}\fP
.fi
.sp
By convention, in these descriptors, references to the names
of states, inputs, and outputs should be enclosed in quotation marks.
Also, each descriptor should begin with a capital letter, and end
with a period.  If the descriptor seems to get long, use
the
.c explanation
directive, explained below.
.UH version
.pp
.IE "version { }"
This item contains two entries
as shown below
.(c
version { \fInumber  MO/DA/YR\fP }
.)c
where the number is a version number, and the MO/DA/YR is the
version date.
If you are using SCCS for version control
.IE SCCS
then the following syntax will work well:
.(c
version { %\&W\&% %\&G\&% }
.)c
When the file is checked in by SCCS, the string "%\&W\&%"
will be replaced with a string of the form:
"@(#)filename num", where num is the version number, and "%\&G\&%" will
be replaced with a properly formatted date.
.UH author
.pp
.IE "author { }"
This optional entry identifies the author of the star or galaxy,
and may contain any number of names.
The syntax is
.(c
author { \fIfirst name, second name and third name\fP }
.)c
Any set of characters between the brackets will be interpreted
as a list of author names.
.UH acknowledge
.pp
.IE "acknowledge { }"
This optional entry attaches an acknowledgement section to the
documentation.  The syntax is
.(c
acknowledge { \fIarbitrary single line of text\fP }
.)c
.UH copyright
.pp
.IE "copyright { }"
This optional entry attaches a copyright notice to the
.c .h ,
.c .cc ,
and
.c .t
files.
The syntax is
.(c
copyright { \fIcopyright information\fP }
.)c
For example, we used to use the following (our lawyers have recently
caused us to increase the verbosity):
.(c
copyright { 1991 The Regents of the University of California }
.)c
.UH location
.pp
.IE "location { }"
This item describes the location of a star definition.
The following descriptions are used, for example:
.(c
location { SDF main library }
.)c
or
.(c
location { \fIdirectory\fP }
.)c
.UH explanation
.pp
.IE "explanation { }"
This item is used to give longer explanations of the function of the stars.
The explanation will appear only in the
.c .t
documentation file.
The syntax is
.sp
.nf
	\f(\*Fexplanation {
\fIbody\f(\*F
	}\fR
.fi
The body is assumed to be troff source, but a number of macros
are provided for convenience.
.pp
The most frequently used macro in
.c explanation
sections is the un-numbered header, invoked as follows:
.(c
	.UH "Header title"
.)c
.pp
Star portHole and state names, by convention, should be
given in \fIitalics\fR.  This can be conveniently done
using the font-change escapes, as in "\\fIitalics\\fP".
\*(PT class names are, by convention, set in a special
font.  This font may be obtained in-line by the escape sequence
"\\f(\\*F", and again the previous font can be restored using
"\\fP".
Alternatively, the font can be obtained using the troff macro:
.(c
	.c word
.)c
or the start and end macros
.(c
	.(c
	body
	.)c
.)c
.UH defstate
.pp
.IE "defstate { }"
This item is used to define a state; it has other items inside it.
Here is an example of a state definition:
.(c
defstate {
	name { gain }
	type { int }
	default { 1.0 }
	desc { Output gain. }
	attributes { A_CONSTANT|A_SETTABLE }
}
.)c
There are five types of sub-items that may appear in a defstate
statement, in any order.  The
.c name
field is the name of the state; the
.c type
field is its type, which may be one of
.c int ,
.c float ,
.c string ,
.c complex ,
.c intarray ,
.c floatarray ,
.c complexarray ,
or
.c stringarray .
Case is ignored for the type argument.
.pp
The
.c default
item specifies the default value of the state; its argument is either
a string (enclosed in quotation marks) or a numeric value.
The above entry could equivalently have been written:
.(c
default { "1.0" }
.)c
Furthermore, if a particularly long default is required, as
for example when initializing an array, the string can be broken
into a sequence of strings.  The following example shows
the default for a ComplexArray:
.(c
default {
"(-.040609,0.0) (-.001628,0.0) (.17853,0.0) (.37665,0.0)"
"(.37665,0.0) (.17853,0.0) (-.001628,0.0) (-.040609,0.0)"
}
.)c
.pp
The
.c desc
(or
.c descriptor )
item,
which is optional but highly recommended, attaches a descriptor to the state.
The same formatting options are available as with the star descriptor.
.pp
Finally, the
.c attributes
keyword specifies state attributes.  At present, two attributes
.IE "attributes"
are defined for all stars: A_CONSTANT and A_SETTABLE (along with their
complements A_NONCONSTANT and A_NONSETTABLE).  If a state has the
A_CONSTANT attribute, then its value is not modified by the run-time code
in the star (it is up to you as the star writer to ensure that this
condition is satisfied).  States with the A_NONCONSTANT attribute may
change when the star is run.  If a state has the A_SETTABLE attribute,
then user interfaces (such as
.i pigi )
will prompt the user for values when directives such as
.i edit-parameters
.IE edit-parameters
are given.  States without this attribute are not presented to the user;
such states always start with their default values as the initial value.
If no attributes are specified, the default is A_CONSTANT|A_SETTABLE.
.pp
Code generation stars use a great number of attributes, many specific
to the model for which code is being generated.  Read the documentation
for the appropriate code generation domain to learn more about these.
.pp
Attributes are currently ignored for galaxy states.
.pp
Mechanisms for accessing and updating states in C++ methods
associated with a star are explained below, in the section entitled
``Writing C++ code.''
.UH "input, output, inmulti, outmulti"
.pp
.IE "input { }"
.IE "output { }"
.IE "inmulti { }"
.IE "outmulti { }"
These keywords are used to define a porthole, which may be an input or
output porthole or an input or output multiporthole.  Like
.c defstate ,
it contains other items.  Here is an example:
.(c
input {
	name { signalIn }
	type { complex }
	numtokens { 2 }
	desc { A complex input that consumes 2 input particles. }
}
.)c
.pp
Here,
.c name
specifies the porthole name.  This is a required item.
.c type
specifies the particle type.  The type may be one of
.c int ,
.c float ,
.c complex ,
.c message ,
or
.c anytype .
Again, case does not matter for the type value.  The
.c type
item may be omitted; the default type is
.c anytype .
For more information on 
.c message ,
please see the appendix at the end of this section.
.pp
The
.c numtokens
keyword (it may also be written
.IE numtokens
.IE "num { }"
.c num
or
.c numTokens )
specifies the number of tokens consumed or produced on
each firing of the star; if the item is omitted, a value of one
is used.  For stars where this number depends on the value
of a state, it is preferable to leave out the
.c numtokens
specification and to have the
.c start
method set the number of tokens (in the SDF domain and most code
generation domains, this is
accomplished with the
.c setSDFParams
method).
This item is used primarily in the SDF and code generation domains,
and is discussed
further in the documentation of those domains.
.pp
There is an alternative syntax for the type field of a porthole; this
syntax is used in connection with ANYTYPE to specify a connection
between the types of two portholes.  The syntax is
.IE "type inheritance"
.(c
type { = \fIname \fP }
.)c
where
.i name
is the name of another porthole.  This indicates that this porthole
inherits its type from the specified porthole.  For example, here
is the definition of the SDF Fork star:
.(c
defstar {
	name {Fork}
	domain {SDF}
	desc { A fork function: copies input particles to each output. }
	input {
		name{input}
		type{ANYTYPE}
	}
	version {2.10 12/8/92}
	outmulti {
		name{output}
		type{= input}
		desc{ Type is inherited from the input. }
	}
	go {
		MPHIter nextp(output);
		PortHole* p;
		while ((p = nextp++) != 0)
			(*p)%0 = input%0;
	}
}
.)c
.pp
Full details for accessing portholes C++ methods
associated with a star are explained below, in the section entitled
``Writing C++ code for stars.''
.UH constructor
.pp
.IE "constructor { }"
This item allows the user to specify extra C++ code to be executed in
the constructor for the class.  This code will be executed
.i after
any automatically generated code to initialize portholes, states, etc.
Syntax:
.sp
.(c
constructor { \fIbody\fP }
.)c
.sp
where
.i body
is a piece of C++ code.  It can be of any length.  Note that actions
that must be performed before every simulation run should appear in the
start method, not the constructor.
.UH conscalls
.pp
.IE "conscalls { }"
You may want to have members in your star or galaxy that have constructors
that require arguments.  These members would be added by using the 
.c public ,
.c private ,
or
.c protected
keywords.  If you have such members, the
.c conscalls
keyword provides a mechanism for passing arguments to the constructors.
Simply list the names of the members followed by the list of constructor
arguments for each, separated by commas if there is more than one.
Syntax:
.(c
conscalls { \fImember1(arglist), member2(arglist) \fP}
.)c
Note that \fImember1, \fRand \fImember2 should have been previously defined
in a
.c public ,
.c private ,
or
.c protected
section.
.UH destructor
.pp
.IE "destructor { }"
This item defines a destructor.  Syntax:
.(c
destructor { \fIbody\fP }
.)c
You generally need a destructor only if you allocate memory in the
constructor; termination functions that happen with every run should
appear in the
.c wrapup
function.  The optional keyword
.c inline
may appear before
.c destructor ;
if so, the destructor function definition appears inline, in the header
file.  Since the destructor for all stars is virtual, this is only a
win when the star is used as a base for derivation.
.UH start
.pp
.IE "setup { }"
This item defines the
.c setup()
method, which is called every time the simulation is restarted.  Syntax:
.(c
setup { \fIbody\fP }
.)c
The optional keyword
.c inline
may appear before the
.c setup
keyword.
It is common for this method to set parameters of input and output
portholes, and to initialize states.
The code syntax for doing this is explained below.
.pp
The alternative keyword
.c start
is accepted instead of
.c setup
for backward compatibility with previous releases.
.UH go
.pp
.IE "go { }"
This item defines the action taken by the star when it is fired.
Syntax:
.(c
go { \fIbody\fP }
.)c
The optional keyword
.c inline
may appear before the
.c go
keyword.
The go methods will typically read input particles and write outputs.
The code syntax for doing this is explained below.
.UH wrapup
.pp
.IE "wrapup { }"
This item defines the
.c wrapup()
method, which is called at the completion of a simulation.  Syntax:
.(c
wrapup { \fIbody\fP }
.)c
The optional keyword
.c inline
may appear before the
.c wrapup
keyword.
The wrapup methods might display or store final state values.
The code syntax for doing this is explained below.
.UH "exectime"
This item defines the optional
.c myExecTime()
function, which is used in code generation to specify how many time
units are required to execute the star's code.  The item is very similar
to the
.c go
item, except that the function must return an integer value.
Syntax:
.(c
exectime { \fIbody\fP }
.)c
The optional keyword
.c inline
may appear before the
.c exectime
keyword.
.UH "codeblock"
.pp
.IE "codeblock { }"
Codeblocks are parametized blocks of code for use in code generation
stars.  Their use and format is discussed in detail in the documentation
for code generation domains.  Syntax:
.(c
codeblock {
	code
	...
}
.)c
.UH "public, protected, private"
.pp
.IE "public { }"
.IE "protected { }"
.IE "private { }"
These three keywords allow the user to declare extra members for the
class with the desired protection.  Syntax:
.sp
	\fIprotkey body\fR
.sp
where
.i protkey
is
.c public ,
.c protected ,
or
.c private .
Example, from the Xgraph star:
.(c
protected {
	FILE *strm;
	int delFile;
	int index;
	const char* fileName;
}
.)c
If any of the added members require arguments for their constructors,
use the
.c conscalls
item to specify them.
.UH "ccinclude, hinclude"
.pp
.IE "ccinclude { }"
.IE "hinclude { }"
These directives cause the
.c .cc
file, or the
.c .h
file, to
.c #include
extra files.  By default, the
.c .cc
file includes
.c KnownBlock.h
and the generated
.c .h
file; the
.c .h
file will (for stars) include
.c \fIXXX\fPStar.h ,
where
.i XXX
is the domain name, or (for galaxies)
.c Galaxy.h ,
as well as the files for any states that are defined, and if
a
.c derived
section is found, the name of the baseclass as well.  Syntax:
.(c
ccinclude { \fIinclist\fP }
hinclude { \fIinclist\fP }
.)c
where
.i inclist
is a comma-separated list of include files.  Each filename must
be surrounded either by quotation marks
or by "<" and ">" (for system include files like
.c <math.h> ).
.UH code
.pp
.IE "code { }"
This keyword allows the user to specify a chunk of arbitrary C++ code.
This code is inserted into the
.c .cc
file after the include files but before everything else; it can be
used to define static non-class functions, declare external variables,
or anything else.  The outermost pair of curly braces is stripped.
Syntax:
.(c
code { \fIbody\fP }
.)c
.UH header
.pp
.IE "header { }"
This keyword allows the user to specify an arbitrary set of definitions
that will appear in the header file.  Everything between the curly
brackets is inserted into the
.c .h
file after the include files but before everything else.  The outermost
pair of curly braces is skipped.
.UH method
.pp
.IE "method { }"
The
.c method
item provides a fully general way to specify an additional method
for the class of star or galaxy that is being defined.  Here is an
example:
.(c
virtual method {
	name { exec }
	access { protected }
	arglist { "(const char* extraOpts)" }
	type { void }
	code {
		// code for the SDFXgraph::exec method goes here
	}
}
.)c
An optional function type specification may appear before the
.c method
keyword, which must be one of the following:
.(c
virtual
inline
pure
pure virtual
inline virtual
.)c
The
.c virtual
keyword makes a virtual member function.  If the 
.c pure
.c virtual
keyword is given, a pure virtual member function is declared and there must
be no
.c code
item in this case.
The function type
.c pure
is a synonym for
.c pure
.c virtual .
The 
.c inline
function type declares the function to be inline.
.pp
Here are the
.c method
subitems:
.ip \f(\*Fname\fR:
The name of the method.  This is a required item.
.ip \f(\*Faccess\fR:
The level of access for the method, one of
.c public ,
.c protected ,
or
.c private .
If the item is omitted,
.c protected
is assumed.
.ip \f(\*Farglist\fR:
The argument list for the method, as a quoted string.  If omitted,
the method has no arguments.
.ip \f(\*Ftype\fR:
The return type of the method.  If the return type is not a single
identifier, you must put quotes around it.  If it is omitted, the
return type is
.c void
(no value is returned).
.ip \f(\*Fcode\fR:
The code that implements the method.  This is a required item, unless
the
.c pure
keyword appears, in which case this item
.i cannot
appear.

