6. GemBuilder for C Files and Data 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  };

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.

 

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.

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.

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.