Parameters File Keywords

appobj

appobj	<name>

The appobj field indicates the name of the application object. All geodes with appl set under type (see above) must have an appobj entry. The name argument should be the name of the object of GenApplicationClass specified in the application's .goc file.

class

class	<name>

The class field specifies the name of the object class to be bound to the geode's process thread. This field has significance only if process is specified in the geode's type field (see below). This should be the same as the ProcessClass object designated in the .goc file (see the Hello World sample for an example of this connection). Note that this class binding will only be for the geode's first (primary) thread.

driver

driver	<name> [noload]

This field specifies another driver that is used by this geode. The noload flag indicates that the used driver does not need to be loaded when the geode is first launched. Most applications and libraries will not use exported routines from drivers, so few geodes will use this field. (Notable exceptions are those geodes that access serial and parallel ports--those geodes will include the serial or parallel driver.)

else

ifdef <VARIABLE>
        <glue statements>
else
        <other glue statements>
endif

The else statement is part of Glue's conditional linking support. If the variable named in the ifdef statement is false, then any commands between an else and an endif will be used when linking.

endif

ifdef <VARIABLE>
        <glue statements>
else
        <other glue statements>
endif

The endif statement is part of Glue's conditional linking support. The endif keyword signals the end of the conditional commands which were begun with a previous ifdef command.

entry

entry	<name>

This field is used by library geodes. The name argument is the name of the library routine to be called by the kernel when the library is loaded or unloaded and when a program using the library is loaded or unloaded.

exempt

exempt	<library-name>

If you wish to exempt a certain library from Glue's platform checking, call it out with the exempt keyword. Glue will not complain if you then use parts of the library not normally available with platforms named in your platform statement.

export

export	<name> [as <name2>]

This field identifies routines usable by geodes other than the one being compiled; these routines are "exported" for use by other programs. Both forms create entry point symbols for the routines. The first name argument must be the actual name of the routine. If the second, optional, name2 argument is included, then other programs will call that routine using the second name rather than the original. This allows a routine to have a different global name than that used by its creator geode.

This field is also used to export classes defined in a .goc or .goh file. See the Benoit sample application for an example.

heapspace

heapspace <space>

Specify the memory requirements for the geode--how much space it requires on the heap. This parameter is required for geodes to run efficiently on certain platforms, such as the Casio Z-7000. To find out what number to enter in this field, run your geode on the device in question with Swat attached. Use the "heapspace" Swat command to find out how much memory your geode requires. For more information about the "heapspace" Swat command, see its entry in the Swat commands reference section of the Tools manual.

The space may be specified in paragraphs, or in k of memory:

heapspace 250
heapspace 4k

ifdef

ifdef <VARIABLE>
        <glue statements>
endif

ifdef <VARIABLE>
        <glue statements>
else
        <other glue statements>
endif

The ifdef keyword is used to implement conditional linking. If the named VARIABLE is defined (via the -D command line argument to Glue--see the Using Tools chapter to find out how), then the commands between the ifdef and the next else or endif command will be used when linking. Otherwise, they will be ignored. If the VARIABLE is not defined, then any commands appearing between the optional else keyword and the endif keyword will be used.

It is possible to nest these statements:

ifdef FOO
	ifdef BAR
		library foobar
	else
		library fooonly
	endif
else
	ifdef BAR
		library baronly
	else
		library nada

        endif

endif

incminor

incminor [<name>]

The incminor directive is used at the end of a library's .gp file before new routines are added (after a release of the library has already been made). After this release, new export and publish directives will be put after this incminor directive. The incminor directive causes two things: First, the geode's minor protocol number gets incremented by one. Second, any geode that uses your library will depend only on the higher minor protocol number if it actually uses one or more of the entry points exported after the incminor directive.

Any number of incminor directives may be used in a given .gp file. The major and the base minor numbers still come from a .rev file, if one exists.

The name argument is optional; it may be used in conjunction with the protominor compiler directive. Glue will know that the structures marked with the protominor label should be associated with the revision represented by the incminor directive.

library

library	<name> [noload]

This field specifies another library that is used by this geode. The noload flag indicates that the used library does not need to be loaded when the geode is first launched (though symbolic information will be loaded in any case). Note that every geode must have the line

library geos

included in the .gp file. Most will also have the following line:

library ui

Any number of used libraries may be specified.

load

load	<name> ["<class>"] as [<name2>] [<align>] [<combine>]\
 ["<class2>"]

The load field is used when you want to alter the way a segment is linked for your geode. This is especially useful, for example, when integrating another company's runtime routines into your application or library; their segments may correspond to specifications other than yours.

Every segment read in has a given name, class, alignment, and combination type. These are described below (the load parameters appear after):

