6. GemBuilder for C Files and Data Structures

Previous chapter

Next chapter

This chapter describes the GemBuilder for C include files, data structures, and other reference information that may be useful when writing your application.

6.1  GemBuilder for C Include Files

The following include files are provided for use with GemBuilder for C functions. These files are in the $GEMSTONE/include directory.

Your C source code should include one of these include files:

gci.hf

Forward references to the GemBuilder functions. Use when creating GCI applications.

gciua.hf

Forward references to the GemBuilder functions that includes definitions to support user actions. Include this when creating user actions.

Using the GemStone C Statistics Interface (GCSI), as described in Chapter 8, “GemStone C Statistics Interface”, include the following:

shrpcstats.ht

Defines all cache statistics. (For a list of cache statistics, refer to the “Monitoring GemStone” chapter of the System Administration Guide for GemStone/S 64 Bit.)

gcsi.hf

Prototypes for all GCSI functions.

gcsierr.ht

GCSI error numbers.

The following include files are included by gciua.hf and/or gci.hf; you do not need to explicitly include any other files in order to use the GCI functions:

gcirtl.hf

Forward references to the GemBuilder functions that perform run time loading.

flag.ht

Contains host-specific C definitions for compilation.

gcicmn.ht

Defines common C types and macros.

gcierr.ht

Defines mnemonics for all GemStone errors.

gcifloat.ht

Macros, constants and functions for accessing the bodies of instances of GemStone classes Float and SmallFloat.

gci.ht

Defines C types for use by GemBuilder functions.

gcilegacy.ht

Definitions that are used by gci.hf; they are in a distinct file since they are not used by the thread-safe GCI.

gcioc.ht

Defines C mnemonics for sizes and offsets into objects.

gcioop.ht

Defines C mnemonics for predefined GemStone objects.

gciuser.ht

Defines a macro to be used to install user actions; loaded by gciua.hf , not by gci.hf .

version.ht

Defines C mnemonics for version-dependent strings.

6.2  Reserved Oops

The GemStone/S 64 Bit distribution includes the file gcioop.ht, which defines C macros that define the OOPs of certain commonly used GemStone objects. Your code can compare these with any value of type OopType.

Note that the actual definition of these macros is subject to change without notice in future software releases. Your C application should refer to the OOPs of predefined GemStone objects by defined macro name only.

The following are some of the names for predefined GemStone objects Refer to $GEMSTONE/include/gcioop.ht for a complete list.

OOP_ILLEGAL

OOP_NIL (nil)
OOP_FALSE (false)
OOP_TRUE (true)

OOP_MinusOne
OOP_MinusTwo
OOP_Zero
OOP_One
OOP_Two
OOP_Three
OOP_Four
MAX_SMALL_INT
MIN_SMALL_INT

OOP_ASCII_NUL represents the first ASCII character OOP. Other Characters have specific OOPs, but no macros.

OOP_CLASS_className, where className is the name of a class (which may be uppercase or camelcase) Refer to gcioop.ht for specific names.

OOP_LAST_KERNEL_OOP (which has the same value as the last class)

6.3  GemBuilder Data Types

The following C types/C++ classes are used by GemBuilder functions. The file
$GEMSTONE/include/gci.ht defines each of the GemBuilder types.

BoolType

An integer.

ByteType

An unsigned 8-bit integer.

OopType

Object-oriented pointer, an unsigned 32-bit integer.

FloatKindEType

Enumerated type that defines the possible kinds of an IEEE binary float.

GciClampedTravArgsSType

A C++ class for clamped traversal arguments.

GciDateTimeSType

A structure for representing GemStone DateTimes.

GciDateAndTime

A structure for representing GemStone DateAndTimes.

GciPosixDateAndTime

A structure for representing GemStone DateAndTimes in posix form.

GciDbgFuncType

The type of C function called by GciDbgEstablish.

GciErrSType

A GemStone error report; see Error Report Structure - GciErrSType.

GciJumpBufSType