name: This is the actual name of the segment being loaded in. Segments with the same name are treated as one continuous segment.
class: Segments with the same class name are always loaded together into memory regardless of their order in the geode's source code. Class names in the load directive must always be enclosed in quotation marks.
align: This specifies the alignment type of the segment--on what type of address the segment can start. Possible alignment settings are byte, word, double word, paragraph, and page.
combine: Segments with the same name may appear in different code modules. The combine parameter specifies how these segments are to be combined when loaded. The combine type may be one of the following (see your assembly reference manual for more information): COMMON, PRIVATE, PUBLIC, STACK, or RESOURCE.

The parameters for load are listed below. Only the first is necessary, to inform Glue which segment is to undergo the alterations. For an example of using the load statement, see below.

name: This represents the actual original name of the segment. It is a necessary parameter so Glue knows which segment's linkage is to be altered.
class: This is the original class name of the segment. It must be enclosed in quotation marks if given. If you do not need to change the class, this parameter is unnecessary.
name2: This is the new name of the segment, if any.
align: This specifies the new align type of the segment, if any.
combine: This specifies the new combine type of the segment, if any.
class2: This specifies a new class name for the segment, if any is required. If you do not need to change the class, this parameter is unnecessary. The new class must be in quotation marks.

Examples:

load _NAME_ "CODE" as CODE word public

load _NAME_ "CODE" as DATASEG para common "DATA"

longname

longname "<string>"

The longname field designates a 32-character name for the geode. This name will be displayed with the geode's icon by GeoManager; all geodes should be given a long name.

name

name	<pname>.<ext>

The name field in the parameters file gives the geode a permanent name which will be used by both the Glue linker and the Swat debugger. Every geode must have a permanent name. Note that the pname argument must be no more than eight characters, and the ext argument must be no more than four. Additionally, the ext argument may not be "appl," as that is reserved.

When Glue is linking an error-checking geode, it drops the fourth character of ext and adds "ec" to the end of pname .

nosort

nosort

This keyword should appear before the list of resources. Normally glue will sort the geode's resources to optimize their arrangement. This keyword turns off that sorting. If you will generate .GYM (generic symbol) files for your geode, you should use the nosort option, as it will be important that all versions of your geode order their resources in the same way. If you won't generate .GYM files, you probably don't want to use this option.

platform

platform <name>

The platform directive specifies that the Geode is compatible with the named system. This gives a sign of how backwards-compatible the application is. If multiple platforms are specified, Glue will make sure that the major protocol numbers for each of the libraries it finds within the platforms match. Having done that, it will use the smallest minor protocol number it can find for each library to ensure compatibility across all platforms.

If a reference is ever made to an entry point in a library that would cause the executable to depend upon a later version of the library than specified in the platform file, glue will complain. For example, if the specified platoform used GrObj version 534.1 and glue found a reference to an entry point that didn't exist until GrObj 534.3 (ie., an entry point exported following 3 'incminor's in grobj.gp), glue will spit out an error message like:

error: file "somegeode.gp", line 59: Usage of NewGrObjRoutine requires grobj minor protocol 3, but platform files only allow minor protocol 1

If the new routine happens to be a "published" routine, glue will copy it into the geode in an effort to avoid the error.

Common platforms include:

zoomer: Casio Z-7000, Tandy Z-PDA
bullet: Sharp PT-9000
geos20: GEOS 2.0 Desktop environment

For a list of all predefined platforms, go to the the Include directory of your SDK installation and list all *.PLT files.

publish

publish <name>

Normally, if a geode is required to run (via platform specifications) with a version of a library that doesn't contain one of the entry points required by the geode, glue will notify the user of the inconsistency, and the link will fail. However, if that entry point happens to be a published routine, glue will actually copy the routine into the geode and switch the call over to the newly copied routine to remove the dependency on the library routine. Glue does this by copying any routines marked "publish" in a library's .gp file into the .ldf file, then copying them out into whatever other geodes needs when those geodes are linked. Routines are marked "publish" by replacing the word "export" with the word "publish" in the .gp file, like so:

publish PublishedRoutinei

The published routines appear in .ldf files in individual segments named after the routine (e.g. _PUBLISHED_PublishedRoutine), each containing a routine, also named after the published routine (e.g., _PUBLISHED__PUBLISHED_PublishedRoutine) You'll know one of these routines has been linked into your geode by examining the resource summary output by glue:

Resource 					Size # Relocs
-------------------------------------------------
CoreBlock 					0 	0
dgroup 					240 	8
_PUBLISHED_GROBJCALCCORNERS 					53 	1
_PUBLISHED_GROBJBODYPROCESSALLGR 					94 	2
TEST2_E 					478 	27
INTERFACE 					652 	1
CHANGETEXTDIALOG 					232 	1
APPRESOURCE 					416 	1