Error jump buffer.

GciObjInfoSType

A C++ class for a GemStone object information report; see Object Information Structure - GciObjInfoSType.

GciObjRepHdrSType

A C++ class for an object report header; see Object Report Header - GciObjRepHdrSType.

GciObjRepSType

A C++ class for an object report; see Object Report Structure - GciObjRepSType.

GciSessionIdType

A signed 32-bit integer.

GciStoreTravDoArgsSType

A C++ class for store traversal arguments.

GciTravBufType

A traversal buffer; see Traversal Buffer - GciTravBufType.

GciUserActionSType

A structure for describing a user action (see User Action Information Structure - GciUserActionSType.

Date/Time Structures

GciDateTimeSType

GemBuilder includes some functions to facilitate access to objects of type DateTime. These functions also make use of the C representation for time, time_t.

The class GciDateTimeSType has the following fields:

int year;         // 1901..1000000 
int dayOfYear;    // 1..366 
int milliseconds; // ms since midnight 
OopType timeZone; // oop of the time zone

GciDateAndTime

The class GciDateAndTime has the following fields:

int64 microSeconds;  // posixMicroseconds if year is -1
int offsetSeconds;
int year;         // Gregorian year per DateAndTime
int dayOfYear;    // 1..366; or -1, meaning microSeconds are
			// posix and year is not used.

GciPosixDateAndTime

The class GciPosixDateAndTime has the following fields:

int64 microseconds;  // UTC since 1970
int offset;

GCI_SECONDS_PER_DAY

A C constant encoding the number of seconds in a day.

enum { GCI_SECONDS_PER_DAY = 86400  };

Error Report Structure - GciErrSType

An error report is a C++ class named GciErrSType. This includes the following fields:

OopType

category

Deprecated. The value is always OOP_GEMSTONE_ERROR_CAT.

OopType

context

The OOP of a GsProcess that provides the state of the virtual machine for use in debugging. This GsProcess can be used as the argument to GciContinue or GciClearStack. If the virtual machine was not running, then context is OOP_NIL. If you are not interested in debugging or in continuing from an error, your program can ignore this value.

OopType

exceptionObj

Either an instance of Exception or nil (if the error was not signaled from Smalltalk execution).

OopType

args[GCI_MAX_ERR_ARGS]

An optional array of error arguments. In this release, GCI_MAX_ERR_ARGS is defined to be 10.

int

number

The GemStone error number (a positive integer).

int

argCount

The number of arguments in the args array.

unsigned char

fatal

Nonzero if this error is fatal.

char

message[GCI_ERR_STR_SIZE + 1]

The null-terminated Utf8 containing the error message. In this release, GCI_ERR_STR_SIZE is defined to be 1024.

char

reason[GCI_ERR_reasonSize + 1]

The null-terminated Utf8 reason. GCI_ERR_reasonSize is defined to be the same as GCI_ERR_STR_SIZE.

The arguments (args) are specific to the error encountered. See the gcierr.ht file for a full list of errors and their arguments.

In the case of a compiler error, this is a single argument — the OOP of an array of error identifiers. Each identifier is an Array with three elements: (1) the error number (a SmallInteger); (2) the offset into the source string at which the error occurred (also a SmallInteger); and (3) the text of the error message (a String).

In the case of a fatal error, fatal is set to nonzero (TRUE). Your connection to GemStone is lost, and the current session ID (from GciGetSessionId) is reset to GCI_INVALID_SESSION_ID.

Object Information Structure - GciObjInfoSType

Object information is placed in a C++ class named GciObjInfoSType. Object information access functions provide information about objects in the database. These functions offer C-style access to much information that would otherwise be available only through calls to GemStone. For more information about the GciObjInfoSType structured type, refer to GciFetchObjImpl.

OopType

objId

OOP of the object.

OopType

objClass

Class of the object.

int64

objSize

Object's total size in bytes or OOPs; see GciFetchSize_.

int

namedSize

Number of named instance variables in the object.

unsigned short

objectSecurityPolicyId

The ID of the object’s security policy.

unsigned short

_bits

Bits indicating the implementation format and mask. See gci.hf for the bit definitions.

Functions

The object information class GciObjInfoSType provides the following functions:

unsigned char isInvariant( );
Returns non-zero if this object is invariant. Returns zero otherwise.

unsigned char isIndexable( );
Returns non-zero if this object is indexable. Returns zero otherwise.

unsigned char isPartial( );
Returns non-zero if the value buffer does not contain the entire object; that is, the operation truncated the object’s instance variables. Returns zero otherwise.

unsigned char isOverlayed( );
Returns non-zero if overlay semantics were used on this operation. Returns zero otherwise. When the traversal is overlayed, you can use OOP_ILLEGAL to mask out instance variables that you don’t want to modify, and then store into the remaining instance variables.

unsigned char objImpl( );
Returns an unsigned char in the range 0..3 that corresponds to the object’s implementation format. The mnemonics for these values are:

GC_FORMAT_OOP
GC_FORMAT_BYTE
GC_FORMAT_NSC
GC_FORMAT_SPECIAL

For bit functions, see gci.hf.

 

Object Report Structure - GciObjRepSType

Each object report has two parts: a fixed-size header (as defined in the C++ class GciObjRepHdrSType) and a variable-size value buffer (an array of the values of the object’s instance variables):

class GciObjRepSType { 
 public:
  GciObjRepHdrSType hdr;        /* object report header */
  union {
    ByteType        bytes[1];   /* Byte objects   */
    OopType         oops[1];    /* Pointer objects */
  } u;
Functions

The object report class GciObjRepSType provides these functions:

int64 usedBytes();
When constructing an object report buffer, returns the size of the object report, including any alignment considerations.

GciObjRepHdrSType* nextReport();
Given a pointer to an object report in a traversal buffer, this function increments the pointer by usedBytes (the size of the object report).

ByteType* valueBufferBytes();
Returns a pointer to the start of the body, as bytes.

OopType* valueBufferOops();
Returns a pointer to the start of the body, as OOPs.

Object Report Header - GciObjRepHdrSType

An object report header is a C++ class named GciObjRepHdrSType. This class holds a general description of an object, and contains the following fields:

int

valueBuffSize

Size (in bytes) of the object's value buffer.

short

namedSize

Number of named instance variables in the object.

unsigned short

objectSecurityPolicyId

The ID of the object’s security policy.

OopType

objId

OOP of the object.

OopType

oclass

Class of the object.

int64

firstOffset

Offset of first value to fetch or store; 1 means first instVar is the first named instVar.

unit64

_idxSizeBits

40 bits size, 8 bits dynamic inst var size, 6 bits unused, 2 bits swizzle, 8 bits implementation format and mask. See gcicmn.hf for the bit definitions.

Functions

The object report header class GciObjRepHdrSType provides the following functions:

int64 idxSize();
Returns the number of indexable or varying instance variables.

void setIdxSize(int64 size);
Sets the number of indexable or varying instance variables.

void setIdxSizeBits(int64 size, unsigned char bits);
Sets both the indexable size and the eight bits defined by the enum of the mask values. Intended for GemStone use only.

int objImpl( );
Returns an integer in the range 0..3 that corresponds to the object’s implementation format. See the description on here.

int setObjImpl(int impl);
Defines the object’s implementation format. The argument must be an integer in the range 0..3 corresponding to the implementation format. You may use the mnemonics GC_FORMAT_OOP, GC_FORMAT_BYTE, GC_FORMAT_NSC, and GC_FORMAT_SPECIAL.

int64 objSize( );
Returns the total number of instance variables in the object (both indexable and named).

void clearBits( );
Sets indexable, invariable, partial, overlayed, non-readable, and clamped to FALSE.

unsigned char isClamped( );
Returns non-zero if this object report is clamped. Returns zero otherwise.

unsigned char noReadAuthorization( );
Returns non-zero if this object report is not readable. Returns zero otherwise.

unsigned char isInvariant( );
Returns non-zero if this object report is invariant. Returns zero otherwise.

unsigned char isIndexable( );
Returns non-zero if this object report is indexable. Returns zero otherwise.

unsigned char isPartial( );
Returns non-zero if the value buffer does not contain the entire object; that is, the traversal operation truncated the object’s instance variables. Returns zero otherwise.

unsigned char isOverlayed( );
Returns non-zero if overlay semantics were used on this store traversal operation. Returns zero otherwise. When the traversal is overlayed, you can use OOP_ILLEGAL to mask out instance variables that you don’t want to modify, and then store into the remaining instance variables.

void setIsClamped(unsigned char val);
If val is non-zero, make this object report clamped.

void setNoReadAuth(unsigned char val);
If val is non-zero, make this object report non-readable.

void setInvariant(unsigned char val);
If val is non-zero, make this object report invariant.

void setIndexable(unsigned char val);
If val is non-zero, make this object report indexable.

void setOverlayed(unsigned char val);
If val is non-zero, use overlay semantics on this store traversal.

ByteType* valueBufferBytes() ;
Returns a pointer to the start of the body, as bytes.

OopType* valueBufferOops()
Returns a pointer to the start of the body, as OOPs.

int64 usedBytes() ;
Returns the size (in bytes) of this object report, including the size of the header, value buffer, and any padding bytes needed at the end of the report so that the next report in the buffer begins on an address that is a multiple of 8.

GciObjRepHdrSType * nextReport() ;
Given a pointer to an object report in a traversal buffer, this function increments the pointer by usedBytes (the size of the object report).

Description

During a store traversal operation, if the specified idxSize is inadequate to accommodate the contents of the value buffer (the values in u.bytes or u.oops), the store operation will automatically increase idxSize (the number of the object’s indexed variables) as needed. If the specified objClass is not indexable, then the idxSize is ignored; in addition, if there are more OOPs in the value buffer than there are named instance variables, and the object is not an NSC, an error will be generated.

During a store traversal operation, the firstOffset indicates where to begin storing values into the object’s array of instance variables. In that array, the object’s named instance variables are followed by its unnamed variables. If firstOffset is not 1, all instance variables (named or indexed) up to the firstOffset will be initialized to nil or 0. The firstOffset must be in the range (1, objSize+1).

The isInvariant() value is true if the object itself is invariant. This can happen in one of three ways:

  • The application program sends the message immediateInvariant to the object.
  • The application program explicitly executes setInvariant() in the report header and then uses that report header in a call to GciStoreTrav.

The object’s class was created with instancesInvariant: true and the object has been committed.

Object implementation

The gcioc.ht include file defines four mnemonics that can be of assistance when you are handling the object implementation field (objImpl): GC_FORMAT_OOP, GC_FORMAT_BYTE, GC_FORMAT_NSC, and GC_FORMAT_SPECIAL. These mnemonics, and no other values, should be used to supply values for objImpl, or to test its contents. However, the gcioc.ht file also defines other mnemonics that can be used in other contexts related to object implementations, indexability, and invariance.

An object’s implementation may restrict the number of its named instance variables (namedSize) and its indexed instance variables (idxSize), as contained in the object report header.

  • If the object implementation is GC_FORMAT_OOP, the object can have both named and unnamed instance variables.
  • If the object implementation is GC_FORMAT_BYTE, the object can only have indexed instance variables, and its namedSize is always zero.
  • If the object implementation is GC_FORMAT_NSC, the object can have both named and unnamed instance variables. (The NSC’s idxSize reports the number of unnamed instance variables, even though they are unordered, not indexed.)
  • If the object implementation is GC_FORMAT_SPECIAL, the object cannot have any instance variables, and the number of both its named and unnamed variables is always zero.
  • Table 6.1 Object Implementation Restrictions on Instance Variables

    Object Implementation

    Named Instance Variables OK?

    Unnamed Instance Variables OK?

    0=Pointer

    YES

    YES (always indexed)

    1=Byte

    NO

    YES (always indexed)

    2=NSC

    YES

    YES (always unordered)

    3=Special

    NO

    NO

For more information about object implementation types, see Structural Access to Objects.

Store Traversal Arguments - GciStoreTravDoArgsSType

GciStoreTravDoArgsSType holds traversal arguments, and is described in $GEMSTONE/include/gcicmn.ht. It contains the following fields:

GciTravBufType*

storeTravBuff

The traversal buffer. For details, see Traversal Buffer - GciTravBufType.

int

storeTravFlags

Flag bits that determines how the objects should be handled.

GCI_STORE_TRAV_DEFAULT = 0
Default behavior: use "add" semantics for varying instvars of Nsc's; if object to be stored into does not exist, give error.

GCI_STORE_TRAV_NSC_REP = 0x1,
Use REPLACE semantics for varying instvars of NSCs.

GCI_STORE_TRAV_CREATE = 0x2
If an object to be stored into does not exist, create the new object and add it to the PureExportSet .

GCI_STORE_TRAV_FINISH_UPDATES = 0x8
After processing the last object report in the traversal buffer, execute GciProcessDeferredUpdates.

GCI_STORE_TRAV_SWIZZLE_IN_PLACE = 0x10
if swizzling by the client is being done for transmit to a server with opposite byte order, this flag says it is ok to swizzle the caller's buffer in place before transmitting. Reduces client memory access footprint of a large store traversal

int

doPerform

  • If this field is 0, this function executes a string using args->u.executestr, with the semantics of GciExecute.
  • If this field is 1, then executes a perform using
    args->u.perform, with the semantics of GciPerform.
  • If this field is 2, execute a string that is the source code for a Smalltalk block using stdArgs->u.executestr, passing the block arguments in execBlock_args.
  • If this field is 3, perform no server Smalltalk execution, but traverse the object specified in
    stdArgs->u.perform.receiver as if it was the results of execution.
  • If this field is 4, resume execution of a suspended Smalltalk Process using stdArgs->u.continueArgs, with the semantics of GciContinueWith.

int

doFlags

Flags to disable or permit asynchronous events and debugging in Smalltalk. These flags apply whatever the value of doPerform.

  • 0 (default) disables the debugger during execution.
  • GCI_PERFORM_FLAG_ENABLE_DEBUG = 1 allows debugging, making this function behave like GciPerform.
  • GCI_PERFORM_FLAG_DISABLE_ASYNC_EVENTS = 2 disables asynchronous events.
  • GCI_PERFORM_FLAG_SINGLE_STEP = 3 places a single-step breakpoint at the start of the method to be performed, and then executes to hit that breakpoint.

union

u

One of three structures containing appropriate input fields for the specified operation.

  • The structure u.perform should be used when doPerform is set to 1 or 3,
  • u.executestr should be used when doPerform is set to 0 or 2
  • u.continueArgs should be used when doPerform is set to 4.

For more information on these structs and how to use them, see gcicmn.ht.

OopType*

alteredTheOops

An array allocating memory for OOPs of objects that will be modified as a consequence of executing the specified code.

int

alteredNumOops

The number of OOPs in alteredTheOops. On input, the caller must set this to the maximum number of OOPs that will fit in alteredTheOops. Upon completion, this field indicates the number of OOPs actually written to alteredTheOops.

BoolType

alteredCompleted

Upon output, TRUE if the alteredTheOops contains the complete set of objects modified as a result of executing the specified code; false otherwise. If FALSE, call GciAlteredObjs for the rest of the modified objects.

perform has the following fields:

OopType

receiver

 

char

pad[24]

Make later elements same offset as executestr

const char*

selector

1 byte per character

const OopType*

args

 

int

numArgs

 

ushort

environmentId

 

executestr has the following fields:

OopType

contextObject

 

OopType

sourceClass

String, Utf8 or Unicode7 or DoubleByteString

OopType

symbolList

 

int64

sourceSize

 

const char*

source

1 or 2 bytes per char, client-native byte order

const OopType*

args

ignored unless ExecuteBlock

int

numArgs

ignored unless ExecuteBlock

ushort

environmentId

 

continueArgs has the following fields:

OopType

process

 

OopType

replaceTopOfStack

 

Clamped Traversal Arguments - GciClampedTravArgsSType

GciClampedTravArgsSType holds the arguments for clamped traversal, and includes the following fields:

OopType

clampSpec

The OOP of the Smalltalk ClampSpecification to be used, or OOP_NIL, if the traversal is to operate without clamping.

int

level

Maximum traversal depth. When the level is 1, an object report is written to the traversal buffer for each element in theOops. When the level is 2, an object report is also obtained for the instance variables of each level-1 object. When the level is 0, the number of levels in the traversal is not restricted.

GciTravBufType *

travBuff

A pointer to the traversal buffer.

int

retrievalFlags

The value of retrievalFlags should be given by using the following mnemonics:

GCI_RETRIEVE_DEFAULT and GCI_RETRIEVE_EXPORT Causes results to automatically be added to an export set using GciSaveObjs semantics.

GCI_CLEAR_EXPORT Causes traverse to clear the export set using GciReleaseAllOops before filling traversal buffer.

GCI_COMPRESS_TRAV Compress traversal buffers before transmissions between gem and rpc gci client, including the store traversal of this call, and any GciMoreTraversal calls used to finish this call.

GCI_NOKILL_TRAV Start a traversal that will allow other GCI calls to preceed GciMoreTraversal calls that are part of this traversal. Only the start of another traversal will kill this traversal.

GCI_TRAV_REFS_EXCLUDE_RESULT_OBJ Exclude execution result * from the traversal result.

GCI_TRAV_REFS_EXCLUDE_EXPORTED_RESULT_OBJ
Only give report for execution result if not already exported. Has no effect if GCI_TRAV_REFS_EXCLUDE_RESULT_OBJ is set..

Traversal Buffer - GciTravBufType

The C++ class GciTravBufType describes a traversal buffer, and defines the following fields:

uint

allocatedBytes

The allocated size of the body.

uint

usedBytes

The used bytes of the body.

ByteType

body[8]

The actual body size is variable, with a minimum of GCI_MIN_TRAV_BUFF_SIZE. Maximum size is 4GB, or, if compression is used, 2GB.

To create a new instance of GciTravBufType, use the function GciAllocTravBuf.

Functions

The traversal buffer class GciTravBufType provides these functions:

GciObjRepSType* firstReport();
Returns a pointer to the first object report in the buffer.

GciObjRepSType* readLimit() ;
Used when reading object reports out of a buffer. Returns a pointer past the end of last object report in the buffer. If readLimit()==firstReport(), the buffer is empty.

GciObjRepSType* writeLimit();
Used when composing a buffer. Returns a pointer one byte past the end of the allocated buffer.

GciObjRepHdrSType* firstReportHdr();
Returns a pointer to the first object report in the buffer.

GciObjRepHdrSType* readLimitHdr();
Used when reading object reports out of a buffer. Returns a pointer past the end of last object report in the buffer.

GciObjRepHdrSType* writeLimitHdr();
Used when composing a buffer. Returns a pointer one byte past the end of the allocated buffer.

User Action Information Structure - GciUserActionSType

The structured type GciUserActionSType describes a user action function. It defines the following fields:

char

userActionName[GCI_MAX_ACTION_NAME+1]

The user action name (a case-insensitive, null-terminated string). In this release, GCI_MAX_ACTION_NAME is defined to be 31.

int

userActionNumArgs

The number of arguments in the C function.

GciUserActionFType

userAction

A pointer to the C user action function.

unsigned int

userActionFlags

For internal use.

 

Previous chapter

Next chapter