resource

resource <name> (read-only|preload|discardable|fixed|conforming|shared|\
 code|data|lmem|discard-only|swap-only|ui-object|object|\
 no-swap|no-discard)+

The resource

(none): If no attribute is specified, the resource named becomes a private data resource for the geode.
read-only: The resource block may not be modified by the program.
preload: The resource block should be loaded when the geode is first launched.
discardable: The resource block may be discarded from memory if necessary.
fixed: The resource block should reside in fixed memory.
conforming: The resource block, if containing code, may be called from a lower privilege level. If containing data, it may be accessed from a lower privilege level. (This applies only in protected mode and is not currently implemented.)
shared: The resource block may be used by other geodes. (Note: It is an error to specify code and shared without read-only .)
code: The resource block contains executable code.
data: The resource block contains data only. If a data resource is designated read-only and not fixed, it is assumed to be discardable.
lmem: The resource block consists of a local memory heap. This implies the attribute data (above), though not the condition pertaining to being discardable.
discard-only: The resource block should not be swapped but may be discarded. This is useful for initialization code.
swap-only: The resource block should not be discarded but may be swapped.
ui-object: The resource block contains objects to be run by the UI. This implies lmem , shared , and no-discard . All blocks for a geode designated ui-object will be run in a UI thread created specifically for the geode's UI objects.
object: The resource block contains objects that are to be run by the application's process thread rather than by the UI. This implies lmem and no-discard .
no-swap: The resource block will not be swapable.
no-discard: The resource block will not be discardable.

Because most resources are code resources, standard code does not have to be declared in the parameters file. Code resources default to code , read-only , and shared . However, if the resource is named in the .gp file, the default is overridden in favor of the settings presented. This fact is useful primarily when programming in assembly--in C, code resources are not declared explicitly.

The Hello World sample application uses only standard code resources (undeclared) and UI resources (designated ui-object ). Some other examples are listed below:

Shared data

resource <name> data shared

Initialization code

resource <nm> code shared read-only preload no-swap

Common code used by several geodes (this is the default)

resource <name> code shared read-only

Self-modifying code (strongly discouraged)

resource <name> code

stack

stack	<number>

The stack field designates the size of the application's stack in bytes. The default stack size is 2000 bytes. This field is not necessary for geodes unless they require a different size stack (the Hello World sample uses a slightly smaller stack size for example only). The stack field is valid only for geodes with a process aspect.

tokenchars

tokenchars "<string>"

This is one of two fields that identifies a unique token in GeoManager's token database file (see tokenid , below). The tokenchars field must be a string of four characters that identifies the geode's token. Note that these characters also appear in the geode file's extended attributes.

tokenid

tokenid	<number>

This is the other of two fields that identifies a unique token in GeoManager's token database file (see tokenchars , above). It must be a number corresponding to the programmer's manufacturer ID number. Note that this number also appears in the geode file's extended attributes.

type

type	(process|driver|appl|library)+ [single] [system] [uses-coproc]\
[needs-coproc] [has-gcm] [c-api]

The type field in the parameters file designates certain characteristics of the geode being compiled. These attributes correspond to the GeodeAttrs type and determine how the Glue linker will put the geode together. The attributes are as follows:

process: This attribute indicates the geode has its own thread. Applications should always have process specified in the type field.
driver: This attribute indicates the geode has a driver aspect.
appl: This attribute indicates the geode has an application aspect.
library: This attribute indicates the geode has a library aspect.
single: This geode may only have one copy running at a time. Some applications may allow multiple copies to be running at once; they should not specify single as a type attribute.
system: This attribute is set for drivers that must be exited specially and must always be exited. For example, a swap driver has special exit conditions that must always be met and is therefore a system driver.
uses-coproc: This attribute is set if the geode will make use of a math coprocessor if one is available. Note that if the geode with this attribute set is a library, all applications that use the library will inherit the property. This attribute is used to indicate that the coprocessor's state must be saved during a context switch.
needs-coproc: This attribute indicates that the geode must have a math coprocessor to run. (This implies uses-coproc , above).
has-gcm: This attribute indicates that the application being compiled has a GCM (appliance) version. This information is used by Welcome to locate all GCM applications.
c-api: This attribute indicates the library entry points are written in C so the kernel must call them with C calling conventions.

usernotes

usernotes "<string>"

This field specifies text to be put in the .geo file's usernotes field. The text must be within quotation marks and can be up to 100 characters long. It must contain no line breaks. This can be useful for containing copyright notices in the executable files. The user can read the text in the usernotes by using GeoManager's File/Get Info command.