7. GemBuilder C Function Reference

Previous chapter

Next chapter

This chapter describes the GemBuilder functions that may be called by your C application program.

7.1  Function Summary Tables

Tables Functions for Controlling Sessions and Transactions through Utility Functions summarize the GemBuilder C functions and the services that they provide to your application.

Table 7.1 Functions for Controlling Sessions and Transactions 

GciAbort,

GciNbAbort

Abort the current transaction.

GciBegin,
GciNbBegin

Begin a new transaction.

GciCommit,
GciNbCommit

Write the current transaction to the database.

GciDeclareAction

Associate a C function with a Smalltalk user action.

GciEncrypt

Encrypt a password string.

GciGetSessionId

Find the ID number of the current user session.

GciInit,
GciInit_

Initialize GemBuilder.

GciInitAppName

Override the default application configuration file name.

GciInstallUserAction

Associate a C function with a Smalltalk user action.

GciIsRemote

Determine whether the application is running linked or remotely.

GciLoadUserActionLibrary

Load an application user action library.

GciLogin,

GciLoginEx,

GciNbLoginEx

Start a user session.

GciLogout

End the current user session.

GciNbEnd,

GciNbEndPoll

Test the status of nonblocking call in progress for completion.

GciProcessDeferredUpdates_

Process deferred updates to objects that do not allow direct structural update.

GciRtlIsLoaded

Report whether a GemBuilder library is loaded.

GciRtlLoad

Load a GemBuilder library.

GciRtlUnload

Unload a GemBuilder library.

GciServerIsBigEndian

Determine whether or not the server process is big-endian.

GciSessionIsRemote

Determine whether or not the current session is using a Gem on another machine.

GciSetCacheName_

Set the name that a linked application will be known by in the shared cache.

GciSetNet,

GciSetNetEx

Set network parameters for connecting the user to the Gem and Stone processes.

GciSetSessionId

Set an active session to be the current one.

GciShutdown

Logout from all sessions and deactivate GemBuilder.

GciUserActionInit

Declare user actions for GemStone.

GciUserActionShutdown

Enable user-defined clean-up for user actions.

 

Table 7.2 Functions for Handling Errors and Interrupts and for Debugging 

GciCallInProgress

Determine if a GemBuilder call is currently in progress.

GciClearStack

Clear the Smalltalk call stack.

GciContinue,
GciNbContinue

Continue code execution in GemStone after an error.

GciContinueWith
GciNbContinueWith

Continue code execution in GemStone after an error.

GciDbgEstablish

Specify the debugging function for GemBuilder to execute before most calls to GemBuilder functions.

GciDbgEstablishToFile

Write trace information for most GemBuilder functions to a file.

GciDbgLogString

Pass a message to a trace function.

GciEnableSignaledErrors

Establish or remove GemBuilder visibility to signaled errors from GemStone.

GciErr

Prepare a report describing the most recent GemBuilder error.

GciInUserAction

Determine whether or not the current process is executing a user action.

GciHardBreak

Interrupt GemStone and abort the current transaction.

GciLongJmp

Provides equivalent functionality to the corresponding longjmp() or _longjmp() function.

GciPollForSignal

Poll GemStone for signal errors without executing any Smalltalk methods.

GciPopErrJump

Discard a previously saved error jump buffer.

GciPushErrJump

Associate GemBuilder error handling with a jump buffer by pushing a jump buffer onto the stack.

GciRaiseException

Signal an error, synchronously, within a user action.

GciSetErrJump

Enable or disable the current error handler.

GciSetHaltOnError

Halt the current session when a specified error occurs.

Gci_SETJMP

(MACRO) Save a jump buffer in GemBuilder’s error jump stack.

GciSoftBreak

Interrupt the execution of Smalltalk code, but permit it to be restarted.

GciStep

Continue code execution in GemStone with specified single-step semantics.

Table 7.3 Functions for Managing Object Bitmaps 

GciAlteredObjs

Find all exported or dirty objects that have changed and are therefore in the ExportedDirtyObjs set.

GciDirtyExportedObjs

Find all objects in the ExportedDirtyObjs set.

GciDirtyObjsInit

Begin tracking which objects in the session workspace change.

GciDirtySaveObjs

Find all exported objects that have changed and are therefore in the ExportedDirtyObjs set.

GciHiddenSetIncludesOop

Determines whether the given OOP is present in the specified hidden set.

GciReleaseAllGlobalOops

Remove all OOPS from the PureExportSet, making these objects eligible for garbage collection.

GciReleaseAllOops

Remove all OOPS from the PureExportSet, or if in a user action, from the user action’s export set, making these objects eligible for garbage collection.

GciReleaseGlobalOops

Remove an array of GemStone OOPs from the PureExportSet, making them eligible for garbage collection.

GciReleaseOops

Remove an array of GemStone OOPs from the PureExportSet, or if in a user action, remove them from the user action’s export set, making them eligible for garbage collection.

GciSaveGlobalObjs

Add an array of OOPs to the PureExportSet, making them ineligible for garbage collection.

GciSaveObjs

Add an array of OOPs to the PureExportSet, or if in a user action to the user action’s export set, making them ineligible for garbage collection.

 

 

Table 7.4 Functions for Compiling and Executing Smalltalk Code in the Database 

GciClassMethodForClass

Compile a class method for a class.

GciClassRemoveAllMethods

Remove all methods from the method dictionary of a class.

GciCompileMethod

Compile a method.

GciExecute,
GciNbExecute

Execute a Smalltalk expression contained in a GemStone String or Utf8 object.

GciExecuteFromContext

Execute a Smalltalk expression contained in a String or Utf8 object as if it were a message sent to another object.

GciExecuteStr,
GciNbExecuteStr

Execute a Smalltalk expression contained in a C string.

GciExecuteStrFetchBytes,
GciNbExecuteStrFetchBytes

Execute a Smalltalk expression contained in a C string, returning byte-format results.

GciExecuteStrFromContext,
GciNbExecuteStrFromContext

Execute a Smalltalk expression contained in a C string as if it were a message sent to an object.

GciInstMethodForClass

Compile an instance method for a class.

GciPerform,
GciNbPerform

Send a message to a GemStone object.

GciPerformNoDebug,
GciNbPerformNoDebug

Send a message to a GemStone object, and temporarily disable debugging.

GciPerformSymDbg

Send a message to a GemStone object, using a String object as a selector.

GciPerformTraverse

First send a message to a GemStone object, then traverse the result of the message.

 

Table 7.5 Functions for Accessing Symbol Dictionaries 

GciResolveSymbol

Find the OOP of the object to which a symbol name C string refers, in the context of the current session’s user profile.

GciResolveSymbolObj

Find the OOP of the object to which a symbol name String or MultiByteString refers, in the context of the current session’s user profile.

GciStrKeyValueDictAt

Find the value in a symbol KeyValue dictionary at the corresponding string key.

GciStrKeyValueDictAtObj

Find the value in a symbol KeyValue dictionary at the corresponding object key.

GciStrKeyValueDictAtObjPut

Store a value into a symbol KeyValue dictionary at the corresponding object key.

GciStrKeyValueDictAtPut

Store a value into a symbol KeyValue dictionary at the corresponding string key.

GciSymDictAt

Find the value in a symbol dictionary at the corresponding string key.

GciSymDictAtObj

Find the value in a symbol dictionary corresponding to the key object.

GciSymDictAtObjPut

Store a value into a symbol dictionary at the corresponding object key.

GciSymDictAtPut

Store a value into a symbol dictionary at the corresponding string key.

GciTraverseObjs

Traverse an array of GemStone objects.

 

Table 7.6 Functions for Creating and Initializing Objects 

GciCreateByteObj

Create a new byte-format object.

GciCreateOopObj

Create a new pointer-format object.

GciGetFreeOop

Allocate an OOP.

GciGetFreeOops

Allocate multiple OOPs.

GciGetFreeOopsEncoded

Allocate multiple OOPs.

GciNewByteObj

Create and initialize a new byte object.

GciNewCharObj

Create and initialize a new character object.

GciNewDateTime

Create and initialize a new instance of DateTime or a subclass of DateTime.

GciNewDateAndTime

Create and initialize a new instance of DateAndTime.

GciNewDateAndTimePosix

Create and initialize a new instance of DateAndTime.

GciNewOop

Create a new GemStone object.

GciNewOops

Create multiple new GemStone objects.

GciNewOopUsingObjRep

Create a new GemStone object from an existing object report.

GciNewString

Create a new String object from a C character string.

GciNewSymbol

Create a new Symbol object from a C character string.

GciNewUtf8String

Create a new Unicode string object from a UTF-8 encoded C character string.

 

Table 7.7 Functions and Macros for Testing and Converting Objects and Values 

GCI_BOOL_TO_OOP

(MACRO) Convert a C Boolean value to a GemStone Boolean object.

GciByteArrayToPointer

Given a result from GciPointerToByteArray, return a C pointer.

GCI_CHR_TO_OOP

(MACRO) Convert a 32 bit C character value to a GemStone Character object.

GciCTimeToDateTime

Convert a C date-time representation to the equivalent GemStone representation.

GciDateTimeToCTime

Convert a GemStone date-time representation to the equivalent C representation.

Gci_doubleToSmallDouble

Convert a C double to a SmallDouble object.

GciFetchDateTime

Convert the contents of a DateTime object and place the results in a C structure.

GciFetchDateAndTime

Convert the contents of a DateAndTime object and place the results in a C structure.

GciFetchDateAndTimePosix

Convert the contents of a DateAndTime object and place the results in a C structure.

GciFetchUtf8Bytes_

Encode a String, MultiByteString, or Uft8 as UTF-8, and fetch the bytes of the encoded result.

GciFloatKind

Obtain the float kind corresponding to a C double value.

GciFltToOop

Convert a C double value to a SmallDouble or Float object.

GCI_I64_IS_SMALL_INT

(MACRO) Determine whether or not a 64-bit C integer is in the SmallInteger range.

GciI32ToOop

Convert a C 32-bit integer value to a GemStone object.

GciI64ToOop

Convert a C 64-bit integer value to a GemStone object.

GCI_OOP_IS_BOOL

(MACRO) Determine whether or not a GemStone object represents a GemStone Smalltalk Boolean.

GCI_OOP_IS_CHAR

(MACRO) Determine whether or not a GemStone object represents a Character.

GCI_OOP_IS_SmallDate

(MACRO) Determine whether or not a GemStone object represents a SmallDate.

GCI_OOP_IS_SmallDateAndTime

(MACRO) Determine whether or not a GemStone object represents a SmallDateAndTime.

GCI_OOP_IS_SMALL_DOUBLE

(MACRO) Determine whether or not a GemStone object represents a SmallDouble.

GCI_OOP_IS_SMALL_FRACTION

(MACRO) Determine whether or not a GemStone object represents a SmallFraction.

GCI_OOP_IS_SMALL_INT

(MACRO) Determine whether or not a GemStone object represents a SmallInteger.

GCI_OOP_IS_SmallScaledDecimal

(MACRO) Determine whether or not a GemStone object represents a SmallScaledDecimal.

GCI_OOP_IS_SmallTime

(MACRO) Determine whether or not a GemStone object represents a SmallTime.

GCI_OOP_IS_SPECIAL

(MACRO) Determine whether or not a GemStone object has a special representation.

GciOopToBool

Convert a Boolean object to a C Boolean value.

GCI_OOP_TO_BOOL

(MACRO) Convert a Boolean object to a C Boolean value.

GciOopToChar16

Convert a Character object to a 16-bit C character value.

GciOopToChar32

Convert a Character object to a 32-bit C character value.

GciOopToChr

Convert a Character object to a C character value.

GCI_OOP_TO_CHR

(MACRO) Convert a Character object to a C character value.

GciOopToFlt

Convert a SmallDouble, Float, or SmallFloat object to a C double.

GciOopToI32

Convert a GemStone object to a C 32-bit integer value.

GciOopToI64

Convert a GemStone object to a C 64-bit integer value.

GciPointerToByteArray

Given a C pointer, return a SmallInteger or ByteArray containing the value of the pointer.

GciStringToInteger

Convert a C string to a GemStone SmallInteger or LargeInteger object.

 

Table 7.8 Object Traversal and Path Functions and Macros 

GCI_ALIGN

(MACRO) Align an address to a word boundary.

GciClampedTrav,
GciNbClampedTrav

Traverse an array of objects, subject to clamps.

GciExecuteStrTrav,
GciNbExecuteStrTrav

Execute a string and traverse the result of the execution.

GciFetchPaths

Fetch selected multiple OOPs from an object tree.

GciFindObjRep

Fetch an object report in a traversal buffer.

GciMoreTraversal,
GciNbMoreTraversal

Continue object traversal, reusing a given buffer.

GciObjRepSize_

Find the number of bytes in an object report.

GciPerformTrav
GciNbPerformTrav

First send a message to a GemStone object, then traverse the result of the message.

GciPerformTraverse

First send a message to a GemStone object, then traverse the result of the message.

GciSetTraversalBufSwizzling

Control swizzling of the traversal buffers.

GciStorePaths

Store selected multiple OOPs into an object tree.

GciStoreTrav
GciNbStoreTrav

Store multiple traversal buffer values in objects.

GciStoreTravDo_,
GciNbStoreTravDo_

Store multiple traversal buffer values in objects, execute the specified code, and return the resulting object.

GciStoreTravDoTrav_
GciNbStoreTravDoTrav_

Combine in a single function the calls to GciStoreTravDo_ and GciClampedTrav, to store multiple traversal buffer values in objects, execute specified code, and traverse the result object.

GciStoreTravDoTravRefs_
GciNbStoreTravDoTravRefs_

Combine in a single function modifications to session sets, traversal of objects to the server, optional Smalltalk execution, and traversal to the client of changed objects and (optionally) the result object.

GciTraverseObjs,
GciNbTraverseObjs

Traverse an array of GemStone objects.

CAUTION
Exercise caution when using the following structural access functions. Although they can improve the speed of GemStone database operations, these functions bypass GemStone’s message-sending metaphor. That is, structural access functions may bypass any checking that might be coded into your application’s methods. In using structural access functions, you implicitly assume full responsibility for safeguarding the integrity of your system.

Note, however, that structural access functions do not bypass checks on authorization violations or concurrency conflicts.

Table 7.9 Structural Access Functions and Macros 

GciAddOopToNsc

Add an OOP to the unordered variables of a nonsequenceable collection.

GciAddOopsToNsc

Add multiple OOPs to the unordered variables of a nonsequenceable collection.

GciAppendBytes

Append bytes to a byte object.

GciAppendChars

Append a C string to a byte object.

GciAppendOops

Append OOPs to the unnamed variables of a collection.

GciClassNamedSize

Find the number of named instance variables in a class.

GciFetchByte

Fetch one byte from an indexed byte object.

GciFetchBytes_

Fetch multiple bytes from an indexed byte object.

GciFetchChars_

Fetch multiple ASCII characters from an indexed byte object.

GciFetchClass

Fetch the class of an object.

GciFetchNamedOop

Fetch the OOP of one of an object’s named instance variables.

GciFetchNamedOops

Fetch the OOPs of one or more of an object’s named instance variables.

GciFetchNamedSize

Fetch the number of named instance variables in an object.

GciFetchNameOfClass

Fetch the class name object for a given class.

GciFetchObjImpl

Fetch the implementation of an object.

GciFetchOop

Fetch the OOP of one instance variable of an object.

GciFetchOops

Fetch the OOPs of one or more instance variables of an object.

GciFetchSize_

Fetch the size of an object.

GciFetchVaryingOop

Fetch the OOP of one unnamed instance variable from an indexable pointer object or NSC.

GciFetchVaryingOops

Fetch the OOPs of one or more unnamed instance variables from an indexable pointer object or NSC.

GciFetchVaryingSize_

Fetch the number of unnamed instance variables in a pointer object or NSC.

GciIsKindOf

Determine whether or not an object is some kind of a given class or class history.

GciIsKindOfClass

Determine whether or not an object is some kind of a given class.

GciIsSubclassOf

Determine whether or not a class is a subclass of a given class or class history.

GciIsSubclassOfClass

Determine whether or not a class is a subclass of a given class.

GciIvNameToIdx

Fetch the index of an instance variable name.

GciNscIncludesOop

Determines whether the given OOP is present in the specified unordered collection.

GciObjExists

Determine whether or not a GemStone object exists.

GciObjInCollection

Determine whether or not a GemStone object is in a Collection.

GciObjIsCommitted

Determine whether or not an object is committed.

GciRemoveOopFromNsc

Remove an OOP from an NSC.

GciRemoveOopsFromNsc

Remove one or more OOPs from an NSC.

GciReplaceOops

Replace all instance variables in a GemStone object.

GciReplaceVaryingOops

Replace all unnamed instance variables in an NSC object.

GciSetVaryingSize

Set the size of a collection.

GciStoreByte

Store one byte in a byte object.

GciStoreBytes

(MACRO) Store multiple bytes in a byte object.

GciStoreBytesInstanceOf

Store multiple bytes in a byte object.

GciStoreChars

Store multiple ASCII characters in a byte object.

GciStoreIdxOop

Store one OOP in an indexable pointer object’s unnamed instance variable.

GciStoreIdxOops

Store one or more OOPs in an indexable pointer object’s unnamed instance variables.

GciStoreNamedOop

Store one OOP into an object’s named instance variable.

GciStoreNamedOops

Store one or more OOPs into an object’s named instance variables.

GciStoreOop

Store one OOP into an object’s instance variable.

GciStoreOops

Store one or more OOPs into an object’s instance variables.

 

Table 7.10 Utility Functions 

GciAll7Bit

Determine if a String contains only 7-bit ASCII characters.

GciCompress

Compress the supplied data, which can be uncompressed with GciUncompress.

GciCompressUsingLz4

Compress the supplied data, which can be uncompressed with GciUncompressUsingLz4.

GciDecodeOopArray

Decode an OOP array that was previously run-length encoded.

GciDecSharedCounter

Decrement the value of a shared counter.

GciEnableFreeOopEncoding

Enable encoding of free OOPs sent between the client and the RPC Gem.

GciEnableFullCompression

Enable full compression between the client and the RPC version of GemBuilder.

GciEncodeOopArray

Encode an array of OOPs, using run-length encoding.

GciFetchNumEncodedOops

Obtain the size of an encoded OOP array.

GciFetchNumSharedCounters

Obtain the number of shared counters available on the shared page cache used by this session.

GciFetchSharedCounterValuesNoLock

Fetch the value of multiple shared counters without locking them.

GciIncSharedCounter

Increment the value of a shared counter.

GciProduct

Return an 8-bit unsigned integer that indicates the GemStone/S product.

GciReadSharedCounter

Lock and fetch the value of a shared counter.

GciReadSharedCounterNoLock

Fetch the value of a shared counter without locking it.

GciSetSharedCounter

Set the value of a shared counter.

GciUncompress

Uncompress the supplied data, assumed to have been compressed with GciCompress.

GciUncompressUsingLz4

Uncompress the supplied data, assumed to have been compressed with GciCompressUsingLz4.

GciVersion

Return a string that describes the GemBuilder version.

 

 

 

 

 

 

 

 

7.2  Executing the examples

The following topaz input defines classes and objects that are used in some of the examples for functions.

run
Array subclass: #Account 
   instVarNames: #(#id #customer #salesRep) inDictionary: UserGlobals. 
Object subclass: #Customer 
   instVarNames: #(#name #address) inDictionary: UserGlobals. 
Object subclass: #Address 
	instVarNames: #(#street #city #state) inDictionary: UserGlobals. 
%
 
run 
Account compileMissingAccessingMethods. 
Customer compileMissingAccessingMethods. 
Address compileMissingAccessingMethods. 
%
 
method: Address
asString
^ self street, ' ', self city, ', ', self state
%
method: Customer
asString
^ self name, ', ', self address asString.
%
method: Account
asString
^'Account ', self id asString, ' for ', self customer asString
%
 
run
UserGlobals at: #AllAccounts put: IdentityBag new.
%
 
run
| createBlk |
createBlk := [:data | | addr cust acct |
   addr := Address new street: (data at: 2); city: (data at: 3); 
      state: (data at: 4); yourself.
   cust := Customer new name: (data at: 1);  address: addr; 
      yourself.
   acct := Account new id: (data at: 5); customer: cust; 
      salesRep: (data at: 6); yourself.
   acct addAll: (data at: 6).
   acct].
{ 
{'Sam Houston' . '2321 Walnut Dr' . 'Myrtle Point' . 
   'OR' . 7212. 'Mark Rabinowitz'. { 'GS64' . 'GBS/VA'} } . 
{'Maya Johnson' . '12 Main Str' .  'Ashland' . 'OR' .  
	2323. 'Mark Rabinowitz' . {'GS64' . 'GBS/VW' . 'GemConnect'}} .
{'Mario Harar' . '12 N. First Str' . 'Washougal' . 'WA' . 
	10073. 'Linda Waffle'. { 'GS64' } } }
     do: 
		[:dataArr | AllAccounts add: (createBlk value: dataArr)].
System commitTransaction.
%
 

GciAbort

Abort the current transaction.

Syntax

void GciAbort( )

Description

This function causes the GemStone system to abort the current transaction. All changes to persistent objects that were made since the last committed transaction are lost, and the application is connected to the most recent version of the database. Your application must fetch again from GemStone any changed persistent objects, to refresh the copies of these objects in your C program. Use the GciDirtySaveObjs function to determine which of the fetched objects were also changed.

This function has the same effect as issuing a hard break, or the function call GciExecuteStr("System abortTransaction", OOP_NIL).

See Also

Interrupting GemStone Execution
GciCommit
GciNbAbort

GciAddOopToNsc

Add an OOP to the unordered variables of a nonsequenceable collection.

Syntax

void GciAddOopToNsc(
OopType theNsc,
OopType theOop );

Arguments

theNsc   

The OOP of the NSC from which to remove the object theOop.

theOops

The OOPs to be added.

Description

This function adds an OOP to the unordered variables of an NSC, using structural access.

Example

OopType GciAddOopToNsc_example(void)
{
  // return an IdentityBag containing the SmallIntegers with value 0..99
 
  OopType oNsc = GciNewOop(OOP_CLASS_IDENTITY_BAG);
  for (int i = 0; i < 100; i ++) {
    OopType oNum = GciI32ToOop(i);
    GciAddOopToNsc(oNsc, oNum);
  }
  return oNsc;
}
 

See Also

GciAddOopsToNsc
GciNscIncludesOop
GciRemoveOopFromNsc
GciRemoveOopsFromNsc

GciAddOopsToNsc

Add multiple OOPs to the unordered variables of a nonsequenceable collection.

Syntax

void GciAddOopsToNsc(
OopType theNsc,
const OopType theOops[ ],
int numOops );

Arguments

theNsc   

The OOP of the NSC to which to add the OOPs.

theOops

The array of OOPs to be added to the NSC.

numOops

The number of OOPs to add.

Description

This function adds multiple OOPs to the unordered variables of an NSC, using structural access.

Example

OopType GciAddOopsToNsc_example(void)

{

// return an IdentityBag containing the SmallIntegers with value 0..99

 

enum { AddOopsToNsc_SIZE = 100 };

 

OopType oNsc = GciNewOop(OOP_CLASS_IDENTITY_BAG);

 

OopType values[AddOopsToNsc_SIZE];

for (int i = 0; i < AddOopsToNsc_SIZE; i ++) {

values[i] = GciI32ToOop(i);

}

GciAddOopsToNsc(oNsc, values, AddOopsToNsc_SIZE);

return oNsc;

}

See Also

GciAddOopToNsc
GciNscIncludesOop
GciRemoveOopFromNsc
GciRemoveOopsFromNsc

GCI_ALIGN

(MACRO) Align an address to a word boundary.

Syntax

uintptr_t * GCI_ALIGN(argument)

Arguments

argument    

The pointer or integer to be aligned.

Return Value

The first multiple of 8 that is greater than or equal to the input argument.

Description

This macro can be used to round up a pointer or size to be a multiple of sizeOf(OopType).

Provided for compatibility. New code should use the accessor functions in GciObjRepHdrSType; see Object Report Header - GciObjRepHdrSType.

GciAll7Bit

Determine if a String contains only 7-bit ASCII characters.

Syntax

BoolType GciAll7Bit(
const char * aString,
size_t * stringLength);

Arguments

aString      

A null-terminated string.

stringLength  

Returns the length of aString, computed by strlen(aString).

Return Value

Returns TRUE if each character in aString is in the 7-bit ASCII range, that is, a value <= 127; FALSE if any characters have values of 128 or higher.

Description

The function GciAll7Bit is used to test if a String is in the ASCII range, which will not involve encoding to UTF-8 for storage.

See Also

GciFetchUtf8Bytes_

GciAllocTravBuf

Allocate and initialize a new GciTravBufType structure.

Syntax

(GciTravBufType *) GciAllocTravBuf(
size_t allocationSize);

Arguments

allocationSize  

The size of the traversal buffer.

Description

This function allocates and initializes a new GciTravBufType structure.

See Also

Traversal Buffer - GciTravBufType

GciAlteredObjs

Find all exported or dirty objects that have changed and are therefore in the ExportedDirtyObjs set.

Syntax

BoolType GciAlteredObjs(
OopType theOops[ ],
int * numOops );

Arguments

theOops       

An array for the of OOPs of the objects in the ExportedDirtyObjs set.

numOops       

Pointer to the maximum number of OOPs that can be returned in this call, that is, the size (in OOPs) of the buffer specified by theOops; on return, the number of actual OOPs in the theOops result.

Return Value

The function result indicates whether all dirty objects have been returned. If the operation is not complete, GciAlteredObjs returns FALSE, and it is expected that the application will make repeated calls to this function until it returns TRUE, indicating that all of the dirty objects have been returned. If repeated calls are not made, then the unreturned objects persist in the list until the next time GciAlteredObjs, or another call that destructively accesses the ExportedDirtyObjs set is called.

Description

Typically, a GemStone C application program caches some database objects in its local object space, generally in the PureExportSet or if in a user action, in the user action’s export set (see GciSaveObjs). After an abort or a successful commit, the user’s session is resynchronized with the most recent version of the database. The values of instance variables cached in your C program may no longer accurately represent the corresponding GemStone objects. In such cases, your C program must update its representation of those objects. The function GciAlteredObjs permits you to determine which objects your application needs to reread from the database.

This function returns a list of all objects that are in the PureExportSet and are “dirty”. An object is considered dirty (changed) under one or more of the following conditions:

  • The object was changed by Smalltalk execution from this session.
  • The object was changed by a call from this session to any GemBuilder function from within a user action.
  • The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
  • The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
  • The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.

Calls to GciStore... (other than GciStorePaths), GciAppend..., GciReplace..., and GciCreate... do not put the modified object into the set of dirty objects (unless the call is from within a user action). The assumption is that the client does not want the dirty set to include modifications that the client has explicitly made.

You must call GciDirtyObjsInit once after GciLogin before you can use GciAlteredObjs.

Note that GciAlteredObjs removes OOPs from the ExportedDirtyObjs set as it enumerates.

See Also

GciDirtyObjsInit
GciReleaseAllOops
GciReleaseOops
GciSaveObjs

GciAppendBytes

Append bytes to a byte object.

Syntax

void GciAppendBytes(
OopType theObject,
int64 numBytes,
const ByteType * theBytes );

Arguments

theObject

A byte object, to which bytes are appended.

numBytes

The number of bytes to be appended.

theBytes

A pointer to the bytes to be appended.

Description

This function appends numBytes bytes to byte object theObject. Its effect is equivalent to GciStoreBytes(x, GciFetchSize_(x)+1, theBytes, numBytes).

GciAppendBytes raises an error if theObject is a Float or SmallFloat. Float and SmallFloat objects are of a fixed and unchangeable size.

See Also

GciAppendChars
GciStoreBytes

GciAppendChars

Append a C string to a byte object.

Syntax

void GciAppendChars(
OopType theObject,
const char * aString );

Arguments

theObject

A byte object, to which the string is appended.

aString

A pointer to the string to be appended.

Description

This function appends the characters of aString to byte object theObject.

See Also

GciAppendBytes
GciStoreChars

GciAppendOops

Append OOPs to the unnamed variables of a collection.

Syntax

void GciAppendOops(
OopType theObject,
int numOops,
const OopType* theOops );

Arguments

theObject

A collection object, to which additional OOPs are appended.

numOops

The number of OOPs to be appended.

theOops

A pointer to the OOPs to be appended.

Description

Appends numOops OOPs to the unnamed variables of the collection theObject. If the collection is indexable, this is equivalent to:

GciStoreOops(theObject, GciFetchSize_(theObject)+1, theOops, numOops);

If the collection is an NSC, this is equivalent to:

GciAddOopsToNsc(theObject, theOops, numOops);

If the object is neither indexable nor an NSC, an error is generated.

See Also

GciAddOopsToNsc
GciStoreOops

GciBegin

Begin a new transaction.

Syntax

void GciBegin( )

Description

This function begins a new transaction. If there is a transaction currently in progress, it aborts that transaction. Calling GciBegin is equivalent to the function call GciExecuteStr("System beginTransaction", OOP_NIL).

See Also

GciAbort
GciCommit
GciNbBegin

GCI_BOOL_TO_OOP

(MACRO) Convert a C Boolean value to a GemStone Boolean object.

Syntax

OopType GCI_BOOL_TO_OOP(aBoolean)

Arguments

aBoolean    

The C Boolean value to be translated into a GemStone object.

Return Value

The OOP of the GemStone Boolean object that is equivalent to aBoolean.

Description

This macro translates a C Boolean value into the equivalent GemStone Boolean object. A C value of 0 translates to the GemStone Boolean object false ( OOP_FALSE). Any other C value translates to the GemStone Boolean object true (OOP_TRUE).

Example

BoolType GCI_BOOL_TO_OOP_example(void)
{
  // zero returns OOP_FALSE
  OopType result = GCI_BOOL_TO_OOP( 0 );
  if ( ! result == OOP_FALSE)
     { return false; }
  
  // any non-zero argument returns OOP_TRUE
  result = GCI_BOOL_TO_OOP( 99 );
  if ( ! result == OOP_TRUE)
     { return false; }
  
  return true;
}

See Also

GciOopToBool,
GCI_OOP_TO_BOOL

GciByteArrayToPointer

Given a result from GciPointerToByteArray, return a C pointer.

Syntax

void * GciByteArrayToPointer(
OopType arg );

Arguments

arg   

A GemStone SmallInteger or ByteArray that was returned by GciPointerToByteArray.

Description

Given an argument that was the result of GciPointerToByteArray, this function returns the corresponding C pointer.

See Also

GciPointerToByteArray

GciCallInProgress

Determine if a GemBuilder call is currently in progress.

Syntax

BoolType GciCallInProgress( )

Return Value

This function returns TRUE if a GemBuilder call is in progress, and FALSE otherwise.

Description

This function is intended for use within signal handlers. It can be called any time after GciInit.

GciCallInProgress returns FALSE if the process is currently executing within a user action and the user action’s code is not within a GemBuilder call. It considers the highest (most recent) call context only.

See Also

GciInUserAction

GciCheckAuth

Gather the current authorizations for an array of database objects.

Syntax

void GciCheckAuth(
const OopType oopArray[ ];
ArraySizeType arraySize;
unsigned char authCodeArray[ ] );

Arguments

oopArray   

An array of OOPs of objects for which the user’s authorization level. is to be ascertained. The caller must provide these values.

arraySize

The number of OOPs in oopArray.

authCodeArray

The resulting array, having at least arraySize elements, in which the authorization values of the objects in oopArray are returned as 1-byte integer values.

Description

GciCheckAuth checks the current user’s authorization for each object in oopArray up to arraySize, returning each authorization code in the corresponding element of authCodeArray. The calling context is responsible for allocating enough space to hold the results.

Authorization levels are:

1 - No authorization

2 - Read authorization

3 - Write authorization

Special objects, such as instances of SmallInteger, are reported as having read authorization.

Authorization values returned are those that have been committed to the database; they do not reflect changes you might have made in your local workspace. To query the local workspace, send an authorization query message to a particular object security policy using GciPerform.

If any member of oopArray is not a legal OOP, GciCheckAuth generates the error OBJ_ERR_DOES_NOT_EXIST. In that case, the contents of authCodeArray are undefined.

GCI_CHR_TO_OOP

GCI_CHR_TO_OOP_

(MACRO) Convert a 32 bit C character value to a GemStone Character object.

Syntax

OopType GCI_CHR_TO_OOP(uint aChar)

OopType GCI_CHR_TO_OOP_(uint aChar)

Arguments

aChar    

The C uint value to be translated into a GemStone object.

Return Value

The OOP of the GemStone Character object that is equivalent to aChar. If unit is larger than 0x10FFFF, then GCI_CHR_TO_OOP_ returns OOP_ILLEGAL, while GCI_CHR_TO_OOP returns the Character with codePoint 0x10FFFF.

Description

This macro translates a 32-bit C character value into the equivalent GemStone Character object.

The variants differ according to how they handle out of range input arguments.

Example

OopType GCI_CHR_TO_OOP_example(void)
{
  // return the OOP for the ASCII character 'a'  
  OopType theOop = GCI_CHR_TO_OOP('a'); 
  return theOop;
}

See Also

GciOopToChr

GciClampedTrav

Traverse an array of objects, subject to clamps.

Syntax

BoolType GciClampedTrav(
const OopType * theOops,
int numOops,
GciClampedTravArgsSType * travArgs );

Arguments

theOops   

An array of OOPs representing the objects to traverse.

numOops  

The number of elements in theOops.

travArgs   

Pointer to an instance of GciClampedTravArgsSType. See Clamped Traversal Arguments - GciClampedTravArgsSType for details on the specific fields: the OOP for a ClampSpecification, traversal depth, traversal buffer, and retrieval flags.

On return, GciClampedTravArgsSType->travBuff is updated.

The first element placed in the buffer is the actualBufferSize, an integer that indicates how many bytes were actually stored in the buffer by this function. The remainder of the traversal buffer consists of a series of object reports, each of which is of type GciObjRepSType.

Return Value

Returns FALSE if the traversal is not yet completed. Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal (that is, an object report was constructed for each object, minus the special objects).

Description

GciClampedTrav initiates a traversal of the specified objects, subject to the clamps in the specified ClampSpecification. In order to guarantee that the root object of the traversal will always have an entry in the traversal buffer, the root object is not subject to the specified clamps. Refer to GciTraverseObjs for a detailed discussion of object traversal.

GemBuilder clamped traversal functions are used by the GemBuilder for Smalltalk implementation of object replication and are intended for similar sophisticated client applications.

See Also

GciMoreTraversal
GciSaveObjs

GciClassMethodForClass

Compile a class method for a class.

Syntax

OopType GciClassMethodForClass(
OopType source,
OopType aClass,
OopType category,
OopType symbolList );

Arguments

source

The OOP of a Smalltalk string to be compiled as a class method.

aClass

The OOP of the class with which the method is to be associated.

category

The OOP of a Smalltalk string, which contains the name of the category to which the method is added. If the category is nil (OOP_NIL), the compiler adds this method to the category “(as yet unclassified)”.

symbolList

The OOP of a GemStone symbol list, or OOP_NIL. Smalltalk resolves symbolic references in source code by using symbols that are available from symbolList. A value of OOP_NIL means to use the default symbol list for the current GemStone session (System myUserProfile symbolList).

Return Value

Returns OOP_NIL, unless there were compiler warnings (such as variables declared but not used, etc.), in which case the return will be the OOP of a string containing the warning messages.

Description

This function compiles a class method for the given class. You may not compile any method whose selector begins with an underscore (_) character. Such selectors are reserved for use by the GemStone development team as private methods.

In addition, the Smalltalk virtual machine optimizes a small number of selectors. You may not compile any methods with any of those selectors. See the Programming Guide for a list of the optimized selectors.

To remove a class method, use GciExecuteStr to execute Smalltalk code in GemStone, or GciClassRemoveAllMethods to remove all methods.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

void GciClassMethodForClass_example(void)
{
  // Assumes the setup code has been executed.
 
  OopType theClass = GciResolveSymbol("Customer", OOP_NIL);
  OopType oCateg = GciNewString("instance creation");
  OopType oMethodSrc = GciNewString( 
      "newNamed: aName address: anAddress.  
      | n | n := self new. n name: aName. n address: anAddress. ^ n"); 
 
  GciClassMethodForClass(oMethodSrc, theClass, oCateg, OOP_NIL); 
  GciErrSType errInfo;
  if (GciErr(&errInfo)) {
    printf("error category "FMT_OID" number %d, %s\n",
       errInfo.category, errInfo.number, errInfo.message);
  }
}

See Also

GciCompileMethod
GciInstMethodForClass

GciClassNamedSize

Find the number of named instance variables in a class.

Syntax

int GciClassNamedSize(
OopType aClass );

Arguments

aClass

The OOP of the class from which to obtain information about instance variables. For reserved OOPs for Smalltalk kernel classes, see $GEMSTONE/include/gcioop.ht.

Return Value

Returns the number of named instance variables in the class, or zero if an error occurs.

Description

This function returns the number of named instance variables for the specified class, including those inherited from superclasses.

Example

int namedSizeExample(void)
{
  // find the class named Employee in the current symbolList
  OopType empClass = GciResolveSymbol("Employee", OOP_NIL);
  if (empClass == OOP_NIL) {
    return -1;  // class not found or other error.
  }
 
  int numIvs = GciClassNamedSize(empClass);
  GciErrSType errInfo;
  if (GciErr(&errInfo)) {
    return -1; // error occurred
  }
 
  // return the number of named instance variables which will
  // be >= 0
  return numIvs;
}
 

See Also

GciIvNameToIdx

GciClassRemoveAllMethods

GciClassRemoveAllMethods_

Remove all methods from the method dictionary of a class.

Syntax

void GciClassRemoveAllMethods(
OopType aClass);

void GciClassRemoveAllMethods_(
OopType aClass,
ushort environmentId );

Arguments

aClass

The OOP of the class from which to remove the methods.

environmentId

The compilation environment from which to remove methods.

Description

GciClassRemoveAllMethods removes all methods from the method dictionary of the specified class, within environment 0, the default Smalltalk environment. To remove methods in other environments, use GciClassRemoveAllMethods_.

To remove an individual method, use GciExecuteStr to execute Smalltalk code in GemStone.

GciClearStack

Clear the Smalltalk call stack.

Syntax

void GciClearStack(
OopType gsProcess );

Arguments

gsProcess   

The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr).

Description

Whenever a session executes a Smalltalk expression or sequence of expressions, the virtual machine creates and maintains a call stack that provides information about its state of execution. The call stack includes an ordered list of activation records related to the methods and blocks that are currently being executed.

If a soft break or an unexpected error occurs, the virtual machine suspends execution, creates a GsProcess object, and raises an error. The GsProcess object represents both the call stack when execution was suspended and any information that the virtual machine needs to resume execution. If there was no fatal error, your program can call GciContinue to resume execution. Call GciClearStack instead if there was a fatal error, or if you do not want your program to resume the suspended execution.

Example

The following example shows how an application can handle an error and either continue or terminate Smalltalk execution.

void clearStackExample(void)
{
  OopType result = GciExecuteStr(
    	"| a | a := 10 + 10. nil halt .  ^ a + 100",
    	OOP_NIL/*use default symbolList for execution*/);
 
  // halt method is expected to generate error number RT_ERR_GENERIC_ERROR
  GciErrSType errInfo;
  if (! GciErr(&errInfo)) {
    printf("expected an error but none found\n");
    return;
  }
  if (errInfo.number == ERR_Halt) {
    // now continue the execution to finish the computation
    result = GciContinue(errInfo.context);
  } else {
         		// FMT_OID format string is defined in gci.ht 
    printf("unexpected error category "FMT_OID" number %d, %s\n",
	   errInfo.category, errInfo.number, errInfo.message);
    // terminate the execution
    GciClearStack(errInfo.context);
    return;
  }
  int val = GciOopToI32(result);
  if (GciErr(&errInfo)) {
    printf("unexpected error category "FMT_OID" number %d, %s\n",
	   errInfo.category, errInfo.number, errInfo.message);
  } else {
    if (val != 120) {
      printf("Wrong answer = %d\n", val);
    } else {
      printf("result = %d\n", val);
    }
  }
}
  
 

See Also

GciContinue
GciSoftBreak

GciCommit

Write the current transaction to the database.

Syntax

BoolType GciCommit( )

Return Value

Returns TRUE if the transaction committed successfully. Returns FALSE if the transaction fails to commit due to a concurrency conflict or in case of error.

Description

The GciCommit function attempts to commit the current transaction to the GemStone database.

GciCommit ignores any commit pending action that may be defined in the current GemStone session state.

Example

void GciCommit_example(void)
{
  // Call GciCommit and see if there was an error 
  if ( ! GciCommit()) {
    GciErrSType errInfo;
    if (GciErr(&errInfo)) {
      printf("commit failed with error %d , %s \n",
    	 	errInfo.number, errInfo.message );
    } else {
      printf("commit failed due to transaction conflicts\n");
    }
  }
}
 

See Also

GciAbort
GciBegin
GciNbCommit

GciCompileMethod

Compile a method.

Syntax

OopType GciCompileMethod(
OopType source,
OopType aClass,
OopType category,
OopType symbolList,
OopType overrideSelector,
int compileFlags,
ushort environmentId );

Arguments

source

The OOP of a Smalltalk string to be compiled as a method.

aClass

The OOP of the class with which the method is to be associated.

category

The OOP of a Smalltalk string, which contains the name of the category to which the method is added. If the category is nil (OOP_NIL), the compiler adds this method to the category “(as yet unclassified)”.

symbolList

The OOP of a GemStone symbol list, or OOP_NIL. Smalltalk resolves symbolic references in source code by using symbols that are available from symbolList. A value of OOP_NIL means to use the default symbol list for the current GemStone session (System myUserProfile symbolList).

overrideSelector

If not OOP_NIL, this is a string that is converted to a symbol and used in precedence to the selector pattern in the method source when installing the method in the method dictionary. Sending 'selector' to the resulting method will also reflect the overrideSelector argument.

compileFlags

Compiler flags. GCI_COMPILE_CLASS_METH means compile a class method. These are listed in gcicmn.ht.

environmentId

The compilation environment for method lookup, normally 0.

Return Value

Returns OOP_NIL, unless there were compiler warnings (such as variables declared but not used, etc.), in which case the return will be the OOP of a string containing the warning messages.

Description

This function is used for compiling a method. Replaces both GciInstMethodForClass and GciClassMethodForClass, and adds the environmentId argument.

This function compiles a method for the given class. You may not compile any method whose selector begins with an underscore (_) character. Such selectors are reserved for use by the GemStone development team as private methods.

In addition, the Smalltalk virtual machine optimizes a small number of selectors. You may not compile any methods with any of those selectors. See the Programming Guide for a list of the optimized selectors.

To remove a method, use GciExecuteStr instead.

See Also

GciClassMethodForClass
GciInstMethodForClass

GciCompress

Compress the supplied data, which can be uncompressed with GciUncompress.

Syntax

int GciCompress(
char * dest,
uint * destLen,
const char * source,
uint sourceLen );

Arguments

dest   

Pointer to the buffer that will hold the resulting compressed data.

destLen

Length, in bytes, of the buffer intended to hold the compressed data.

source   

Pointer to the source data to compress.

sourceLen 

Length, in bytes, of the source data.

Return Value

GciCompress returns Z_OK (equal to 0) if the compression succeeded, or various error values if it failed; see the documentation for the compress function in the GNU zlib library at http://www.gzip.org.

Description

GciCompress passes the supplied inputs unchanged to the compress function in the GNU zlib library Version 1.2.3, and returns the result exactly as the GNU compress function returns it.

Example

#include <limits.h>
 
OopType compressByteArray(OopType byteArray)
{
  // given an input ByteArray , return a new ByteArray with
  // the contents of the input compressed .
 
  if (!GciIsKindOfClass(byteArray, OOP_CLASS_BYTE_ARRAY) )
     return OOP_NIL; /* error: input arg is not a ByteArray */
 
  int64 inputSize = GciFetchSize_(byteArray);
  if (inputSize > INT_MAX) {
    return OOP_NIL;  // GciCompress supports max 2G bytes input
  }
 
  int64 outputSize = inputSize;
 
  ByteType *inputBuffer  = (ByteType*)malloc( inputSize);
  if (inputBuffer == NULL) {
    return OOP_NIL; // malloc failure
  }
  ByteType *outputBuffer = (ByteType*)malloc( outputSize);
  if (outputBuffer == NULL) {
    free(inputBuffer);
    return OOP_NIL; // malloc failure
  }
 
  OopType resultOop = OOP_NIL;
 
  int64 numRet = GciFetchBytes_(byteArray, 1/* start at first element */,
	  inputBuffer, inputSize /* max bytes to fetch */ );
  if (numRet == inputSize) {
    uint compressedSize;
    int status = GciCompress( (char *)outputBuffer,
	    		&compressedSize, 
	    	     (char *) inputBuffer, inputSize);
    if (status == 0) {
      // compress ok 
      resultOop =  GciNewByteObj(OOP_CLASS_BYTE_ARRAY,
			outputBuffer, (int64)compressedSize );
    } else {
      // compress failed
    }
  } else {
    // error during FetchBytes
  }
  free(inputBuffer);
  free(outputBuffer);
  return resultOop;
}
 

See Also

GciUncompress

GciCompressUsingLz4

Compress the supplied data, which can be uncompressed with GciUncompressUsingLz4.

Syntax

int GciCompressUsingLz4(
const char * source,
char * dest,
int sourceLen,
int destLen
);

Arguments

dest   

Pointer to the buffer that will hold the resulting compressed data.

destLen

Length, in bytes, of the buffer intended to hold the compressed data.

source   

Pointer to the source data to compress.

sourceLen 

Length, in bytes, of the source data.

Return Value

If the function cannot compress source into a the size specified by destLen, compression stops, function result is zero, and dest content is undefined (invalid).

Description

GciCompressUsingLz4 is a wrapper for the lz4 function LZ4_compress_default(). Compresses souceLen bytes from buffer souce into already allocated dest buffer of size destLen. Compression is faster, and guaranteed to succeed, if destLen >= LZ4_compressBound(sourceLen).

See Also

GciUncompress

 

GciContinue

Continue code execution in GemStone after an error.

Syntax

OopType GciContinue(
OopType gsProcess );

Arguments

gsProcess

The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr).

Return Value

Returns the OOP of the result of the Smalltalk code that was executed. Returns OOP_NIL in case of error.

Description

The GciContinue function attempts to continue Smalltalk execution sometime after it was suspended. It is most useful for proceeding after GemStone encounters a pause message, a soft break (GciSoftBreak), or an application-defined error, since continuation is always possible after these events. Because GciContinue calls the virtual machine, the application user can also issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.

It may also be possible to continue Smalltalk execution if the virtual machine detects a nonfatal error during a GciExecute... or GciPerform call. You may then want to use structural access functions to investigate (or modify) the state of the database before you call GciContinue.

Example

See the example for GciClearStack.

See Also

GciClearStack
GciContinueWith
GciErr
GciNbContinue
GciSoftBreak

GciContinueWith

Continue code execution in GemStone after an error.

Syntax

OopType GciContinueWith (
OopType gsProcess,
OopType replaceTopOfStack,
int flags,
GciErrSType * continueWithError );

Arguments

gsProcess

The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr).

replaceTopOfStack

f not OOP_ILLEGAL, replace the value at the top of the Smalltalk evaluation stack with this value before continuing. If OOP_ILLEGAL, the evaluation stack is not changed.

flags

Flags to disable or permit asynchronous events and debugging in Smalltalk, as defined for GciPerformNoDebug.

continueWithError

If not NULL, continue execution by signalling this error. This argument takes precedence over replaceTopOfStack.

Return Value

Returns the OOP of the result of the Smalltalk code that was executed. In case of error, this function returns OOP_NIL.

Description

This function is a variant of the GciContinue function, except that it allows you to modify the call stack and the state of the database before attempting to continue the suspended Smalltalk execution. This feature is typically used while implementing a Smalltalk debugger.

See Also

GciClearStack
GciContinue
GciErr
GciNbContinueWith
GciSoftBreak

GciCreateByteObj

Create a new byte-format object.

Syntax

OopType GciCreateByteObj(
OopType aClass,
OopType objId,
const ByteType * values,
int64 numValues,
int clusterId,
BoolType makePermanent );

Arguments

aClass   

The OOP of the class of the new object.

objId

The new object’s OOP (obtained from GciGetFreeOop), or OOP_ILLEGAL.

If you are trying to create a Symbol or DoubleByteSymbol, objId must be OOP_ILLEGAL. You cannot use the result of GciGetFreeOop to create a type of Symbol object.

values   

Array of instance variable values.

numValues

Number of elements in values.

clusterId   

ID of the cluster bucket in which to place the object. If clusterId is 0, use the cluster bucket (System currentClusterId). Otherwise, clusterId must be a positive integer <= GciFetchSize_(OOP_ALL_CLUSTER_BUCKETS).

makePermanent

Has no effect.

Return Value

GciCreateByteObj returns the OOP of the object it creates. The return value is the same as objId unless that value is OOP_ILLEGAL, in which case GciCreateByteObj assigns and returns a new OOP itself.

Description

Creates a new object using an object identifier (OOP) objId previously obtained from GciGetFreeOop or GciGetFreeOops. For more about the semantics of such object identifiers, see GciGetFreeOop.

The object is created in temporary object space, and the garbage collector makes it permanent if the object is referenced, or becomes referenced, by another permanent object.

Values are stored into the object starting at the first named instance variable (if any) and continuing to the indexable (or NSC) instance variables if oclass is indexable or NSC. The caller must initialize any unused elements of *values to OOP_NIL.

If oclass is an indexable or NSC class, then numValues may be as large or as small as desired. If oclass is neither indexable nor NSC, numValues must not exceed the number of named instance variables in the class. If numValues is less than number of named instance variables, then the size of the newly-created object is the number of named instance variables and any instance variables beyond numValues are initialized to OOP_NIL.

For certain classes of byte format, namely DateTime, Float, and LargeInteger, additional size restrictions apply.

For an indexable object, if numValues is greater than zero and values is NULL, then the object is created of size numValues, and is initialized to logical size numValues. (This is equivalent to new: aSize for classes Array or String.)

If GciCreateByteObj is being used to create an instance of OOP_CLASS_FLOAT or OOP_CLASS_SMALL_FLOAT, then the correct number of value bytes must be supplied at the time of creation.

If you are trying to create a Symbol or DoubleByteSymbol, objId must be OOP_ILLEGAL.

See Also

GciCreateOopObj
GciGetFreeOop
GciGetFreeOops

GciCreateOopObj

Create a new pointer-format object.

Syntax

OopType GciCreateOopObj(
OopType aClass,
OopType objId,
const OopType * values,
int numValues,
int clusterId,
BoolType makePermanent );

Arguments

aClass   

The OOP of the class of the new object.

objId

The new object’s OOP (obtained from GciGetFreeOop), or OOP_ILLEGAL.

values   

Array of instance variable values.

numValues

Number of elements in values.

clusterId   

ID of the cluster bucket in which to place the object. If clusterId is 0, use the cluster bucket (System currentClusterId). Otherwise, clusterId must be a positive integer <= GciFetchSize_(OOP_ALL_CLUSTER_BUCKETS).

makePermanent

Has no effect.

Return Value

GciCreateOopObj returns the OOP of the object it creates. The return value is the same as objId unless that value is OOP_ILLEGAL, in which case GciCreateOopObj assigns and returns a new OOP itself.

Description

Creates a new object using an object identifier (objId) previously obtained from GciGetFreeOop or GciGetFreeOops. For more about the semantics of such object identifiers, see GciGetFreeOop.

The object is created in temporary object space, and the garbage collector makes it permanent if the object is referenced, or becomes referenced, by another permanent object.

Values are stored into the object starting at the first named instance variable (if any) and continuing to the indexable (or NSC) instance variables if oclass is indexable or NSC. Values may be forward references to objects whose identifier has been allocated with GciGetFreeOop, but for which the object has not yet been created with GciCreate.... The caller must initialize any unused elements of *values to OOP_NIL.

Because it is illegal to create a forward reference to a Symbol, any GciCreate... call that creates a Symbol will fail if the client’s objId of the created object was already used as a forward reference.

If oclass is an indexable or NSC class, then numValues may be as large or as small as desired. If oclass is neither indexable nor NSC, numValues must not exceed the number of named instance variables in the class. If numValues is less than number of named instance variables, then the size of the newly-created object is the number of named instance variables and any instance variables beyond numValues are initialized to OOP_NIL.

For an indexable object, if numValues is greater than zero and values is NULL, then the object is created of size numValues, and is initialized to logical size numValues. (This is equivalent to new: aSize for classes Array or String.)

See Also

GciCreateByteObj
GciGetFreeOop
GciGetFreeOops

GciCTimeToDateTime

Convert a C date-time representation to the equivalent GemStone representation.

Syntax

BoolType GciCTimeToDateTime(
time_t arg,
GciDateTimeSType * result );

Arguments

arg   

The C time value to be converted.

result   

A pointer to the C struct for the converted value.

Return Value

Returns TRUE if the conversion succeeds; otherwise returns FALSE.

Description

Converts a time_t value to GciDateTimeSType. On systems where time_t is a signed value, GciCTimeToDateTime generates an error if arg is negative.

See Also

GciDateTimeToCTime

GciDateTimeToCTime

Convert a GemStone date-time representation to the equivalent C representation.

Syntax

time_t GciDateTimeToCTime(
const GciDateTimeSType * arg );

Arguments

arg   

An instance of GciDateTimeSType to be converted.

Return Value

A C time value of type time_t.

Description

Converts an instance of GciDateTimeSType to the equivalent time_t value.

See Also

GciCTimeToDateTime

GciDbgEstablish

Specify the debugging function for GemBuilder to execute before most calls to GemBuilder functions.

Syntax

GciDbgFuncType * GciDbgEstablish(
GciDbgFuncType * newDebugFunc );

Arguments

newDebugFunc 

A pointer to a C function that will be called before each subsequent GemBuilder call. Note that this function will not be called before any of the following GemBuilder functions or macros: GCI_ALIGN, GCI_BOOL_TO_OOP, GCI_CHR_TO_OOP, GciErr, or this function.

Return Value

Returns a pointer to the newDebugFunc specified in the previous GciDbgEstablish call (if any).

Description

This function establishes the name of a C function (most likely a debugging routine) to be called before your program calls any GemBuilder function or macro (except those named above). Before each GemBuilder call, a single argument, a null-terminated string that names the GemBuilder function about to be executed, is passed to the specified newDebugFunc.

The newDebugFunc function is passed a single null-terminated string argument, (of type const char []), the name of the GemBuilder function about to be called.

To disable previous debugging routines, call GciDbgEstablish with an argument of NULL.

Example

void traceGciFunct(const char* gciFname)
{
  printf("trace gci call %s \n", gciFname);
}
 
void debugEstablishExample(void)
{
  GciDbgEstablish(traceGciFunct); // enable tracing
  GciFetchSize_(OOP_CLASS_STRING);  // this call will be traced
    GciDbgEstablish(NULL);  // shut off tracing
}

See Also

GciDbgEstablishToFile
GciDbgLogString

GciDbgEstablishToFile

GciDbgEstablishToFile_

Write trace information for most GemBuilder functions to a file.

Syntax

BoolType GciDbgEstablishToFile(
const char * fileName );

BoolType GciDbgEstablishToFile_(
const char * fileName ,
GciErrSType *err);

 

Arguments

fileName  

The file to which trace information is to be written.

Return Value

Returns TRUE if the file operation was successful.

Description

This function causes trace information for most GemBuilder functions to be written to a file. If the file already exists, it is opened in append mode. If fileName is NULL and tracing to a file is not currently active, trace information will be written to stdout.

The GciDbgEstablishToFile_ variant returns error information in *err if the function result is FALSE.

Calling GciDbgEstablishToFile supersedes the effect of any previous calls to GciDbgEstablish or GciDbgEstablishToFile.

To terminate tracing to an active file, call GciDbgEstablishToFile with an argument of NULL; alternatively, a call GciShutdown also teminates tracing.

For details about the trace information generated, see GciDbgEstablish.

See Also

GciDbgEstablish
GciDbgLogString

GciDbgLogString

Pass a message to a trace function.

Syntax

void GciDbgLogString(
const char * message);

Arguments

message

A message to be passed to GciDbgEstablish or GciDbgEstablishToFile.

Description

If either GciDbgEstablish or GciDbgEstablishToFile has been called to activate tracing of GemBuilder calls, this function passes the argument to the trace function.

If tracing is not active, this function has no effect.

See Also

GciDbgEstablish
GciDbgEstablishToFile

GciDebugConnectToGem

Initiate the connection to another session for debugging.

Syntax

void GciDebugConnectToGem(
int gemPid);

Arguments

gemPid

The ProcessId of a Gem that is listening for debug, by a setting for GEM_LISTEN_FOR_DEBUG or a call to System class >> listenForDebugConnection.

Description

Connect to a previous open listening debug port for a Gem that is running on localhost. For more information, see the configuration parameter GEM_LISTEN_FOR_DEBUG, and the topaz DEBUGGEM command.

The call to GciDebugConnectToGem must be followed by a call to GciDebugStartDebugService to complete the connection.

See Also

GciDebugStartDebugService

GciDebugStartDebugService

Connect to another session for debugging.

Syntax

void GciDebugStartDebugService(
uint64 debugToken);

Arguments

debugToken

The token returned by a revious call to GciDebugConnectToGem.

Description

Must be preceeded by GciDebugConnectToGem() which creates a GCI session.

Using a Gci session created by GciDebugConnectToGem, GciDebugStartGemThread will validate the debugToken argument and interrupt any Smalltalk execution in progress in the target gem by the equivalent of GciSoftBreak.

To continue an execution that was interrupted by this SoftBreak and release the target gem to continue running, execute GciNbContinue followed by GciLogout_(FALSE);

See Also

GciDebugConnectToGem
GciNbContinue
GciLogout

 

GciDeclareAction

Associate a C function with a Smalltalk user action.

Syntax

void GciDeclareAction(
const char* name,
void* func,
int nunArgs,
uint flags,
BoolType errorIfDuplicate );

Arguments

name   

The user action name (a case-insensitive, null-terminated string).

func   

A pointer to the C user action function.

numArgs   

The number of arguments in the C function.

flags   

Flags that apply to the declaration: intended for internal use.

errorIfDuplicate   

If True, return an error if there is already a user action with the specified name. If False, leave the existing user action in place and ignore the current call.

Description

This function associates a user action name (declared in Smalltalk) with a user-written C function. GciDeclareAction allows you to declare a user action by passing each field of the user action structure to the function as a separate argument. Because the user action structure is encapsulated within the function itself, there’s no need to explicitly allocate and free memory, as is required with GciInstallUserAction (which uses the data structure defined by GciUserActionSType).

Example

To declare a user action funtion doConvert with one argument:

GciDeclareAction("doConvert", (void*)doConvert, 1, 0, TRUE);

See Also

Chapter 4, “Writing User Actions”
User Action Information Structure - GciUserActionSType
GCI_DECLARE_ACTION
GciInstallUserAction
GciInUserAction
GciUserActionInit
GciUserActionShutdown

GCI_DECLARE_ACTION

(MACRO) Associate a C function with a Smalltalk user action.

Syntax

void GCI_DECLARE_ACTION(
const char* name,
void* func,
int nunArgs,
);

Arguments

name   

The user action name (a case-insensitive, null-terminated string).

func   

A pointer to the C user action function.

numArgs   

The number of arguments in the C function.

Description

This function associates a user action name (declared in Smalltalk) with a user-written C function. GCI_DECLARE_ACTION allows you to declare a user action by passing each field of the user action structure to the function as a separate argument. Because the user action structure is encapsulated within the function itself, there’s no need to explicitly allocate and free memory, as is required with GciInstallUserAction (which uses the data structure defined by GciUserActionSType).

Example

To declare a user action funtion doConvert with one argument:

GCI_DECLARE_ACTION("doConvert", doConvert, 1);

See Also

Chapter 4, “Writing User Actions”
User Action Information Structure - GciUserActionSType
GciDeclareAction
GciInstallUserAction
GciInUserAction
GciUserActionInit
GciUserActionShutdown

GciDecodeOopArray

Decode an OOP array that was previously run-length encoded.

Syntax

int GciDecodeOopArray(
OopType * encodedOopArray,
const int numEncodedOops,
OopType * decodedOopArrray,
const int decodedOopsSize);

Arguments

encodedOopArray

An OOP array that was encoded by a call to GciEncodeOopArray.

numEncodedOops

The number of OOPs in encodedOopArray.

decodedOopArray

The decoded OOP array that had been run-length encoded.

decodedOopsSize 

The maximum number of OOPs in decodedOopArray.

Return Value

Returns the number of OOPs placed in decodedOopArray.

Description

This function decodes the OOPs in encodedOopArray that were run-length encoded using GciEncodeOopArray and places the result in decodedOopArray.

The decodedOopArraySize must be large enough to hold all decoded OOPs. If it is not, no decode is performed and *decodedOopArraySize is set to -1.

See Also

GciFetchNumEncodedOops
GciEncodeOopArray
GciGetFreeOopsEncoded

GciDecSharedCounter

Decrement the value of a shared counter.

Syntax

BoolType GciDecSharedCounter(
int64_t counterIdx,
int64_t * value,
int64_t * floor);

Arguments

counterIdx

The offset into the shared counters array of the value to decrement.

value

Pointer to a value that indicates how much to decrement the shared counter by. On return, the new value of the shared counter after the decrement.

floor   

The minimum possible value for the shared counter. The counter cannot be decremented below this value. If floor is NULL, then a floor value of INT_MIN -2147483647) will be used.

Return Value

Returns a C Boolean value indicating if the shared counter was successfully decremented by the given amount. Returns TRUE if successful, FALSE if an error occurred.

Description

This function decrements the value of a particular shared counter by a specified amount. The shared counter is specified by index. The value of this shared counter cannot be decremented to a value lower than floor.

This function is not supported for remote GCI interfaces, and will always return FALSE.

See Also

GciFetchNumSharedCounters
GciIncSharedCounter
GciSetSharedCounter
GciReadSharedCounter
GciReadSharedCounterNoLock
GciFetchSharedCounterValuesNoLock

GciDirtyExportedObjs

Find all objects in the ExportedDirtyObjs set.

Syntax

BoolType GciDirtyExportedObjs(
OopType theOops[ ],
int * numOops );

Arguments

theOops 

An array to hold the dirty exported objects.

numOops

The maximum number of objects that can be put into theOops buffer. On return, the number of dirty exported objects found.

Return Value

This function returns a C Boolean value indicating whether or not the complete set of dirty objects has been returned in theOops in one or more calls. TRUE indicates that the complete set has been returned, and FALSE indicates that it has not.

Description

This function returns a list of all objects that are in the ExportedDirtyObjs set, which includes all objects in the PureExportSet that have been made “dirty” since the ExportedDirtyObjs set was last initialized or retrieved using any of the following:

GciDirtyAlteredObjs
GciDirtyExportedObjs
GciDirtyObjsInit
GciDirtySaveObjs

Object are added to the PureExportSet using GciSaveObjs or by other functions that invoke GciSaveObjs.

An object is considered dirty (changed) under one or more of the following conditions:

  • The object was changed by Smalltalk execution from this session.
  • The object was changed by a call from this session to any GemBuilder function from within a user action.
  • The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
  • The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
  • The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.

Calls to GciStore... (other than GciStorePaths), GciAppend..., GciReplace..., and GciCreate... do not put the modified object into the set of dirty objects (unless the call is from within a user action). The assumption is that the client does not want the dirty set to include modifications that the client has explicitly made.

The function GciDirtyObjsInit must be executed once after GciLogin before this function can be called, because it depends upon GemStone’s set of dirty objects.

The user is expected to call this function repeatedly while it returns FALSE, until it finally returns TRUE. When this function returns TRUE, it first clears the set of dirty objects.

Note that GciDirtyExportedObjs removes OOPs from the ExportedDirtyObjs set as they are enumerated.

See Also

Garbage Collection
GciDirtyExportedObjs
GciDirtyObjsInit
GciDirtySaveObjs
Gci_doubleToSmallDouble
GciSaveGlobalObjs
GciTraverseObjs

GciDirtyObjsInit

Begin tracking which objects in the session workspace change.

Syntax

void GciDirtyObjsInit( )

Description

GemStone can track which objects in a session change, but doing so has a measurable cost. By default, GemStone does not do it. The GciDirtyObjsInit function permits an application to request GemStone to maintain that set of dirty objects, the ExportedDirtyObjects, when it is needed. Once initialized, GemStone tracks dirty objects until GciLogout is executed.

GciDirtyObjsInit must be called once after GciLogin before GciDirtyExportedObjs, or GciDirtySaveObjs in order for those functions to operate properly, because they depend upon GemStone’s set of dirty objects.

An object is considered dirty (changed) under one or more of the following conditions:

  • The object was changed by Smalltalk execution from this session.
  • The object was changed by a call from this session to any GemBuilder function from within a user action.
  • The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
  • The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
  • The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.

See Also

GciDirtyExportedObjs
GciDirtySaveObjs
GciTraverseObjs

GciDirtySaveObjs

Find all exported objects that have changed and are therefore in the ExportedDirtyObjs set.

Syntax

BoolType GciDirtySaveObjs(
OopType theOops[ ],
int * numOops );

Arguments

theOops 

An array to hold the dirty cached objects.

numOops 

The maximum number of objects that can be put into theOops buffer. On return, the number of dirty cached objects found

Return Value

This function returns a C Boolean value indicating whether or not the complete set of dirty objects has been returned in theOops in one or more calls. TRUE indicates that the complete set has been returned, and FALSE indicates that it has not.

Description

This function finds all objects that are in the ExportedDirtyObjs set. The ExportedDirtyObjs set includes all objects in PureExportSet that have been made “dirty” since the ExportedDirtyObjs set was last reset.

The ExportedDirtyObjs set is initialized by GciDirtyObjsInit.

The ExportedDirtyObjs set is cleared by calls to GciDirtyAlteredObjs, GciDirtyExportedObjs, or GciDirtySaveObjs (this function).

An object is considered dirty (changed) under one or more of the following conditions:

  • The object was changed by Smalltalk execution from this session.
  • The object was changed by a call from this session to any GemBuilder function from within a user action.
  • The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
  • The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
  • The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.

Calls to GciStore... (other than GciStorePaths), GciAppend..., GciReplace..., and GciCreate... do not put the modified object into the set of dirty objects (unless the call is from within a user action). The assumption is that the client does not want the dirty set to include modifications that the client has explicitly made.

GciDirtyObjsInit must be called once after GciLogin before GciDirtySaveObjs can be executed, because it depends upon GemStone’s set of dirty objects.

The user is expected to call GciDirtySaveObjs repeatedly while it returns FALSE, until it finally returns TRUE. When GciDirtySaveObjs returns TRUE, it first clears the set of dirty objects.

For details about the PureExportSet, see GciSaveObjs.

Note that GciDirtySaveObjs removes OOPs from the ExportedDirtyObjs set.

See Also

Garbage Collection
GciDirtyExportedObjs
GciDirtyObjsInit
Gci_doubleToSmallDouble
GciTraverseObjs
GciSaveObjs

Gci_doubleToSmallDouble

Convert a C double to a SmallDouble object.

Syntax

OopType Gci_doubleToSmallDouble(
double aDouble );

Arguments

aDouble  

A C double value

Return Value

Returns the OOP of the GemStone SmallDouble object that corresponds to the C value. If the C value is not representable as a GemStone SmallDouble, return OOP_ILLEGAL.

Description

This function translates a C double into the equivalent GemStone SmallDouble object.

See Also

GciFltToOop

GciEnableFreeOopEncoding

Enable encoding of free OOPs sent between the client and the RPC Gem.

Syntax

void GciEnableFreeOopEncoding( )

Description

This function enables run-length encoding of free OOPs sent between the Gem and the GemBuilder client.

This function increases CPU consumption on both the client and the Gem, and decreases the number of bytes passed on the network.

GciEnableFullCompression

Enable full compression between the client and the RPC version of GemBuilder.

Syntax

void GciEnableFullCompression( )

Description

This function enables full compression (in both directions) between the client and GciRpc (the “remote procedure call” version of GemBuilder). This function has no effect for linked sessions.

GciEnableSignaledErrors

Establish or remove GemBuilder visibility to signaled errors from GemStone.

Syntax

BoolType GciEnableSignaledErrors(
BoolType newState );

Arguments

newState 

The new state of signaled error visibility: TRUE for visible.

Return Value

This function returns TRUE if signaled errors are already visible when it is called.

Description

GemStone permits selective response to signal errors: RT_ERR_SIGNAL_ABORT, RT_ERR_SIGNAL_COMMIT, and RT_ERR_SIGNAL_GEMSTONE_SESSION. The default condition is to leave them all invisible. GemStone responds to each single kind of signal error only after an associated method of class System has been executed: enableSignaledAbortError, enableSignaledObjectsError, and enableSignaledGemStoneSessionError respectively.

After GciInit executes successfully, the GemBuilder default condition also leaves all signal errors invisible. The GciEnableSignaledErrors function permits GemBuilder to respond automatically to signal errors. However, GemStone must respond to each kind of error in order for GemBuilder to respond to it. Thus, if an application calls GciEnableSignaledErrors with newState equal to TRUE, then GemBuilder responds automatically to exactly the same kinds of signal errors as GemStone. If GemStone has not executed any of the appropriate System methods, then this call has no effect until it does.

When enabled, GemBuilder checks for signal errors at the start of each function that accesses the database. It treats any that it finds just like any other errors, through GciErr or the GciLongJmp mechanism, as appropriate.

Automatic checking for signalled errors incurs no extra runtime cost. The check is optimized into the check for a valid session. However, instead of checking automatically, these errors can be polled by calling the GciPollForSignal function.

GciEnableSignaledErrors may be called before calling GciLogin.

See Also

GciErr
GciPollForSignal

GciEncodeOopArray

Encode an array of OOPs, using run-length encoding.

Syntax

int GciEncodeOopArray(
OopType * oopArray,
const int numOops,
OopType * encodedOopArray,
BoolType needsSorting );

Arguments

oopArray   

An OOP array to be encoded.

numOops   

The number of OOPs in oopArray.

encodedOopArray

The encoded OOP array.

needsSorting 

If oopArray is known to be in ascending order, set this to FALSE; otherwise set it to TRUE.

Return Value

Returns the number of elements in the encoded array. Returns -1 indicating an error if the input array was found to be out of sequence and needsSorting was set to FALSE.

Description

This function encodes the OOPs in oopArray using run-length encoding and places the result in encodedOopArray. Both oopArray and encodedOopArray must have the size numOops.

See Also

GciDecodeOopArray
GciFetchNumEncodedOops
GciGetFreeOopsEncoded

GciEncrypt

Encrypt a password string.

Syntax

char * GciEncrypt(
const char* password,
char outBuff[],
unsigned int outBuffSize);

Arguments

password

String containing a password.

outBuff  

Array in which to put the encrypted password.

outBuffSize

The maximum number of bytes to place in outBuff.

Return Value

Returns a pointer to the first character of the encrypted password in outBuff[], or NULL if the encrypted password is larger than outBuffSize.

Description

This function encrypts a host or GemStone password for use in GciSetNetEx or GciLogin with password encyrption enabled.

Example

BoolType login_encrypt_example(void)
{
   // assume the netldi been started with -a -g so that host 
   // userId and host password are not required.
   const char* stoneName    = "gs64stone";
   const char* gemService   = "gemnetobject";
   const char* gsUserName   = "DataCurator";
 
   // GciInit  required before first login
   if (!GciInit()) {
      printf("GciInit failed\n");
      return FALSE;
   }
   
   char outBuf[1024];
   char * gsPassword = GciEncrypt("swordfish", outBuf, 
       sizeof(outBuf));
   if ( gsPassword == NULL ) {
      printf("password encryption failed\n");
      return FALSE;
      }
 
   GciSetNet(stoneName, "", "", gemService);
   BoolType success = GciLoginEx(gsUserName, gsPassword, 
      GCI_LOGIN_PW_ENCRYPTED | GCI_LOGIN_QUIET, 0);
   if (! success) {
     GciErrSType errInfo;
     if (GciErr(&errInfo)) {
       printf("login encrypted password failed; error %d, %s\n",
         errInfo.number, errInfo.message);
      }
   }
  return success;
}

See Also

GciLoginEx
GciSetNetEx

GciErr

Prepare a report describing the most recent GemBuilder error.

Syntax

BoolType GciErr(
GciErrSType * errorReport );

Arguments

errorReport

Address of a GemBuilder error report structure.

Return Value

TRUE indicates that an error has occurred. The errorReport parameter has been modified to contain the latest error information, and the internal error buffer in GemBuilder has been cleared. You can only call GciErr once for a given error. If GciErr is called a second time, the function returns FALSE.

If the result is TRUE, all objects referenced from errorReport have been added to the PureExportSet, unless the error occurred during a GciStoreTravDoTravRefs_, in which case all objects referenced from errorReport have been added to the ReferencedSet rather than the PureExportSet.

FALSE indicates no error occurred, and the contents of errorReport are unchanged.

Description

Your application program can call GciErr to determine whether or not the previous GemBuilder function call resulted in an error. If an error has occurred, this function provides information about the error and about the state of the GemStone system. In the case of a fatal error, your connection to GemStone is lost, and the current session ID (from GciGetSessionId) is reset to GCI_INVALID_SESSION_ID.

The GciErr function is especially useful when error traps are disabled or are not present. See GciPopErrJump for information about using general-purpose error traps in GemBuilder. The section Error Report Structure - GciErrSType describes the C structure for error reports.

See Also

GciClearStack
GciContinue
GciErr
GciLongJmp
GciPopErrJump
GciPushErrJump
GciRaiseException
GciSetErrJump

GciExecute

Execute a Smalltalk expression contained in a GemStone String or Utf8 object.

Syntax

OopType GciExecute(
OopType source,
OopType symbolList );

Arguments

source

The OOP of a String or Utf8 containing a sequence of one or more Smalltalk statements to be executed.

symbolList

The OOP of a GemStone symbol list. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.

Description

This function sends an expression (or sequence of expressions) to GemStone for execution. This is roughly equivalent to executing the body of a nameless procedure (method).

In most cases, you may find it more efficient to use GciExecuteStr. That function takes a C string as its argument, thus reducing the number of network round-trips required to execute the code. With GciExecute, you must first convert the source to a String or Utf8 object (see the following example.) If the source is already one of these kinds of object, however, GciExecute will be more efficient.

Because GciExecute calls the virtual machine, the user can issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.

Example

BoolType execute_example(void)
{
   OopType oString = GciNewString(" ^ 3 + 4 ");
   OopType result = GciExecute(oString, OOP_NIL);
   if (result == OOP_NIL) {
     printf("error from execution\n");
     return false;
   } 
  
   BoolType conversionErr = FALSE;
   int val = GciOopToI32_(result, &conversionErr);
   if (conversionErr) {
      printf("Error converting result to C int\n");
   } else {
      printf("result = %d\n", val);
   }
   return ! conversionErr;
}
 

See Also

GciExecuteFromContext
GciExecuteStr
GciExecuteStrFetchBytes
GciExecuteStrFromContext
GciNbExecute
GciPerform

GciExecuteFromContext

Execute a Smalltalk expression contained in a String or Utf8 object as if it were a message sent to another object.

Syntax

OopType GciExecuteFromContext(
OopType source,
OopType contextObject,
OopType symbolList );

Arguments

source

The OOP of a String or Utf8 containing a sequence of one or more Smalltalk statements to be executed.

contextObject

OOP_ILLEGAL, or the OOP of any GemStone object. The code to be executed is compiled as if it were a method in the class of contextObject. A value of OOP_ILLEGAL or OOP_NO_CONTEXT means no context.

symbolList

The OOP of a GemStone symbol list. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.

Description

This function sends an expression (or sequence of expressions) to GemStone for execution. The source is executed as though contextObject were the receiver. That is, the pseudo-variable self will have the value contextObject during the execution. Messages in the source are executed as defined for contextObject.

For example, if contextObject is an instance of Association, the source can reference the pseudo-variables key and value (referring to the instance variables of the Association contextObject). If any pool dictionaries were available to Association, the source could reference them too.

In most cases, you may find it more efficient to use GciExecuteStrFromContext. That function takes a C string as its argument, thus reducing the number of network round-trips required to execute the code. With GciExecuteFromContext, you must first convert the source to a String or Utf8 object. If the source is already one of these kinds of object, however, GciExecuteFromContext will be more efficient.

Because GciExecuteFromContext calls the virtual machine, the user can issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.

See Also

GciExecuteStr
GciExecuteStrFetchBytes
GciExecuteStrFromContext
GciNbExecuteFromContextDbg_
GciNbExecuteStrFromContext
GciPerform

GciExecuteStr

Execute a Smalltalk expression contained in a C string.

Syntax

OopType GciExecuteStr(
const char source[ ],
OopType symbolList );

Arguments

source

A null-terminated string containing a sequence of one or more Smalltalk statements to be executed.

symbolList

The OOP of a GemStone symbol list. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.

Description

This function sends an expression (or sequence of expressions) to GemStone for execution.

If the source is already a String object, you may find it more efficient to use GciExecute. That function takes the OOP of a String as its argument.

Because GciExecuteStr calls the virtual machine, the user can issue a soft break while this function is executing. For more information, see .Interrupting GemStone Execution.

Example

void executeStrExample(void)
{
  // get the symbolList for UserProfile named 'Newton'
  OopType symbolList = GciExecuteStr(
	"(AllUsers userWithId: 'Newton') symbolList", OOP_NIL);
 
  // get the value associated with key "#GciStructsMd5" in that
  // symbolList ; expected to be a kind of String 
  OopType keysum = GciExecuteStr("GciStructsMd5", symbolList);
  
  // fetch characters of the String
  char buf[1024];
  GciFetchChars_(keysum, 1, buf, sizeof(buf));  
 
  GciErrSType errInfo;
  if ( GciErr(&errInfo)) {
    			// FMT_OID format string is defined in gci.ht
    printf("unexpected error category "FMT_OID" number %d, %s\n",
      errInfo.category, errInfo.number, errInfo.message);
  } else {
    printf("#GciStructsMd5 is %s \n", buf);
  }
}
 

See Also

GciExecute
GciExecuteStrFetchBytes
GciExecuteStrFromContext
GciNbExecuteStr
GciPerform

GciExecuteStrFetchBytes

Execute a Smalltalk expression contained in a C string, returning byte-format results.

Syntax

int64 GciExecuteStrFetchBytes(
const char * source,
int64 sourceSize,
OopType sourceClass,
OopType contextObject,
OopType symbolList,
ByteType * result,
int64 maxResultSize );

Input

source

A null-terminated string containing a sequence of one or more Smalltalk statements to be executed.

sourceSize

The number of bytes in the source, or -1. If sourceSize is -1, strlen(source) is used.

sourceClass

The OOP of a class to use for the compilation target for the text in sourceStr, typically OOP_CLASS_STRING, OOP_CLASS_Utf8, or OOP_CLASS_Unicode7.

contextObject

OOP_ILLEGAL, or the OOP of any GemStone object. The code to be executed is compiled as if it were a method in the class of contextObject. A value of OOP_ILLEGAL or OOP_NO_CONTEXT means no context.

symbolList

The OOP of a GemStone symbol list. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

resultBuf

Array containing the bytes of the result of the execution.

maxResultSize

The maximum size of the resulting string.

Return Value

Returns the number of bytes returned in the result buffer, or -1 if an error occurred.

Description

This function sends an expression (or sequence of expressions) to GemStone for execution. The execution result, which should be a byte format object is returned in the *result buffer.

Execution is in environment 0 using GCI_PERFORM_FLAG_ENABLE_DEBUG .

See Also

GciExecute
GciExecuteStr
GciExecuteStrFromContext
GciNbExecuteStrFetchBytes
GciPerform

GciExecuteStrFromContext

Execute a Smalltalk expression contained in a C string as if it were a message sent to an object.

Syntax

OopType GciExecuteStrFromContext(
const char source[ ],
OopType contextObject,
OopType symbolList );

Arguments

sourceStr

A null-terminated string containing a sequence of one or more Smalltalk statements to be executed.

contextObject

The OOP of any GemStone object. The code to be executed is compiled as if it were a method in the class of contextObject. A value of OOP_ILLEGAL or OOP_NO_CONTEXT means no context.

symbolList

The OOP of a GemStone symbol list. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.

Description

This function sends an expression (or sequence of expressions) to GemStone for execution. The source is executed as though contextObject were the receiver. That is, the pseudo-variable self will have the value contextObject during the execution. Messages in the source are executed as defined for contextObject.

For example, if contextObject is an instance of Association, the source can reference the pseudo-variables key and value (referring to the instance variables of the Association contextObject). If any pool dictionaries were available to Association, the source could reference them too.

Because GciExecuteStrFromContext calls the virtual machine, the user can issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.

Example

void executeFromContextExample(void)
{
  // get the Assocation with key UserProfileSet  in dictionary Globals
  OopType oAssoc = GciExecuteStr("Globals associationAt: #UserProfileSet", 
					OOP_NIL);
 
  OopType oResult = GciExecuteStrFromContext(" ^ value ", oAssoc, OOP_NIL);
 
  if (oResult != OOP_CLASS_USERPROFILE_SET) {
    printf("unexpected result"FMT_OID" \n", oResult);
  }
}
 

See Also

GciExecute
GciExecuteStr
GciExecuteStrFetchBytes
GciNbExecuteStrFromContext
GciPerform

GciExecuteStrTrav

First execute a Smalltalk expression contained in a C string as if it were a message sent to an object, then traverse the result of the execution.

Syntax

BoolType GciExecuteStrTrav(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList,
GciClampedTravArgsSType * travArgs );

Arguments

sourceStr

A null-terminated string containing a sequence of one or more Smalltalk statements to be executed.

contextObject

OOP_ILLEGAL, or the OOP of any GemStone object. The code to be executed is compiled as if it were a method in the class of contextObject. A value of OOP_ILLEGAL or OOP_NO_CONTEXT means no context.

symbolList

The OOP of a GemStone symbol list. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

travArgs

Pointer to an instance of GciClampedTravArgsSType, as described under Clamped Traversal Arguments - GciClampedTravArgsSType.

On return, the instance of GciClampedTravArgsSType, with GciClampedTravArgsSType->travBuff filled.

The first element placed in the buffer is the actualBufferSize, an integer that indicates how many bytes were actually stored in the buffer by this function. The remainder of the traversal buffer consists of a series of object reports, each of which is of type GciObjRepSType.

Return Value

Returns FALSE if the traversal is not yet completed. You can then call GciMoreTraversal to proceed. Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal.

Description

This function is like GciPerformTrav, except that it first does a GciExecuteStr instead of a GciPerform.

See Also

GciExecute
GciExecuteStr
GciMoreTraversal
GciNbExecuteStrTrav
GciPerformTrav
GciPerformTraverse

GciFetchByte

Fetch one byte from an indexed byte object.

Syntax

ByteType GciFetchByte(
OopType theObject,
int64 atIndex );

Arguments

theObject

The OOP of the GemStone byte object.

atIndex 

The index into theObject of the element to be fetched. The index of the first element is 1.

Return Value

Returns the byte value at the specified index. In case of error, this function returns zero.

Description

This function fetches a single element from a byte object at the specified index, using structural access.

Example

void fetchByteExample(void)
{
  OopType oString = GciNewString("abc");
 
  ByteType theChar = GciFetchByte(oString, 2);
  if (theChar != 'b') {
    printf("unexpected result %d \n", theChar);
  }
}
 

See Also

GciFetchBytes_
GciFetchChars_
GciFetchOop
GciStoreByte

GciFetchBytes_

Fetch multiple bytes from an indexed byte object.

Syntax

int64 GciFetchBytes_(
OopType theObject,
int64 startIndex,
ByteType theBytes[ ],
int64 numBytes );

Arguments

theObject

The OOP of the GemStone byte object.

atIndex   

The index into theObject at which to begin fetching bytes. The index of the first element is 1. Note that if startIndex is 1 greater than the size of the object, this function returns a byte array of size 0, but no error is generated.

theBytes   

The array of fetched bytes.

numBytes

The maximum number of bytes to return.

Return Value

Returns the number of bytes fetched. (This may be less than numBytes, depending upon the size of theObject.) In case of error, this function returns zero.

Description

This function fetches multiple elements from a byte object starting at the specified index, using structural access. A common application of GciFetchBytes_ would be to fetch a text string.

GciFetchBytes_ permits theObject to be a byte object with multiple bytes per character or digit, such as DoubleByteString, Float and LargeInteger. In this case, GciFetchBytes_ provides automatic byte swizzling to client native byte order. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values. For MultiByteStrings, startIndex must be aligned on character boundaries and numbytes must be a multiple of the number of bytes per character; for numeric objects startindex must be one and numBytes the size of the numeric class.

Example

This example will print a GemStone String of arbitrarily large size, by repeatedly fetching fixed size buffers.

BoolType fetchBytes_example(OopType anObj)
{
   int BUF_SIZE =  5000;
   char buff[BUF_SIZE];
   BoolType done = FALSE;
   int idx = 1;
   GciErrSType err;
   while (! done) {
      int64 numRet = GciFetchBytes_(anObj, idx, (ByteType*)buff, BUF_SIZE - 1);
      if (numRet == 0) {
         done = TRUE;  // hit end of object or error
         if (GciErr(&err)) {
            printf("error %d, %s\n", err.number, err.message);
            return false;
         }
      } else {
         buff[numRet] = '\0';
         printf("%s\n", buff);
         idx += numRet;
      } 
   }
   return true;
}

See Also

GciFetchByte
GciFetchChars_
GciFetchOop
GciStoreBytes

GciFetchChars_

Fetch multiple ASCII characters from an indexed byte object.

Syntax

int64 GciFetchChars_(
OopType theObject,
int64 startIndex,
char * cString,
int64 maxSize );

Arguments

theObject

The OOP of an object containing ASCII characters.

startIndex

The index of the first character to retrieve.

cString

Pointer to the location in which to store the returned string.

maxSize

Maximum number of characters to fetch.

Return Value

Returns the number of characters fetched.

Description

Equivalent to GciFetchBytes_, except that it is assumed that theObject contains ASCII text. The bytes fetched are stored in memory starting at cString. At most maxSize - 1 bytes will be fetched from the object, and a \0 character will be stored in memory following the bytes fetched. The function returns the number of characters fetched, excluding the null terminator character, which is equivalent to strlen(cString) if the object does not contain any null characters. If an error occurs, the function result is 0, and the contents of cString are undefined.

See Also

GciFetchByte
GciFetchBytes_
GciStoreChars

GciFetchClass

Fetch the class of an object.

Syntax

OopType GciFetchClass(
OopType theObject );

Arguments

theObject

The OOP of the object.

Return Value

Returns the OOP of the object’s class. In case of error, this function returns OOP_NIL.

The GemBuilder include file $GEMSTONE/include/gcioop.ht defines a C constant for each of the Smalltalk kernel classes.

Description

The GciFetchClass function obtains the class of an object from GemStone. The GemBuilder session must be valid when GciFetchClass is called, unless theObject is an instance of one of the following classes: Boolean, Character, SmallInteger, SmallDouble, or UndefinedObject.

Example

#include <stdlib.h>
 
void fetchClassExample(void)
{
  // random double to Oop conversion producing a Float or SmallDouble
  double rand = drand48() * 1.0e38 ; 
  OopType oFltObj = GciFltToOop(rand); 
  
  OopType oClass = GciFetchClass(oFltObj);
  const char* kind;
  if (oClass == OOP_CLASS_SMALL_DOUBLE) {
    kind = "SmallDouble";
  } else if (oClass == OOP_CLASS_FLOAT) {
    kind = "Float";
  } else {
    kind = "Unexpected";
  }
  printf("result is a %s, class oop = "FMT_OID"\n", kind, oClass);
}  
 

See Also

GciFetchNamedSize
GciFetchObjImpl
GciFetchSize_
GciFetchVaryingSize_

GciFetchDateTime

Convert the contents of a DateTime object and place the results in a C structure.

Syntax

void GciFetchDateTime(
OopType datetimeObj,
GciDateTimeSType * result );

Arguments

datetimeObj

The OOP of the object to fetch.

result  

C pointer to the structure for the returned object.

Description

Fetches the contents of a DateTime object into the specified C result. Generates an error if datetimeObj is not an instance of DateTime. The value that result points to is undefined if an error occurs. For details on GciDateTimeSType, see GciDateTimeSType.

GciFetchDateAndTime

Convert the contents of a DateAndTime object and place the results in a C structure.

Syntax

BoolType GciFetchDateAndTime(
OopType dateAndTimeObj,
GciDateAndTime * result );

Arguments

dateAndTimeObj

The OOP of the object to fetch.

result  

C pointer to the structure for the returned object.

Description

Fetches the contents of a DateAndTime object into the specified C result. Generates an error if dateAndTimeObj is not an instance of DateAndTime. The value that result points to is undefined if an error occurs. For details on GciDateAndTime, see GciDateAndTime.

GciFetchDateAndTimePosix

Convert the contents of a DateAndTime object and place the results in a C structure.

Syntax

void GciFetchDateTimePosix(
OopType dateAndTimeObj,
GciPosixDateAndTime * result );

Arguments

dateAndTimeObj

The OOP of the object to fetch.

result  

C pointer to the structure for the returned object.

Description

Fetches the contents of a DateAndTime object into the specified C result. Generates an error if dateAndTimeObj is not an instance of DateAndTime. The value that result points to is undefined if an error occurs. For details on GciPosixDateAndTime, see GciPosixDateAndTime.

 

GciFetchDynamicIv

Fetch the OOP of one of an object’s dynamic instance variables.

Syntax

OopType GciFetchDynamicIv(
OopType theObject,
OopType aSymbol );

Arguments

theObject 

The OOP of the object.

aSymbol  

Specifies the dynamic instance variable to fetch.

Return Value

Returns the OOP of the specified dynamic instance variable. If no such dynamic instance variable exists in the object, this function returns OOP_NIL.

Description

This function fetches the contents of an object’s dynamic instance variable, as specified by aSymbol.

See Also

GciFetchDynamicIvs
GciStoreDynamicIv

GciFetchDynamicIvs

Fetches the OOPs of one or more of an object’s dynamic instance variables.

Syntax

int GciFetchDynamicIvs(
OopType theObject,
OopType * buf,
int numOops);

Arguments

theObject

The OOP of the object.

buf  

C pointer to the buffer that will contain the object’s dynamic instance variables.

numOops

The maximum number of elements to return.

Return Value

Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.)

Description

The number of dynamic instance variable pairs returned is (function result / 2). To obtain all dynamic instance variables in one call, use a buffer.

See Also

GciFetchDynamicIv
GciStoreDynamicIv

GciFetchNamedOop

Fetch the OOP of one of an object’s named instance variables.

Syntax

OopType GciFetchNamedOop(
OopType theObject,
int atIndex );

Arguments

theObject 

The OOP of the object.

atIndex  

The index into theObject’s named instance variables of the element to be fetched. The index of the first named instance variable is 1.

Return Value

Returns the OOP of the specified named instance variable. In case of error, this function returns OOP_NIL.

Description

This function fetches the contents of an object’s named instance variable at the specified index, using structural access.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

BoolType fetchNamedOop_example(OopType anAccount)
{
   // fetch anAccount's salesRep, hard coding offset
   int indexOfSalesRep = 3;
   OopType oName1 = GciFetchNamedOop(anAccount, indexOfSalesRep);
 
   // fetch anAccount's salesRep without hardcoding offset
   int ivOffset = GciIvNameToIdx(GciFetchClass(anAccount), "salesRep");
   OopType oName2 = GciFetchNamedOop(anAccount, ivOffset);
  
   return oName1 = oName2;
}

See Also

GciFetchNamedOops
GciFetchVaryingOop
GciIvNameToIdx
GciStoreNamedOop

GciFetchNamedOops

Fetch the OOPs of one or more of an object’s named instance variables.

Syntax

int GciFetchNamedOops(
OopType theObject,
int startIndex,
OopType theOops[ ],
int numOops );

Arguments

theObject

The OOP of the object.

startIndex

The index into theObject’s named instance variables at which to begin fetching. The index of the first named instance variable is 1. Note that if startIndex is 1 greater than the size of the object, this function returns a byte array of size 0, but no error is generated.

theOops

The array of fetched OOPs.

numBytes

The maximum number of elements to return.

Return Value

Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.) In case of error, this function returns zero.

Description

This function uses structural access to fetch multiple values from an object’s named instance variables, starting at the specified index.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

This example fetches an Account’s id, customer, and salesRep.

BoolType fetchNamedOops_example(OopType anAccount)
{
   GciErrSType err;
   // fetch the number of named instvars
 
   int namedSize = GciFetchNamedSize(anAccount);
   if (namedSize == 0) {  return  false;  }
 
   OopType *oBuffer = (OopType*) malloc( sizeof(OopType) * namedSize );
   if (oBuffer == NULL) { return  false; } 
 
   int numRet = GciFetchNamedOops(anAccount, 1, oBuffer, namedSize);
   if (GciErr(&err)) {
      printf("Error %d, %s\n", err.number, err.message);
      return false;
   }
   free(oBuffer);
   return (numRet == namedSize) ;
}

See Also

GciFetchNamedOop
GciFetchVaryingOops
GciIvNameToIdx
GciStoreNamedOops

GciFetchNamedSize

Fetch the number of named instance variables in an object.

Syntax

int GciFetchNamedSize(
OopType theObject );

Arguments

theObject

The OOP of the object.

Return Value

Returns the number of named instance variables in theObject. In case of error, this function returns zero.

Description

This function returns the number of named instance variables in a GemStone object. See the example for GciFetchNamedOops.

GciFetchNameOfClass

Fetch the class name object for a given class.

Syntax

OopType GciFetchNameOfClass(
OopType aClass );

Arguments

aClass

The OOP of a class.

Return Value

The OOP of the class’s name, or OOP_NIL if an error occurred.

Description

Given the OOP of a class, this function returns the object identifier of the String object that is the name of the class.

GciFetchNumEncodedOops

Obtain the size of an encoded OOP array.

Syntax

int GciFetchNumEncodedOops(
OopType * encodedOopArray,
const int numEncodedOops );

Arguments

encodedOopArray

An OOP array that was encoded by a call to GciEncodeOopArray.

numEncodedOops

The number of OOPs in encodedOopArray.

Return Value

Returns the number of OOPs that will be decoded by a call to GciDecodeOopArray.

Description

This function returns the total number of OOPs in an OOP array that was encoded by a call to GciEncodeOopArray.

See Also

GciDecodeOopArray
GciEnableFreeOopEncoding
GciEncodeOopArray
GciGetFreeOopsEncoded

GciFetchNumSharedCounters

Obtain the number of shared counters available on the shared page cache used by this session.

Syntax

int GciFetchNumSharedCounters( );

Return Value

Returns the number of shared counters available on the shared page cache used by this session, or -1 if the session is not logged in.

Description

This function returns the total number of shared counters available on the shared page cache used by this session.

Not supported for remote GCI interfaces.

See Also

GciDecSharedCounter
GciIncSharedCounter
GciSetSharedCounter
GciReadSharedCounter
GciReadSharedCounterNoLock
GciFetchSharedCounterValuesNoLock

GciFetchObjectInfo

Fetch information and values from an object.

Syntax

BoolType GciFetchObjectInfo(
OopType theObject,
GciFetchObjInfoArgsSType * args );

Arguments

theObject

OOP of any object with byte, pointer, or NSC format.

args   

Pointer to an instance of GciFetchObjInfoArgsSType with the following argument fields:

GciObjInfoSType *  info
Pointer to an instance of GciObjInfoSType, or NULL.

ByteType *  buffer
Pointer to an area where byte or OOP values will be returned, or NULL.

int64  startIndex
The offset in the object at which to start fetching, a 1-based offset into the named and unnamed instance variables. Ignored if bufSize == 0 or buffer == NULL.

int64  bufSize
The size in bytes of the buffer, maximum number of elements fetched for a byte object. For an OOP object, the maximum number of elements fetched for an OOP object will be bufSize/8. If fetching a kind of BinaryFloat and greater than zero, it must be large enough to fetch the complete object.

int64  numReturned
On return, this contains the number of logical elements (bytes or OOPs) returned in buffer. Note that the size of (OopType) is 8 bytes.

int  retrievalFlags
If (retrievalFlags & GCI_RETRIEVE_EXPORT) != 0 then if theObject is non-special, theObject is automatically added to the PureExportSet or the user action’s export set (see GciSaveObjs).

Return Value

TRUE if successful, FALSE if an error occurs.

Description

GciFetchObjectInfo fetches information and values from an object starting at the specified index using structural access. If either info or buffer is NULL, then that part of the result is not filled in. If numReturned is NULL, then buffer will not be filled in.

The offset in startIndex does not distinguish between named and unnamed instance variables. Indices are based at the beginning of the object’s array of instance variables. In that array, any existing named instance variables are followed by any existing unnamed instance variables

If theObject is a byte object with multiple bytes per character or digit, such as DoubleByteString, LargeInteger, or Float, the results in args->buffer will be automatically byte swizzled to client native byte order. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.

For MultiByteStrings, args->startIndex must be aligned on a character boundary and args->bufSize must be a multiple of the number of bytes per character in the string. For numeric objects, args->startIndex must be one and args->bufSize must be the size of the numeric class.

See Also

GciFetchOops
GciFetchBytes_
GciFetchOop
GciSaveObjs

GciFetchObjImpl

Fetch the implementation of an object.

Syntax

int GciFetchObjImpl(
OopType theObject );

Arguments

theObject

The OOP of the object.

Return Value

Returns an integer representing the implementation type of theObject (0=pointer, 1=byte, 2=NSC, or 3=special). In case of error, the return value is -l.

Description

This function obtains the implementation of an object (pointer, byte, NSC, special) from GemStone. For more information about implementation types, see Object implementation.

See Also

GciFetchClass
GciFetchNamedSize
GciFetchSize_
GciFetchVaryingSize_

GciFetchOop

Fetch the OOP of one instance variable of an object.

Syntax

OopType GciFetchOop(
OopType theObject,
int64 atIndex );

Arguments

theObject

The OOP of the source object.

atIndex  

The index into theObject of the OOP to be fetched. The index of the first OOP is 1.

Return Value

Returns the OOP at the specified index of the source object. In case of error, this function returns OOP_NIL.

Description

This function fetches the OOP of a single instance variable from any object at the specified index, using structural access. It does not distinguish between named and unnamed instance variables. Indices are based at the beginning of the object’s array of instance variables. In that array, any existing named instance variables are followed by any existing unnamed instance variables.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples. This example illustrates fetching one named and one unnamed instance variable from an Account.

BoolType fetchOop_example(OopType anAccount)
{
   GciErrSType err;
   // fetch the number of named and unnamed instvars
   int namedSize = GciFetchNamedSize(anAccount);
   int64 varyingSize = GciFetchVaryingSize_(anAccount);
 
   // fetch anAccount's salesRep
   int indexOfSalesRep = 3;   
   if (namedSize < indexOfSalesRep) { return false; }
   OopType salesRep = GciFetchOop(anAccount, indexOfSalesRep );
   if (GciErr(&err)) {
      printf("Error %d, %s\n", err.number, err.message);
      return false;   }
   
   // fetch the first product in the indexed variables 
   if (varyingSize < 1) { return false; }
   OopType firstProduct = GciFetchOop(anAccount, namedSize + 1 );
   if (GciErr(&err)) {
      printf("Error %d, %s\n", err.number, err.message);
      return false;   }
   
   return true;
}

See Also

GciFetchOops
GciStoreOop
GciStoreOops

GciFetchOops

Fetch the OOPs of one or more instance variables of an object.

Syntax

int GciFetchOops(
OopType theObject,
int64 startIndex,
OopType theOops[ ],
int numOops );

Arguments

theObject  

The OOP of the source object.

startIndex   

The index into theObject’s unnamed and named instance variables at which to begin fetching. The index of the first instance variable is 1. Note that if startIndex is 1 greater than the size of the object, this function returns an array of size 0, but no error is generated.

theOops   

The array of fetched OOPs.

numOops   

The maximum number of OOPs to return.

Return Value

Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.) In case of error, this function returns zero.

Description

This function fetches the OOPs of multiple instance variables from any object starting at the specified index, using structural access. It does not distinguish between named and unnamed instance variables. Indices are based at the beginning of the object’s array of instance variables. In that array, any existing named instance variables are followed by any existing unnamed instance variables.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

BoolType fetchOops_example(OopType anAccount)
{
   GciErrSType err;
   // fetch the number of named and unnamed instvars
   int namedSize = GciFetchNamedSize(anAccount);
   int64 varyingSize = GciFetchVaryingSize_(anAccount);
 
   int mySize = namedSize + varyingSize;
   OopType oBuffer[mySize];
   
   // Two ways to fetch anAccount's products list 
   GciFetchOops(anAccount, namedSize + 1, oBuffer, varyingSize);
   GciFetchVaryingOops(anAccount, 1, oBuffer, varyingSize);
 
   // Fetch the named instance variables PLUS the products list
   GciFetchOops(anAccount, 1, oBuffer, mySize);
   // oBuffer[0..namedSize-1] are named instVar values
   // oBuffer[namedSize] are varying instVar values 
 
   if (GciErr(&err)) {
      printf("Error %d, %s\n", err.number, err.message);
      return false; }
      
  return true;
}

See Also

GciFetchOops
GciFetchVaryingOop
GciStoreOops

GciFetchPaths

Fetch selected multiple OOPs from an object tree.

Syntax

BoolType GciFetchPaths(
const OopType theOops[ ],
int numOops,
const int paths[ ],
const int pathSizes[ ],
int numPaths,
OopType results[ ] );

Arguments

theOops   

A collection of OOPs from which you want to fetch.

numOops 

The size of theOops.

paths   

An array of integers. This one-dimensional array contains the elements of all constituent paths, laid end to end.

pathSizes   

An array of integers. Each element of this array is the length of the corresponding path in the paths array (that is, the number of elements in each constituent path).

numPaths   

The number of paths in the paths array. This should be the same as the number of integers in the pathSizes array.

results   

An array containing the OOPs that were fetched.

Return Value

Returns TRUE if all desired objects were successfully fetched. Returns FALSE if the fetch on any path fails for any reason.

Description

This function allows you to fetch multiple OOPs from selected positions in an object tree with a single GemBuilder call, importing only the desired information from the database.

Each path in the paths array is itself an array of integers. Those integers are offsets that specify a path from which to fetch objects. In each path, a positive integer x refers to an offset within an object’s named instance variables (see GciFetchNamedOop), while a negative integer -x refers to an offset within an object’s indexed instance variables (see GciFetchVaryingOop).

From each object in theOops, this function fetches the object pointed to by each element of the paths array, and stores the fetched object into the results array. The results array contains (numOops * numPaths) elements, stored in the following order:

[0,0]..[0,numPaths-1]..[1,0]..[1,numPaths-1]..[numOops-1,0]..[numOops-1,numPaths-1]

That is, all paths are first applied in order to the first element of theOops. This step is repeated for each subsequent object, until all paths have been applied to all elements of theOops. The result for object i and path j is represented as:

results[ ((i-1) * numPaths) + (j-1) ]

If the fetch on any path fails for any reason, the result of that fetch is reported in the results array as OOP_ILLEGAL. Because some path-fetching errors do not necessarily invalidate the remainder of the information fetched, the system will then attempt to continue its fetching with the remaining paths and objects.

This ability to complete a fetching sequence despite errors means that your application won’t be slowed by a round-trip to GemStone on each fetch to check for errors. Instead, after a fetch is complete, you can cycle through the result and deal selectively at that time with any errors you find.

The appropriate response to an error in path fetching depends both upon the error itself and on your application. Here are some of the reasons why a fetch might not succeed:

  • The user had no read authorization for some object in the path. The seriousness of this depends on your application. In some applications, you may simply wish to ignore the inaccessible data.
  • The path was invalid for the object to which it was applied. This can happen if the object from which you’re fetching is not of the correct class, or if the path itself is faulty for the class of the object.
  • The path was valid but simply not filled out for the object being processed. This would be the case, for example, if you attempted to access address.zip when an Employee’s Address instance variable contained only nil. This is probably the most common path fetching error, and may require only that the application program detect the condition and display some suitable indication to the user that a field is not yet filled in with meaningful data.

Example 1: Calling sequence for a single object and a single path

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

The first example fetches just the street address from a single Account.

OopType fetchPaths_example1(OopType anAccount)
{
   GciErrSType errInfo;
   int path_size = 3;
   int aPath[path_size]; 
   aPath[0] = 2; //name
   aPath[1] = 2; //address
   aPath[2] = 1; //street
   
   OopType result;
   GciFetchPaths(&anAccount, 1, aPath, &path_size, 1, &result);
   if (GciErr(&errInfo)) {
      printf("Error %d, %s\n", errInfo.number, errInfo.message);
      return OOP_NIL;
   }
   return result;
}

Example 2: Calling sequence for multiple objects with a multiple paths

This example fetches the customer name, and the address city, from two separate accounts.

BoolType fetchPaths_example2(int numOfAccounts, OopType* resultAccounts)
{
   GciErrSType errInfo;
   OopType myAccts; 
   myAccts = GciExecuteStr("AllAccounts", OOP_NIL);
   if (myAccts == OOP_NIL) { return false; }
 
   int numRet = GciFetchVaryingOops(myAccts, 1, resultAccounts, numOfAccounts);
   if (numRet != numOfAccounts) { return false; }
  
   int path_segments[2]; 
   path_segments[0] = 2;
   path_segments[1] = 3;
   int serialPath[6]; // size is sum of path_segments
   serialPath[0] = 2; //customer
   serialPath[1] = 1; //name
   serialPath[2] = 2; //customer
   serialPath[3] = 2; //address
   serialPath[4] = 2; //city
   
   OopType results[2 * numOfAccounts]; // size of path_segments * number of accounts
   GciFetchPaths(resultAccounts, numOfAccounts, serialPath, path_segments, 2, results);    
 
   if (GciErr(&errInfo)) {
      printf("GciFetchPaths error %d, %s\n", errInfo.number, errInfo.message);
      return false;
   }
   return true;
}

See Also

GciStorePaths

GciFetchSharedCounterValuesNoLock

Fetch the value of multiple shared counters without locking them.

Syntax

int GciFetchSharedCounterValuesNoLock(
int startIndex,
int64_t buffer[ ],
size_t * maxReturn);

Arguments

startIndex   

The offset into the shared counters array of the first shared counter value to fetch.

buffer   

Pointer to a buffer where the shared counter values will be stored. The buffer must be at least 8 * maxReturn bytes and the address must be aligned on an 8-byte boundary.

maxReturn   

Pointer to a value that indicates the maximum number of shared counters to fetch.

Return Value

Returns an int indicating the number of shared counter values successfully stored in the buffer. Returns -1 if a bad argument is detected.

Description

Fetch the values of multiple shared counters in a single call, without locking any of them. The values of the maxReturn count of shared counters starting at the offset indicated by counterIdx (0-based) are put into the buffer buffer. buffer must be large enough to accommodate maxReturn 8-byte values, and be aligned on an 8-byte boundary.

Not supported for remote GCI interfaces.

See Also

GciDecSharedCounter
GciFetchNumSharedCounters
GciIncSharedCounter
GciReadSharedCounter
GciReadSharedCounterNoLock
GciSetSharedCounter

GciFetchSize_

Fetch the size of an object.

Syntax

int64 GciFetchSize_(
OopType theObject );

Arguments

theObject

The OOP of the object.

Return Value

Returns the size of theObject. In case of error, this function returns zero.

Description

This function obtains the size of an object from GemStone.

The result of this function depends on the object’s implementation (see GciFetchObjImpl). For byte objects, this function returns the number of bytes in the object. (For Strings, this is the number of Characters in the String; for Floats, the size is 23.) For pointer objects, this function returns the number of named instance variables (GciFetchNamedSize) plus the number of indexed instance variables, if any (GciFetchVaryingSize_). For NSC objects, this function returns the cardinality of the collection. For special objects, the size is always zero.

This differs somewhat from the result of executing the Smalltalk method Object>>size, as shown in Table 7.11:

Table 7.11 Differences in Reported Object Size

Implementation

Object>>size (Smalltalk)

GciFetchSize_

0=Pointer

Number of indexed elements in the object (0 if  not indexed)

Number of indexed elements PLUS number of named instance variables

1=Byte

Number of indexed elements in the object

Same as Smalltalk message “size”

2=NSC

Number of elements in the object

Same as Smalltalk message “size”

3=Special

0

0

Example

void fetchSize_example(void)
{
  const char* str = "abcdef";
  OopType oString = GciNewString(str);
 
  int64 itsSize = GciFetchSize_(oString);
  if (itsSize != (int64)strlen(str)) {
    printf("error during fetch size\n");
  }
}

See Also

GciFetchClass
GciFetchNamedSize
GciFetchObjImpl
GciFetchVaryingOop

GciFetchUtf8Bytes_

GciFetchUtf8Bytes__

Encode a String, MultiByteString, or Uft8 as UTF-8, and fetch the bytes of the encoded result.

Syntax

int64 GciFetchUtf8Bytes_(
OopType oopOfAString,
int64 startIndex,
ByteType * theBytes,
int64 numBytes,
OopType * utf8String,
int flags);

int64 GciFetchUtf8Bytes__(
OopType oopOfAString,
int64 startIndex,
ByteType * theBytes,
int64 numBytes,
OopType * utf8String,
int flags,
int64 maxConvert);

Arguments

oopOfAString 

The OOP of the GemStone String, MultiByteString or Utf8.

startIndex   

The index into aString at which to begin encoding bytes. The index of the first element is 1. Note that if startIndex is 1 greater than the size of the object, this function returns a byte array of size 0, but no error is generated.

theBytes   

The array of encoded bytes

numBytes   

The maximum number of bytes to return.

utf8String   

Pointer to the OOP of the encoded string.

flags   

Bits in flags are defined by GciFetchUtf8Flags. The options are

GCI_UTF8_FetchNormal = 0
generate an error on illegal codePoints in the input.

GCI_UTF8_NoError = 0x2
return a message instead of signalling Exception.

maxConvert

The upper limit of the size in bytes of the instance of Utf8 in *utf8String.

Return Value

Returns the number of bytes fetched. (This may be less than numBytes, depending upon the size of theObject.) In case of error, this function returns zero.

Description

This function encodes a kind of String, MultiByteString, or Utf8 into UTF-8. The encoded bytes are placed in the buffer theBytes, and the OOP of the encoded object is placed at utf8String.

The OOP of utf8String is also placed in the ExportSet. The caller must pass the OOP of utf8String to GciReleaseOops after fetching all bytes.

If all characters in aString are < 128, or if the class of aString is Utf8, then the behavior is the same as GciFetchBytes_. No encoding is done; the bytes of aString are place in theBytes. utf8String is the same as aString, and is not added to the ExportSet.

See Also

GciFetchBytes_
GciNewUtf8String

GciFetchVaryingOop

Fetch the OOP of one unnamed instance variable from an indexable pointer object or NSC.

Syntax

OopType GciFetchVaryingOop(
OopType theObject,
int64 atIndex );

Arguments

theObject

The OOP of the pointer or NSC object.

atIndex   

The index of the OOP to be fetched. The index of the first unnamed instance variable’s OOP is 1.

Return Value

Returns the OOP of the unnamed instance variable at index atIndex. In case of error, this function returns OOP_NIL.

Description

This function fetches the OOP of a single unnamed instance variable at the specified index, using structural access. The numerical index of any unordered variable of an NSC can change whenever the NSC is modified.

Example

See Executing the examples for the smalltalk code that supports the examples.

OopType fetchVaryingOop_example(OopType anAccount)
{
   GciErrSType err;
   int64 varyingSize = GciFetchVaryingSize_(anAccount);
   if (varyingSize < 1) { return OOP_NIL; }
   
   // fetch the first product in the indexed variables 
   OopType firstProduct = GciFetchVaryingOop(anAccount, 1);
   if (GciErr(&err)) {
      printf("Error %d, %s\n", err.number, err.message);
      return OOP_NIL;   }
   
   return firstProduct;
}

See Also

GciFetchNamedOop
GciFetchOop
GciFetchVaryingOops
GciStoreIdxOop

GciFetchVaryingOops

Fetch the OOPs of one or more unnamed instance variables from an indexable pointer object or NSC.

Syntax

int GciFetchVaryingOops(
OopType theObject,
int64 startIndex,
OopType theOops[ ],
int numOops );

Arguments

theObject  

The OOP of the pointer or NSC object.

startIndex   

The index into theObject’s elements at which to begin fetching. The index of the first unnamed instance variable is 1. Note that if startIndex is 1 greater than the number of unnamed instance variables of the object, this function returns a byte array of size 0, but no error is generated.

theOops   

The array of fetched OOPs.

numBytes   

The maximum number of elements to return.

Return Value

Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.) In case of error, this function returns zero.

Description

This function fetches the OOPs of multiple unnamed instance variables beginning at the specified index, using structural access. The numerical index of any unordered variable of an NSC can change whenever the NSC is modified.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

BoolType fetchVaryingOops_example(OopType anAccount)
{
   GciErrSType err;
   int64 varyingSize = GciFetchVaryingSize_(anAccount);
   if (varyingSize < 1) { return false; }
   
   OopType oBuffer[varyingSize];
   
   // fetch OOPs for all indexed instvars 
   int numRet = GciFetchVaryingOops(anAccount, 1, oBuffer, varyingSize);
   if (GciErr(&err)) {
      printf("Error %d, %s\n", err.number, err.message);
      return false; }
      
   return numRet = varyingSize;
}

See Also

GciFetchNamedOops
GciFetchVaryingOop
GciFetchVaryingSize_
GciStoreIdxOop
GciStoreIdxOops

GciFetchVaryingSize_

Fetch the number of unnamed instance variables in a pointer object or NSC.

Syntax

int64 GciFetchVaryingSize_(
OopType theObject );

Arguments

theObject 

The OOP of the object.

Return Value

Returns the number of unnamed instance variables in theObject. In case of error, this function returns zero.

Description

This function obtains from GemStone the number of indexed variables in an indexable object or the number of unordered variables in an NSC.

Example

See an example under GciFetchOop.

See Also

GciFetchClass GciFetchSize_
GciFetchNamedSize GciSetVaryingSize
GciFetchObjImpl

GciFindObjRep

Fetch an object report in a traversal buffer.

Syntax

GciObjRepHdrSType * GciFindObjRep(
GciTravBufType * travBuff,
OopType theObject );

Arguments

travBuff   

A traversal buffer returned by a call to GciTraverseObjs.

theObject  

The OOP of the object to find.

Return Value

Returns a pointer to an object report within the traversal buffer. In case of error, this function returns NULL.

Description

This function locates an object report within a traversal buffer that was previously returned by GciTraverseObjs. If the report is not found within the buffer, this function generates the error GCI_ERR_TRAV_OBJ_NOT_FOUND.

Example

GciObjRepHdrSType* findObjRepExample(GciTravBufType *buf, OopType objId)
{
  GciObjRepHdrSType *theReport = GciFindObjRep(buf, objId);
  if (theReport == NULL) {
    GciErrSType errInfo; 
    if (GciErr(&errInfo)) {
       printf("error category "FMT_OID" number %d, %s\n",
           errInfo.category, errInfo.number, errInfo.message);
    }
  }
  return theReport;
}

See Also

GciTraverseObjs
GciObjRepSize_

GciFloatKind

Obtain the float kind corresponding to a C double value.

Syntax

GciFloatKindEType GciFloatKind(
double aReal );

Arguments

aReal   

A floating point value.

Return Value

Returns the type of GemStone Float object that corresponds to the C value.

Description

This function obtains the kind of GemStone Float object that corresponds to the C floating point value aReal.

See Also

GciFltToOop
GciOopToFlt

GciFltToOop

Convert a C double value to a SmallDouble or Float object.

Syntax

OopType GciFltToOop(
double aDouble );

Arguments

aDouble 

A C double value

Return Value

Returns the OOP of the GemStone SmallDouble or Float object that corresponds to the C value. In case of error, this function returns OOP_NIL.

Description

This function translates a C double precision value into the equivalent GemStone Float object.

Example

#include <stdlib.h>
 
void fltToOopExample(void)
{
  // random double to Oop conversion producing a Float or SmallFloat
  double rand = drand48() * 1.0e38 ; 
  OopType oFltObj = GciFltToOop(rand); 
  
  OopType oClass = GciFetchClass(oFltObj);
  const char* kind;
  if (oClass == OOP_CLASS_SMALL_DOUBLE) {
    kind = "SmallDouble";
  } else if (oClass == OOP_CLASS_FLOAT) {
    kind = "Float";
  } else {
    kind = "Unexpected";
  }
  printf("result is a %s, class oop = "FMT_OID"\n", kind, oClass);
}  
 

See Also

GciOopToFlt
Gci_doubleToSmallDouble

GciGetFreeOop

Allocate an OOP.

Syntax

OopType GciGetFreeOop( )

Return Value

Returns an unused object identifier (OOP).

You cannot use the result of GciGetFreeOop to create a Symbol object.

Description

Allocates an object identifier without creating an object.

The object identifier returned from this function remains allocated to the Gci session until the session calls GciLogout or until the identifier is used as an argument to a function call.

If an object identifier returned from GciGetFreeOop is used as a value in a GciStore... call before it is used as the objId argument of a GciCreate... call, then an unresolved forward reference is created in object memory. This is a reference to an object that does not yet exist. This forward reference must be satisfied by using the identifier as the objId argument to a GciCreate... call before a GciCommit can be successfully executed.

If GciCommit is attempted prior to satisfying all unresolved forward references, an error is generated and GciCommit returns FALSE. Then GciCreate can be used to satisfy the forward references and GciCommit can be attempted again. GciAbort removes all unsatisfied forward references from the session’s object space, just as it removes any other uncommitted modifications.

As long as it remains an unresolved forward reference, the identifier returned by GciGetFreeOop can be used only as a parameter to the following function calls, under the given restrictions:

  • As the objID of the object to be created
GciCreateByteObj
  • As the objID of the object to be created, or as an element of the value buffer
GciCreateOopObj
  • As an element of the value buffer only
GciStoreOop
GciStoreOops
GciStoreIdxOop
GciStoreIdxOops
GciStoreNamedOop
GciStoreNamedOops
GciStoreTrav
GciAppendOops
GciAddOopToNsc
GciAddOopsToNsc
GciNewOopUsingObjRep
  • As an element of newValues only
GciStorePaths

See Also

GciCreateByteObj
GciCreateOopObj
GciGetFreeOops
GciGetFreeOopsEncoded

GciGetFreeOops

Allocate multiple OOPs.

Syntax

void GciGetFreeOops(
int count,
OopType * resultOops );

Arguments

count   

The number of OOPs to allocate. On return, the number of OOPs that were allocated.

resultOops   

An array to hold the allocated OOPs.

Return Value

Returns an unused object identifier (OOP).

Description

Allocates object identifiers without creating objects.

If an object identifier returned from GciGetFreeOops is used as a value in a GciStore... call before it is used as the objId argument of a GciCreate... call, then an unresolved forward reference is created in object memory. This is a reference to an object that does not yet exist. This forward reference must be satisfied by using the identifier as the objId argument to a GciCreate... call before a GciCommit can be successfully executed.

If GciCommit is attempted prior to satisfying all unresolved forward references, an error is generated and GciCommit returns false. In this case, GciCreate can be used to satisfy the forward references and GciCommit can be attempted again. GciAbort removes all unsatisfied forward references from the session’s object space, just as it removes any other uncommitted modifications.

As long as it remains an unresolved forward reference, the identifier returned by GciGetFreeOops can be used only as a parameter to the following function calls, under the given restrictions:

  • As the objID of the object to be created
GciCreateByteObj
  • As the objID of the object to be created, or as an element of the value buffer
GciCreateOopObj
  • As an element of the value buffer, only
GciStoreOop
GciStoreOops
GciStoreIdxOop
GciStoreIdxOops
GciStoreNamedOop
GciStoreNamedOops
GciStoreTrav
GciAppendOops
GciAddOopToNsc
GciAddOopsToNsc
GciNewOopUsingObjRep
  • As an element of newValues, only
GciStorePaths

See Also

GciCreateByteObj
GciCreateOopObj
GciGetFreeOop
GciGetFreeOopsEncoded

GciGetFreeOopsEncoded

Allocate multiple OOPs.

Syntax

void GciGetFreeOopsEncoded(
int * count,
OopType * encodedOops );

Arguments

count   

The number of OOPs to allocate. On return, the number of OOPs that were allocated.

encodedOops   

A pointer to memory for holding encoded OOPs. Must be at least the size specified by count.

Description

This function is identical to GciGetFreeOops, except that it returns OOPs in an encoded array that is more compact for less network I/O. Before the OOPs can be used, the encoded array must be decoded by calling GciDecodeOopArray().

See Also

GciCreateByteObj
GciCreateOopObj
GciDecodeOopArray
GciEncodeOopArray
GciFetchNumEncodedOops
GciGetFreeOop
GciGetFreeOops
GciGetFreeOopsEncoded
GciFetchNumEncodedOops

GciGetSessionId

Find the ID number of the current user session.

Syntax

GciSessionIdType GciGetSessionId( )

Return Value

Returns the session ID currently being used for communication with GemStone. Returns GCI_INVALID_SESSION_ID if there is no session ID (that is, if the application is not logged in).

Description

This function obtains the unique session ID number that identifies the current user session to GemStone. An application can have more than one active session, but only one current session.

The ID numbers assigned to your application’s sessions are unique within your application, but bear no meaningful relationship to the session IDs assigned to other GemStone applications that may be executing at the same time or accessing the same database.

Example

void getSessionExample(const char* userId, const char* password)
{
  if (GciLogin(userId, password)) {
    GciSessionIdType sessId = GciGetSessionId();
    printf("sessionId is %d \n", sessId);
  } 
  GciLogout();
  GciSessionIdType sessId = GciGetSessionId();
  if (sessId != GCI_INVALID_SESSION_ID) {
    printf("unexpected sessionId %d after logout \n", sessId);
  }
}
 

See Also

GciSetSessionId

GciHardBreak

Interrupt GemStone and abort the current transaction.

Syntax

void GciHardBreak( )

Description

GciHardBreak sends a hard break to the current user session (set by the last GciLogin or GciSetSessionId), which interrupts Smalltalk execution.

All GemBuilder functions can recognize a hard break, so the users of your application can terminate Smalltalk execution. For example, if your application sends a message to an object (via GciPerform), and for some reason the invoked Smalltalk method enters an infinite loop, the user can interrupt the application. GciHardBreak has no effect if called from within a User Action.

In order for GemBuilder functions in your program to recognize interrupts, your program will need a signal handler that can call the functions GciSoftBreak and GciHardBreak. Since GemBuilder does not relinquish control to an application until it has finished its processing, soft and hard breaks must be initiated from a signal handler.

If GemStone is executing when it receives the break, it replies with the error message RT_ERR_HARD_BREAK. Otherwise, it ignores the break.

If GemStone is executing any of the following methods of class Repository, then a hard break terminates the entire session, not just Smalltalk execution:

fullBackupTo:
restoreFromBackup(s):
markForCollection
objectAudit
auditWithLimit:
repairWithLimit:
pagesWithPercentFree

See Also

GciSoftBreak

GciHiddenSetIncludesOop

Determines whether the given OOP is present in the specified hidden set.

Syntax

BoolType GciHiddenSetIncludesOop(
OopType theOop,
int hiddenSetId );

Arguments

theOop   

The OOP to search for.

hiddenSetId 

The index to the hidden set to search.

Return Value

True if the OOP was found; false otherwise.

Description

The Gem holds objects in a number of sets ordinarily hidden from the user, including the PureExportSet (among others). GciHiddenSetIncludesOop allows you to pass in an index to a specified hidden set to determine if the set includes a specific object. For indexes of available hidden sets, see the GemStone Smalltalk method System Class >> HiddenSetSpecifiers.

GciI32ToOop

Convert a C 32-bit integer value to a GemStone object.

Syntax

OopType GciI32ToOop(
int anInt );

Arguments

anInt

A C 32-bit signed integer.

Return Value

The GciI32ToOop function returns the OOP of a GemStone object whose value is equivalent to anInt.

Description

The GciI32ToOop function translates a C 32bit integer value into the equivalent GemStone object. This function always succeeds.

See Also

GciI64ToOop
GciOopToI32

GCI_I64_IS_SMALL_INT

(MACRO) Determine whether or not a 64-bit C integer is in the SmallInteger range.

Syntax

BoolType GCI_I64_IS_SMALL_INT(anInt)

Arguments

anInt

A C 64-bit signed integer.

Return Value

Returns TRUE if the object is within the SmallInteger range, FALSE otherwise.

Description

This macro tests to see if anInt is within the SmallInteger range.

A SmallInteger has a 61 bit 2’s complement integer and 3 tag bits. For a positive int64 argument, top 4 bits must be 2r0000 for argument to be within SmallInteger range; for a negative int64 argument, the top 4 bits must be 2r1111 for argument to be within SmallInteger range.

See Also

GCI_OOP_IS_SMALL_INT

 

GciI64ToOop

Convert a C 64-bit integer value to a GemStone object.

Syntax

OopType GciI64ToOop(
int64 anInt );

Arguments

anInt

A C 64-bit signed integer.

Return Value

The GciI64ToOop function returns the OOP of a GemStone object whose value is equivalent to anInt.

Description

The GciI64ToOop function translates a C 64-bit integer (int64_t) value into the equivalent GemStone object. If the result is not a SmallInteger, the result is automatically saved to the export set as described under GciSaveObjs.

See Also

GciI32ToOop
GciOopToI64

GciIncSharedCounter

Increment the value of a shared counter.

Syntax

BoolType GciIncSharedCounter(
int64_t counterIdx,
int64_t * value);

Arguments

counterIdx   

The offset into the shared counters array of the value to increment.

value

Pointer to a value that indicates how much to increment the shared counter by. On return, this will hold the new value after the shared counter, after incrementing.

Return Value

Returns a C Boolean value indicating if the shared counter was successfully incremented. Returns TRUE if successful, FALSE if an error occurred.

Description

This function increments the value of a particular shared counter by a specified amount. The shared counter is specified by index. The maximum value of this shared counter is INT_MAX (2147483647), attempts to increase a shared counter to higher values is not an error, but does not cause the value to increase further, it will remain set to INT_MAX.

This function is not supported for remote GCI interfaces, and will always return FALSE.

See Also

GciDecSharedCounter
GciFetchNumSharedCounters
GciFetchSharedCounterValuesNoLock
GciReadSharedCounter
GciReadSharedCounterNoLock
GciSetSharedCounter

GciInit

Initialize GemBuilder.

Syntax

BoolType GciInit( );

Return Value

The function GciInit returns TRUE or FALSE to indicate successful or unsuccessful initialization of GemBuilder. .

Description

This function initializes GemBuilder. Among other things, it establishes the default GemStone login parameters.

If your C application program is linkable, you may wish to call GciInitAppName, which you must do before you call GciInit. After GciInitAppName, you must call GciInit or GciInit_ before calling any other GemBuilder functions. Otherwise, GemBuilder behavior will be unpredictable.

When doing run-time binding, you should call GciRtlLoad before calling GciInit. For details, see Building the Application.

When GemBuilder is initialized on UNIX platforms, it establishes its own handler for SIGIO interrupts. See Signal Handling in Your GemBuilder Application for information on GciInit’s handling of interrupts and pointers on making GemBuilder, application, and third-party handlers work together.

See Also

GciInit_
GciInitAppName

GciInit_

Initialize GemBuilder, including arguments.

Syntax

BoolType GciInit( );

(int) GciInit_(
BoolType quietMode,
GciProcessType processType,
GciCfgFileArgs *cfg,
char *configFileWarn,
size_t warnSize
);

Return Value

The function GciInit_ returns 0 for success, -2 for errors in the configuration file, and -2 for memory allocation errors in libgcilnk.

Description

This function initializes GemBuilder. Among other things, it establishes the default GemStone login parameters.

See gci.ht for details on GciCfgFileArgs, which is used by topaz to pass configuration file arguments. GciProcessType should be specified as GCI_PROCESS_GEM for linked Gem processes.

Linked C applications may call GciInitAppName, before invoking GciInit_, and after GciInitAppName, you must call GciInit or GciInit_ before calling any other GemBuilder functions. Otherwise, GemBuilder behavior will be unpredictable.

When doing run-time binding, you should call GciRtlLoad before calling GciInit. See Building the Application for details.

When GemBuilder is initialized on UNIX platforms, it establishes its own handler for SIGIO interrupts. See Signal Handling in Your GemBuilder Application for information on GciInit’s handling of interrupts and pointers on making GemBuilder, application, and third-party handlers work together.

See Also

GciInit
GciInitAppName

GciInitAppName

GciInitAppName_

Override the default application configuration file name.

Syntax

void GciInitAppName(
const char * applicationName,
BoolType logWarnings );

void GciInitAppName_(
const char * applicationName,
BoolType logWarnings,
unsigned int gemTOCOverrideKB,
int gemNativeCodeOverride );

Arguments

applicationName   

The application’s name, as a character string.

logWarnings   

If TRUE, causes the configuration file parser to print any warnings to standard output at executable startup.

gemTOCOverrideKB

If non-zero, defines the maximum size (in KB) of temporary object memory for this application. This value overrides any GEM_TEMPOBJ_CACHE_SIZE settings in configuration files read by GciInit.

gemNativeCodeOverride

If non-zero, value overrides the GEM_NATIVE_CODE_ENABLED config file settings in configuration files read by GciInit.

Description

This function affects only linkable applications. It has no effect on RPC applications. If you do not call this function before you call GciInit, it will have no effect.

A linkable GemBuilder application reads a configuration file called applicationName.conf when GciInit is called. This file can alter the behavior of the underlying GemStone session. For complete information, please see the System Administration Guide for GemStone/S 64 Bit.

A linkable GemBuilder application uses defaults until it calls this function (if it does) and reads the configuration file (which it always does). For linkable GemBuilder applications, the default application name is gci, so the default executable configuration file is gci.conf. The applicationName argument overrides the default application name with one of your choice, which causes your linkable GemBuilder application to read its own executable configuration file.

The logWarnings argument determines whether or not warnings that are generated while reading the configuration file are written to standard output. If your application does not call GciInitAppName, the default log warnings setting is FALSE. The logWarnings argument resets the default for your application, which is used in the absence of a LOG_WARNINGS entry in the configuration file, or until that entry is read.

The GciInitAppName_ variant allows you to specify additional arguments that are used by the linkable GemBuilder application: the maximum temporary object cache size, and an override for the native code configuration.

You application may not call both GciInitAppName and GciInitAppName_.

See Also

GciInit

GciInstallUserAction

GciInstallUserAction_

Associate a C function with a Smalltalk user action.

Syntax

void GciInstallUserAction(
GciUserActionSType * userAction );

void GciInstallUserAction_(
GciUserActionSType * userAction,
BoolType errorIfDuplicate );

Arguments

userAction   

A pointer to a C structure that describes the user-written C function.

errorIfDuplicate

If True, return an error if there is already a user action with the specified name. If False, leave the existing user action in place and ignore the current call.

Description

This function associates a user action name (declared in Smalltalk) with a user-written C function. Your application must call GciInstallUserAction before beginning any GemStone sessions with GciLogin. This function is typically called from GciUserActionInit. For more information, see Chapter 4, “Writing User Actions”

See Also

Chapter 4, “Writing User Actions”
User Action Information Structure - GciUserActionSType
GciDeclareAction
GciInUserAction
GciUserActionInit
GciUserActionShutdown

GciInstMethodForClass

Compile an instance method for a class.

Syntax

OopType GciInstMethodForClass(
OopType source,
OopType aClass,
OopType category,
OopType symbolList );

Arguments

source

The OOP of a Smalltalk string to be compiled as a instance method.

aClass

The OOP of the class with which the method is to be associated.

category

The OOP of a Smalltalk string, which contains the name of the category to which the method is added. If the category is nil (OOP_NIL), the compiler adds this method to the category “(as yet unclassified)”.

symbolList

The OOP of a GemStone symbol list, or OOP_NIL. Smalltalk resolves symbolic references in source code by using symbols that are available from symbolList. A value of OOP_NIL means to use the default symbol list for the current GemStone session (System myUserProfile symbolList).

Return Value

Returns OOP_NIL, unless there were compiler warnings (such as variables declared but not used, etc.), in which case the return will be the OOP of a string containing the warning messages.

Description

This function compiles an instance method for the given class.

Note that the Smalltalk virtual machine optimizes a small number of selectors, and you may not compile methods for any of those selectors. See the Programming Guide for a list of the optimized selectors.

To remove a class method, use GciExecuteStr to execute an expression removing the method, or GciClassRemoveAllMethods to remove all methods.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

void instanceMethodExample(void)
{
  // Assumes the setup code has been executed.
 
  OopType theClass = GciResolveSymbol("Customer", OOP_NIL);
  OopType oCateg = GciNewString("Printing");
 
  OopType oMethodSrc = GciNewString("asString  ^ 'Customer named ', name  asString") ;
 
  GciInstMethodForClass(oMethodSrc, theClass, oCateg, OOP_NIL);
  GciErrSType errInfo;
  if (GciErr(&errInfo)) {
    printf("error category "FMT_OID" number %d, %s\n",
       errInfo.category, errInfo.number, errInfo.message);
  }
}

See Also

GciCompileMethod
GciClassMethodForClass

GciInUserAction

Determine whether or not the current process is executing a user action.

Syntax

BoolType GciInUserAction( )

Return Value

This function returns TRUE if it is called from within a user action, and FALSE otherwise.

Description

This function is intended for use within signal handlers. It can be called any time after GciInit.

GciInUserAction returns FALSE if the process is currently executing within a GemBuilder call that was made from a user action. It considers the highest (most recent) call context only.

See Also

GciCallInProgress

GciIsKindOf

Determine whether or not an object is some kind of a given class or class history.

Syntax

BoolType GciIsKindOf(
OopType anObj,
OopType possibleClass );

Arguments

anObject  

The object to be checked.

possibleClass

A class or class history to check the object against.

Return Value

GciIsKindOf returns TRUE when the class of anObj or any of its superclasses is in the class history of possibleClass. It returns FALSE otherwise.

Description

GciIsKindOf performs structural access that is equivalent to the isKindOf: method of the Smalltalk class Object. It compares anObj’s class and superclasses to see if any of them are in a given class history. When possibleClass is simply a class (which is typical), GciIsKindOf uses possibleClass’s class history. When possibleClass is itself a class history, GciIsKindOf uses possibleClass directly.

Since GciIsKindOf does consider class histories, it can help to support schema modification by simplifying checks on the relationship of types when they can change over time. To accomplish a similar operation without seeing the effects of class histories, use the GciIsKindOfClass function.

See Also

GciIsKindOfClass
GciIsSubclassOf
GciIsSubclassOfClass

GciIsKindOfClass

Determine whether or not an object is some kind of a given class.

Syntax

BoolType GciIsKindOfClass(
OopType anObject,
OopType possibleClass );

Arguments

anObject  

The object to be checked.

possibleClass

A class to check the object against.

Return Value

GciIsKindOfClass returns TRUE when the class of anObject or any of its superclasses is possibleClass. It returns FALSE otherwise.

Description

GciIsKindOfClass performs structural access that is equivalent to the isKindOf: method of the Smalltalk class Object. It compares anObject’s class and superclasses to see if any of them are the possibleClass.

Since GciIsKindOfClass does not consider class histories, it cannot help to support schema modification. To accomplish a similar operation when the relationship of types can change over time, use the GciIsKindOf function.

See Also

GciIsKindOf
GciIsSubclassOf
GciIsSubclassOfClass

GciIsRemote

Determine whether the application is running linked or remotely.

Syntax

BoolType GciIsRemote( )

Return Value

Returns TRUE if this application is running with GciRpc (the remote procedure call version of GemBuilder). Returns FALSE if this application is running with GciLnk (that is, if GemBuilder is linked with your GemStone session).

Description

This function reports whether the current application is using the GciRpc (remote procedure call) or GciLnk (linkable) version of GemBuilder.

GciIsSubclassOf

Determine whether or not a class is a subclass of a given class or class history.

Syntax

BoolType GciIsSubclassOf(
OopType testClass,
OopType possibleClass );

Arguments

testClass  

The class to be checked.

possibleClass

A class or class history to check the object against.

Return Value

GciIsSubclassOf returns TRUE when testClass or any of its superclasses is in the class history of possibleClass. It returns FALSE otherwise.

Description

GciIsSubclassOf performs structural access that is equivalent to the isSubclassOf: method of the Smalltalk class Behavior. It compares testClass and testClass’s superclasses to see if any of them are in a given class history. When possibleClass is simply a class (which is typical), GciIsSubclassOf uses possibleClass’s class history. When possibleClass is itself a class history, GciIsSubclassOf uses possibleClass directly.

Since GciIsSubclassOf does consider class histories, it can help to support schema modification by simplifying checks on the relationship of types when they can change over time. To accomplish a similar operation without seeing the effects of class histories, use the GciIsSubclassOfClass function.

See Also

GciIsKindOf
GciIsKindOfClass
GciIsSubclassOfClass

GciIsSubclassOfClass

Determine whether or not a class is a subclass of a given class.

Syntax

BoolType GciIsSubclassOf(
OopType testClass,
OopType givenClass );

Arguments

testClass  

The class to be checked.

possibleClass

A class to check testClass against.

Return Value

GciIsSubclassOf returns TRUE when testClass or any of its superclasses is possibleClass. It returns FALSE otherwise.

Description

GciIsSubclassOfClass performs structural access that is equivalent to the isSubclassOf: method of the Smalltalk class Behavior. It compares testClass and testClass’s superclasses to see if any of them are the possibleClass.

Since GciIsSubclassOfClass does not consider class histories, it cannot help to support schema modification. To accomplish a similar operation when the relationship of types can change over time, use the GciIsSubclassOf function.

See Also

GciIsKindOf
GciIsKindOfClass
GciIsSubclassOf

GciIvNameToIdx

Fetch the index of an instance variable name.

Syntax

int GciIvNameToIdx(
OopType aClass,
const char instVarName[ ] );

Arguments

aClass   

The OOP of the class from which to obtain information about instance variables.

instVarName   

The instance variable name to search for.

Return Value

Returns the index of instVarName into the array of named instance variables for the specified class. Returns 0 if the name is not found or if an error is encountered.

Description

This function searches the array of instance variable names for the specified class (including those inherited from superclasses), and returns the index of the specified instance variable name. This index could then be used as the atIndex parameter in functions such as GciFetchNamedOop or GciStoreNamedOop.

Example

BoolType nameToIdx_example(void)
{
  // Find offset for maximum in an OutOfRange exception
  OopType theClass = GciResolveSymbol("OutOfRange", OOP_NIL);
  int idx = GciIvNameToIdx(theClass, "maximum");
  if (idx < 1) {
    printf("error during GciIvNameToIdx\n");
    return false;
  }
  return idx = 12;
}
 

See Also

GciFetchNamedOop
GciFetchNamedOops

GciLoadUserActionLibrary

Load an application user action library.

Syntax

BoolType GciLoadUserActionLibrary(
const char * uaLibraryName[ ],
BoolType mustExist,
void ** libHandlePtr,
char infoBuf[ ],
int64 infoBufSize );

Arguments

uaLibraryName

The name and location of the user action library file (a null-terminated string).

mustExist   

A flag to make the library required or optional.

libHandlePtr 

A variable to store the status of the loading operation.

infoBuf   

A buffer to store the name of the user action library or an error message.

infoBufSize 

The size of infoBuf.

Return Value

A C Boolean value. If an error occurs, the return value is FALSE, and the error message is stored in infoBuf, unless infoBuf is NULL. Otherwise, the return value is TRUE, and the name of the user action library is stored in infoBuf.

Description

This function loads a user action shared library at run time. If uaLibraryName does not contain a path, then a standard user action library search is done. The proper prefix and suffix for the current platform are added to the basename if necessary. For more information, see Chapter 4, “Writing User Actions”

If a library is loaded, libHandlePtr is set to a value that represents the loaded library, if libHandlePtr is not NULL. If mustExist is TRUE, then an error is generated if the library can not be found. If mustExist is FALSE, then the library does not need to exist. In this case, TRUE is returned and libHandlePtr is NULL if the library does not exist and non-NULL if it exists.

See Also

GciInstallUserAction
GciInUserAction
GciUserActionShutdown

GciLogin

Start a user session.

Syntax

BoolType GciLogin(
const char gemstoneUsername[ ],
const char gemstonePassword[ ] );

Arguments

gemstoneUsername

The user’s GemStone user name (a null-terminated string).

gemstonePassword

The user’s GemStone password (a null-terminated string).

Return Value

Returns true if login succeeded, false otherwise

Description

Users must log in before any work may be performed. This function creates a user session and its corresponding transaction workspace.

This function uses the current network parameters (as specified by GciSetNet) to establish the user’s GemStone session.

Example

BoolType login_example(void)
{
  // assume the netldi on machine lichen been started with -a -g 
  //  so that host userId and host password are not required.
  const char* StoneName    = "gs64stone";
  const char* HostUserId   = "";
  const char* HostPassword = "";
  const char* GemService   = "gemnetobject";
  const char* gsUserName   = "DataCurator";
  const char* gsPassword   = "swordfish";
 
  // GciInit  required before first login
  if (!GciInit()) {
    printf("GciInit failed\n");
    return FALSE;
  }
  GciSetNet(StoneName, HostUserId, HostPassword, GemService);
  BoolType success = GciLogin(gsUserName, gsPassword);
  if (! success) {
    GciErrSType errInfo;
    if (GciErr(&errInfo)) {
      printf("error category "FMT_OID" number %d, %s\n",
         errInfo.category, errInfo.number, errInfo.message);
    }
  }
  return success;
}
 

See Also

GciLoginEx
GciSetNet
GciSetNetEx

GciLoginEx

GciLoginEx_

Start a user session with session configuration

Syntax

BoolType GciLoginEx(
const char gemstoneUsername[ ],
const char gemstonePassword[ ] ,
unsigned int loginFlags,
int haltOnErrNum);

BoolType GciLoginEx_(
const char gemstoneUsername[ ],
const char gemstonePassword[ ] ,
unsigned int loginFlags,
int haltOnErrNum
BoolType * executedSessionInit);

 

Arguments

gemstoneUsername

The user’s GemStone user name (a null-terminated string).

gemstonePassword

The user’s GemStone password (a null-terminated string).

loginFlags

Login flags, as described below

haltOnErrNum

A legacy error number; if nonzero, specifies a value for GEM_HALT_ON_ERROR config parameter.

Result Arguments

executedSessionInit   

Set to TRUE if login succeeded and and GsCurrentSession initialize was executed in the new session.

Return Value

Returns true if login succeeded, false otherwise

Description

This function creates a user session and its corresponding transaction workspace. The current network parameters, as specified by GciSetNet, are used to establish the user’s GemStone session.

Other login attributes are provided by loginFlags. The value of loginFlags should be given using the following GemBuilder mnemonics:

GCI_LOGIN_PW_ENCRYPTED (1) indicates the gemstonePassword is encrypted. When specifying this flag, you must encrypt the password using GciEncrypt.

GCI_LOGIN_IS_SUBORDINATE (2) Creates the new session as a child of the current session. It will be terminated if the current session terminates. The primary use of this is for GciInterface, and is only valid for RPC sessions.

GCI_LOGIN_FULL_COMPRESSION_ENABLED (4) the login will use full compression.

GCI_LOGIN_ERRS_USE_REF_SET (8) sets the OOPs of objects related to errors to be put into the ReferencedSet, rather than the PureExportSet.

GCI_LOGIN_QUIET (0x10) suppresses printing of banner information during login.

GCI_CLIENT_DOES_SESSION_INIT (0x20) after login, the session will manually execute GciPerform(OOP_CLASS_GSCURRENT_SESSION, "initialize", NULL, 0);
otherwise, the VM will automatically executes that code as part of login.

GCI_TS_CLIENT (0x40) the client will use the thread-safe API. Using this flag, GciLoginEx is equivalent to GciTsLogin, from the gcits.hf (not included in this documentation).

GCI_PASSWORDLESS_LOGIN (0x80) specifies login using Kerberos.

GCI_LOGIN_SOLO (0x100) species to login solo, which does not require a Stone to be running.

GCI_WINDOWS_CLIENT (0x200) is use on Windows client application.

GCI_ONETIME_PASSWORD (0x400) the specified password is a one-time security token.

If haltOnErrNum is set to a GemStone error number, and the session encounters the error associated with that error number, the session will halt.

Example

For an example, see GciEncrypt

See Also

GciEncrypt
GciLogin
GciSetNet
GciSetNetEx

GciLogout

GciLogout_

End the current user session.

Syntax

void GciLogout( );

void GciLogout_(
BoolByte getResult );

Arguments

getResult

If True, waits for a reply packet from the Gem; this is the behavior of GciLogout.

If False, the library sends the logout command and closes the connection without waiting for a reply from the gem.

Description

This function terminates the current user session (set by the last GciLogin or GciSetSessionId), and allows GemStone to release all uncommitted objects created by the application program in the corresponding transaction workspace. The current session ID is reset to GCI_INVALID_SESSION_ID, indicating that the application is no longer logged in. (See GciGetSessionId for more information.)

See Also

GciGetSessionId
GciLogin
GciSetSessionId

GciLongJmp

Provides equivalent functionality to the corresponding longjmp() or _longjmp() function.

Syntax

void GciLongJmp(
GciJmpBufSType * jumpBuffer,
int val );

Arguments

jumpBuffer

A pointer to a jump buffer.

Description

Except for the difference in the first argument type, the semantics of this function are the same as for longjmp() on Solaris and _longjmp() on HP-UX.

See Also

GciErr
GciPopErrJump
GciPushErrJump
GciSetErrJump
Gci_SETJMP

GciMoreTraversal

Continue object traversal, reusing a given buffer.

Syntax

BoolType GciMoreTraversal(
GciTravBufType * travBuff);

Arguments

travBuff 

A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType.

Return Value

Returns FALSE if the traversal is not yet completed, but further traversal would cause the travBuffSize to be exceeded. If the travBuffSize is reached before the traversal is complete, you can continue to call GciMoreTraversal to proceed from the point where travBuffSize was exceeded.

Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal.

Description

When the amount of information obtained in a traversal exceeds the amount of memory available to the buffer (as specified with travBuffSize), your application can call GciMoreTraversal repeatedly to break the traversal into manageable amounts of information. The information returned by this function begins with the object report following where the previous unfinished traversal left off. The level value is retained from the initial GciTraverseObjs call.

Generally speaking, an application can continue to call GciMoreTraversal until it has obtained all requested information.

Naturally, GemStone will not continue an incomplete traversal if there is any chance that changes to the database in the intervening period might have invalidated the previous report or changed the connectivity of the objects in the path of the traversal. Specifically, GemStone will refuse to continue a traversal if, in the interval before attempting to continue, you:

  • Modify the objects in the database directly by calling any of the GciStore... or GciAdd... functions;
  • Call one of the Smalltalk message-sending functions GciPerform, GciContinue, or any of the GciExecute... functions.
  • Abort your transaction, thus invalidating any subsequent information from that traversal.

Any attempt to call GciMoreTraversal after one of these events will generate an error.

Note that this holds true across multiple GemBuilder applications sharing the same GemStone session. Suppose, for example, that you were holding on to an incomplete traversal buffer and the user moved from the current application to another, did some work that required executing Smalltalk code, and then returned to the original application. You would be unable to continue the interrupted traversal.

If you attempt to call GciMoreTraversal when no traversal is underway, this function will generate the error GCI_ERR_TRAV_COMPLETED.

During the entire sequence of GciTraverseObjs and GciMoreTraversal calls that constitute a traversal, any single object report will be returned exactly once. Regardless of the connectivity of objects in the GemStone database, only one report will be generated for any non-special object.

The section Organization of the Traversal Buffer describes the organization of traversal buffers in detail.

GciMoreTraversal provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

void moreTraversalExample(void)
{
  // Assumes setup code has been run
 
  OopType rootObj = GciResolveSymbol("AllAccounts", OOP_NIL);
  GciTravBufType *buf = GciTravBufType::malloc(8000);
 
  int totalCount = 0;
  // traverse the AllAccounts collection to 4 levels deep
  BoolType done = GciTraverseObjs(&rootObj, 1, buf, 4);
  while (! done) {
    int objCount = 0;
    GciObjRepHdrSType *rpt = buf->firstReportHdr();
    GciObjRepHdrSType *limit = buf->readLimitHdr();
    while (rpt < limit) {
      objCount++ ;
      rpt = rpt->nextReport();
    }
    totalCount += objCount;
    done = GciMoreTraversal(buf);
  }
  buf->free();
  printf("traversal returned %d total objects\n", totalCount);
}

See Also

GCI_ALIGN
GciFindObjRep
GciObjRepSize_
GciNbMoreTraversal
GciTraverseObjs

GciNbAbort

Abort the current transaction (nonblocking).

Syntax

void GciNbAbort( )

Description

The GciNbAbort function is equivalent in effect to GciAbort. However, GciNbAbort permits the application to proceed with non-GemStone tasks while the transaction is aborted, and GciAbort does not.

See Also

GciAbort
GciBegin
GciNbBegin
GciNbCommit

GciNbBegin

Begin a new transaction (nonblocking).

Syntax

void GciNbBegin( )

Description

The GciNbBegin function is equivalent in effect to GciBegin. However, GciNbBegin permits the application to proceed with non-GemStone tasks while a new transaction is started, and GciBegin does not.

See Also

GciBegin
GciNbAbort
GciNbCommit

GciNbClampedTrav

Traverse an array of objects, subject to clamps (nonblocking).

Syntax

void GciNbClampedTrav(
const OopType * theOops,
int numOops,
GciClampedTravArgsSType * travArgs );

Arguments

theOops

The array of OOPs for the objects to be traversed.

numOops

The number of elements in theOops.

travArgs

Pointer to an instance of GciClampedTravArgsSType. See GciClampedTrav for documentation on the fields in travArgs. On return, the result is in the travBuff field of the travArgs instance of GciClampedTravArgsSType.

Return Value

The GciNbClampedTrav function, unlike GciClampedTrav, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciClampedTrav by using the argument to GciNbEnd.

Description

This function is equivalent in effect to GciClampedTrav. However, GciClampedTrav permits the application to proceed with non-GemStone tasks while a traversal is carried out, and GciClampedTrav does not.

See Also

GciClampedTrav

GciNbCommit

Write the current transaction to the database (nonblocking).

Syntax

void GciNbCommit( )

Return Value

The GciNbCommit function, unlike GciCommit, does not have a return value. However, when the commit operation is complete, you can access a value identical in meaning to the return value of GciCommit by using the argument to GciNbEnd.

Description

This function is equivalent in effect to GciCommit. However, GciNbCommit permits the application to proceed with non-GemStone tasks while the transaction is committed, and GciCommit does not.

See Also

GciCommit
GciNbAbort
GciNbBegin

GciNbContinue

Continue code execution in GemStone after an error (nonblocking).

Syntax

void GciNbContinue(
OopType gsProcess );

Arguments

gsProcess

The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr).

Return Value

The GciNbContinue function, unlike GciContinue, does not have a return value. However, when the continued operation is complete, you can access a value identical in meaning to the return value of GciContinue by using the argument to GciNbEnd.

Description

The GciNbContinue function is equivalent in effect to GciContinue. However, GciNbContinue permits the application to proceed with non-GemStone tasks while the operation continues, and GciContinue does not.

This function sets the GCI_PERFORM_noClientUseraction flag and is disallowed with client user actions.

See Also

GciContinue
GciNbContinueWith

GciNbContinueWith

Continue code execution in GemStone after an error (nonblocking).

Syntax

void GciNbContinueWith (
OopType process,
OopType replaceTopOfStack,
int flags,
GciErrSType * error );

Arguments

gsProcess

The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr).

replaceTopOfStack

If not OOP_ILLEGAL, replace the value at the top of the Smalltalk evaluation stack with this value before continuing. If OOP_ILLEGAL, the evaluation stack is not changed.

flags

Flags to disable or permit asynchronous events and debugging in Smalltalk, as defined for GciPerformNoDebug.

continueWithError

If not NULL, continue execution by signalling this error. This argument takes precedence over replaceTopOfStack.

Description

The GciNbContinueWith function is equivalent in effect to GciContinueWith. However, GciNbContinueWith permits the application to proceed with non-GemStone tasks while the operation continues, and GciContinueWith does not.

See Also

GciContinueWith
GciNbContinue

GciNbEnd

GciNbEnd_

Test the status of nonblocking call in progress for completion.

Syntax

GciNbProgressEType GciNbEnd(
void ** result );

GciNbProgressEType GciNbEnd_(
int64* result);

Arguments

result

The address at which GciNbEnd or GciNbEnd_ should place a pointer to the result of the nonblocking call when it is complete. The actual result is that of the corresponding equivalent blocking GCI call.

With GciNbEnd, the result may be either 4 byte or 8 byte, and the caller must be aware of whether this is 4 byte or 8 byte, and dereference result accordingly on big endian machines.

GciNbEnd_ produces result type of the corresponding blocking GCI call, typically int, BoolType or OopType, and may be accessed by normal C casting without regard to byte order of the CPU.

Return Value

The GciNbEnd function returns an enumerated type. Its value is GCI_RESULT_READY if the outstanding nonblocking call has completed execution and its result is ready, GCI_RESULT_NOT_READY if the call is not complete and there has been no change since the last inquiry, and GCI_RESULT_PROGRESSED if the call is not complete but progress has been made towards its completion.

Description

Once an application calls a nonblocking function, it must call GciNbEnd, GciNbEnd_, or GciNbEndPoll at least once, and must continue to do so until that nonblocking function has completed execution. The intent of the return values is to give the scheduler a hint about whether it is calling one of these functions too often or not often enough.

Once an operation is complete, you are permitted to call GciNbEnd or a related function repeatedly. It returns GCI_RESULT_READY and a pointer to the same result each time, until you call a nonblocking function again. It is an error to call GciNbEnd or a related function before you call any nonblocking functions at all. Use the GciCallInProgress function to determine whether or not there is a GemBuilder call currently in progress.

Example

void nbEnd_example(void)
{
  void *resultPtr;
  GciNbExecuteStr("Globals size", OOP_NIL);
  do {
    // wait for non-blocking result 
    GciHostMilliSleep(1);  
  } while (GciNbEnd(&resultPtr) != GCI_RESULT_READY);
 
  OopType result = *(OopType*)resultPtr;
  BoolType conversionErr = FALSE;
  int gSize = GciOopToI32_(result, &conversionErr);
  if (conversionErr) {
    printf("error in execution\n");
  } else {
    printf("Globals size = %d \n", gSize);
  }
}
 

See Also

GciNbEndPoll
GciCallInProgress

GciNbEndPoll

Test the status of nonblocking call in progress for completion, with timeout.

Syntax

GciNbProgressEType GciNbEndPoll(
int64* result,
int timeoutMs);

Arguments

result  

The address at which GciNbEndPoll should place a pointer to the result of the nonblocking call when it is complete. The actual result is that of the corresponding equivalent blocking GCI call. The result will be 8 bytes, and correct on big endian machines.

Return Value

The GciNbEndPoll function returns an enumerated type. Its value is GCI_RESULT_READY if the outstanding nonblocking call has completed execution and its result is ready, GCI_RESULT_NOT_READY if the call is not complete and there has been no change since the last inquiry, and GCI_RESULT_PROGRESSED if the call is not complete but progress has been made towards its completion.

Description

Once an application calls a nonblocking function, it must call GciNbEndPoll, GciNbEnd, or GciNbEnd_ at least once, and must continue to do so until that nonblocking function has completed execution. The intent of the return values is to give the scheduler a hint about whether it is calling GciNbEndPoll too often or not often enough.

GciNbEndPoll allows you to specify a timeout, and will wait for timeoutMs milliseconds before returning status. This avoids too-frequent polling for long-running code.

Once an operation is complete, you are permitted to call GciNbEndPoll repeatedly. It returns GCI_RESULT_READY and a pointer to the same result each time, until you call a nonblocking function again. It is an error to call GciNbEndPoll before you call any nonblocking functions at all. Use the GciCallInProgress function to determine whether or not there is a GemBuilder call currently in progress.

See Also

GciNbEnd
GciCallInProgress

GciNbExecute

Execute a Smalltalk expression contained in a String object (nonblocking).

Syntax

void GciNbExecute(
OopType source,
OopType symbolList );

Arguments

sourceStr

The OOP of a String containing a sequence of one or more Smalltalk statements to be executed.

symbolList

The OOP of a GemStone symbol list. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

The GciNbExecute function, unlike GciExecute, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecute by using the argument to GciNbEnd.

Description

The GciNbExecute function is equivalent in effect to GciExecute. However, GciNbExecute permits the application to proceed with non-GemStone tasks while the Smalltalk expression is executed, and GciExecute does not.

This function sets the GCI_PERFORM_noClientUseraction flag and is disallowed with client user actions.

See Also

GciExecute
GciNbEnd
GciNbExecuteStr
GciNbExecuteStrFetchBytes
GciNbExecuteStrFromContext
GciNbPerform

GciNbExecuteFromContextDbg_

Execute a Smalltalk expression contained in a String object (nonblocking) as if it were a message sent to an object (nonblocking).

Syntax

void GciNbExecuteFromContextDbg_(
OopType source,
OopType contextObject,
OopType symbolList,
int flags,
ushort environmentId);

Arguments

source

The OOP of a String or Utf8 containing a sequence of one or more Smalltalk statements to be executed.

contextObject

The OOP of a GemStone object to use as the compilation context. If OOP_NO_CONTEXT, the code is compiled as an anonymous method in which self == nil. Otherwise, the compilation is done as if the code is an instance method of the class of contextObj.

symbolList

The OOP of a GemStone symbol list. Smalltalk resolves symbolic references in source code by using symbols that are available from symbolList. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

flags

Values for flags are described in gcicmn.ht,and can include:

  • 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.

environmentId

The compilation environment for method lookup, normally 0.

Return Value

The GciNbExecuteFromContextDbg_ function, unlike GciExecuteFromContext, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecuteFromContext by using the argument to GciNbEnd.

Description

The GciNbExecuteFromContextDbg_ function is equivalent in effect to GciExecuteFromContext. However, GciNbExecuteFromContextDbg_ permits the application to proceed with non-GemStone tasks while the Smalltalk expression is executed, and GciExecuteFromContext does not.

See Also

GciExecuteFromContext
GciExecuteStrFromContext
GciNbEnd
GciNbExecute
GciNbExecuteStr
GciNbExecuteStrFetchBytes
GciNbPerform

GciNbExecuteStr

Execute a Smalltalk expression contained in a C string (nonblocking).

Syntax

void GciNbExecuteStr(
const char source[ ],
OopType symbolList );

Arguments

sourceStr

A null-terminated string containing a sequence of one or more Smalltalk statements to be executed.

symbolList

The OOP of a GemStone symbol list. Smalltalk resolves symbolic references in source code by using symbols that are available from symbolList. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

The GciNbExecuteStr function, unlike GciExecuteStr, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecuteStr by using the argument to GciNbEnd.

Description

The GciNbExecuteStr function is equivalent in effect to GciExecuteStr. However, GciNbExecuteStr permits the application to proceed with non-GemStone tasks while the Smalltalk expression is executed, and GciExecuteStr does not.

See Also

GciExecuteStr
GciNbEnd
GciNbExecute
GciNbExecuteStrFetchBytes
GciNbExecuteStrFromContext
GciNbPerform

GciNbExecuteStrFetchBytes

Execute a Smalltalk expression contained in a C string, returning byte-format results (nonblocking).

Syntax

void GciNbExecuteStrFetchBytes(
const char * sourceStr,
int64 sourceSize,
OopType sourceClass,
OopType contextObject,
OopType symbolList,
ByteType * result,
int64 maxResultSize );

Arguments

sourceStr

A null-terminated string containing a sequence of one or more Smalltalk statements to be executed.

sourceSize

The number of bytes in the source, or -1. If sourceSize is -1, strlen(sourceStr) is used.

sourceClass

The OOP of a class to use for the compilation target for the text in sourceStr, typically OOP_CLASS_STRING, OOP_CLASS_UNICODE7, or OOP_CLASS_Utf8.

contextObject

The OOP of a GemStone object to use as the compilation context. If OOP_NO_CONTEXT, the code is compiled as an anonymous method in which self == nil. Otherwise, the compilation is done as if the code is an instance method of the class of contextObj.

symbolList

The OOP of a GemStone symbol list. Smalltalk resolves symbolic references in source code by using symbols that are available from symbolList. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

result

Array containing the bytes of the result of the execution.

maxResultSize

Maximum size of result.

Return Value

The GciNbExecuteStrFetchBytes function, unlike GciExecuteStrFetchBytes, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecuteStrFetchBytes by using the argument to GciNbEnd.

Description

This function sends an expression (or sequence of expressions) to GemStone for execution. The execution result, which should be a byte format object is returned in the *result buffer.

See Also

GciExecuteStrFetchBytes
GciNbEnd
GciNbExecute
GciNbExecuteStr
GciNbExecuteStrFromContext
GciNbPerform

GciNbExecuteStrFromContext

Execute a Smalltalk expression contained in a C string as if it were a message sent to an object (nonblocking).

Syntax

void GciNbExecuteStrFromContext(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList );

Arguments

sourceStr

A null-terminated string containing a sequence of one or more Smalltalk statements to be executed.

contextObject

The OOP of a GemStone object to use as the compilation context. If OOP_NO_CONTEXT, the code is compiled as an anonymous method in which self == nil. Otherwise, the compilation is done as if the code is an instance method of the class of contextObj.

symbolList

The OOP of a GemStone symbol list. Smalltalk resolves symbolic references in source code by using symbols that are available from symbolList. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

The GciNbExecuteStrFromContext function, unlike GciExecuteStrFromContext, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecuteStrFromContext by using the argument to GciNbEnd.

Description

The GciNbExecuteStrFromContext function is equivalent in effect to GciExecuteStrFromContext. However, GciNbExecuteStrFromContext permits the application to proceed with non-GemStone tasks while the Smalltalk expression is executed, and GciExecuteStrFromContext does not.

See Also

GciExecuteStrFromContext
GciNbEnd
GciNbExecute
GciNbExecuteStr
GciNbExecuteStrFetchBytes
GciNbPerform

GciNbExecuteStrTrav

First execute a Smalltalk expression contained in a C string as if it were a message sent to an object, then traverse the result of the execution (nonblocking).

Syntax

void GciNbExecuteStrTrav(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList,
GciClampedTravArgsSType * travArgs );

Arguments

sourceStr

A null-terminated string containing a sequence of one or more Smalltalk statements to be executed.

contextObject

The OOP of a GemStone object to use as the compilation context. If OOP_NO_CONTEXT or OOP_ILLEGAL, the code is compiled as an anonymous method in which self == nil. Otherwise, the compilation is done as if the code is an instance method of the class of contextObj.

symbolList

The OOP of a GemStone symbol list. Smalltalk resolves symbolic references in source code by using symbols that are available from symbolList. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

travArgs

Pointer to an instance of GciClampedTravArgsSType. See GciExecuteStrTrav for field definitions.

Return Value

The GciNbExecuteStrTrav function, unlike GciExecuteStrTrav, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciExecuteStrTrav by using the argument to GciNbEnd.

Description

The GciNbExecuteStrTrav function is equivalent in effect to GciExecuteStrTrav. However, GciNbExecuteStrTrav permits the application to proceed with non-GemStone tasks while the traversal is completed, and GciExecuteStrTrav does not.

See Also

GciExecuteStrTrav includes information details on traversal.
GciNbEnd
GciNbExecute
GciPerformTraverse

GciNbLoginEx

Start a user session with session configuration (nonblocking)

Syntax

BoolType GciNbLoginEx(
const char gemstoneUsername[ ],
const char gemstonePassword[ ] ,
unsigned int loginFlags,
int haltOnErrNum);

Arguments

gemstoneUsername

The user’s GemStone user name (a null-terminated string).

gemstonePassword

The user’s GemStone password (a null-terminated string).

loginFlags

Login flags, as described below

haltOnErrNum

A legacy error number; if nonzero, specifies a value for GEM_HALT_ON_ERROR config parameter.

Return Value

Returns true if login succeeded, false otherwise

Description

This function creates a user session and its corresponding transaction workspace. The current network parameters , as specified by GciSetNet, are used to establish the new GemStone session.

Other login attributes are provided by loginFlags. The value of loginFlags should be given using the GemBuilder mnemonics descibed under GciLoginEx.

If haltOnErrNum is set to a GemStone error number, and the session encounters the error associated with that error number, the new session will halt.

Once this call is invoked, the current session is set to the not-yet-logged in session. Calls to GciNbEnd apply to the not-yet-logged in session.

See Also

GciLoginEx
GciNbEnd

GciNbMoreTraversal

Continue object traversal, reusing a given buffer (nonblocking).

Syntax

void GciNbMoreTraversal(
GciTravBufType * travBuff);

Arguments

travBuff

A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType.

Return Value

The GciNbMoreTraversal function, unlike GciMoreTraversal, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciMoreTraversal by using the argument to GciNbEnd.

Description

The GciNbMoreTraversal function is equivalent in effect to GciMoreTraversal. However, GciNbMoreTraversal permits the application to proceed with non-GemStone tasks while the traversal is completed, and GciMoreTraversal does not.

GciNbMoreTraversal provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.

See Also

GciMoreTraversal
GciNbTraverseObjs
GciObjRepSize_
GciTraverseObjs

GciNbPerform

Send a message to a GemStone object (nonblocking).

Syntax

void GciNbPerform(
OopType receiver,
const char selectorStr[ ],
const OopType args[ ],
int numArgs );

Arguments

receiver

The OOP of the receiver of the message.

selectorStr

A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

Return Value

The GciNbPerform function, unlike GciPerform, does not have a return value. However, when the performed operation is complete, you can access a value identical in meaning to the return value of GciPerform by using the argument to GciNbEnd.

Description

The GciNbPerform function is equivalent in effect to GciPerform. However, GciNbPerform permits the application to proceed with non-GemStone tasks while the message is executed, and GciPerform does not.

See Also

GciNbEnd
GciNbExecute
GciNbPerformNoDebug
GciNbPerformTrav
GciPerform

GciNbPerformFetchBytes

Send a message to a GemStone object, returning byte results (nonblocking).

Syntax

void GciNbPerformFetchBytes(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
ByteType * result,
ssize_t maxResultSize);

Arguments

receiver

The OOP of the receiver of the message.

selector

A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

result

Array containing the bytes of the result of the execution.

maxResultSize

Maximum size of result.

Return Value

The GciNbPerformFetchBytes function, unlike GciPerformFetchBytes, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciPerformFetchBytes by using the argument to GciNbEnd.

Description

This function sends a message (that is, the selector along with any keyword arguments and their corresponding values) to the specified receiver (an object in the GemStone database), and puts the result, which should be a byte format object, in the *result buffer.

See Also

GciNbExecuteStrFetchBytes
GciNbPerform

GciNbPerformNoDebug

Send a message to a GemStone object, and temporarily disable debugging (nonblocking).

Syntax

void GciNbPerformNoDebug(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
int flags );

Arguments

receiver

The OOP of the receiver of the message.

selector

A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

flags

Flags to disable or permit asynchronous events and debugging in Smalltalk. Use one or more of the GemBuilder mnemonics described under GciPerformNoDebug.

Return Value

The GciNbPerformNoDebug function, unlike GciPerformNoDebug, does not have a return value. However, when the performed operation is complete, you can access a value identical in meaning to the return value of GciPerformNoDebug by using the argument to GciNbEnd.

Description

The GciNbPerformNoDebug function is equivalent in effect to GciPerformNoDebug. However, GciNbPerformNoDebug permits the application to proceed with non-GemStone tasks while the message is executed, and GciPerformNoDebug does not.

See Also

GciNbEnd
GciNbExecute
GciNbPerform
GciPerformNoDebug

GciNbPerformTrav

First send a message to a GemStone object, then traverse the result of the message (nonblocking).

Syntax

void GciNbPerformTrav(
OopType receiver,
const char * selector,
const OopType * args,
int numArgs,
GciClampedTravArgsSType * travArgs );

Arguments

receiver

The OOP of the receiver of the message.

selector

A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

travArgs

Pointer to an instance of GciClampedTravArgsSType. See GciClampedTrav for documentation of the fields in travArgs. On return, the results are in the first object in the resulting travBuffs field.

Return Value

The GciNbPerformTrav function, unlike GciPerformTrav, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciPerformTrav by using the argument to GciNbEnd.

Description

The GciNbPerformTrav function is equivalent in effect to GciPerformTrav. However, GciNbStoreTrav permits the application to proceed with non-GemStone tasks while the traversal is done, and GciPerformTrav does not.

See Also

GciPerformTrav
GciNbPerform
GciClampedTrav

GciNbStoreTrav

Stores multiple traversal buffer values in objects (nonblocking).

Syntax

void GciNbStoreTrav(
GciTravBufType * travBuff,
int behaviorFlag );

Arguments

travBuff

A buffer that contains the object reports to be stored. The first element in the buffer is an integer that indicates how many bytes are stored in the buffer. The remainder of the traversal buffer consists of a series of object reports, each of which is of type GciObjRepSType.

behaviorFlag

A flag specifying whether the values returned by GciStoreTrav should be added to the values in the traversal buffer or should replace the values in the traversal buffer.

Flag values, defined in the gci.ht header file, are GCI_STORE_TRAV_NSC_ADD (add to the traversal buffer) and GCI_STORE_TRAV_NSC_REP (replace traversal buffer contents).

Description

The GciNbStoreTrav function is equivalent in effect to GciStoreTrav. However, GciNbStoreTrav permits the application to proceed with non-GemStone tasks while the traversals are stored, and GciStoreTrav does not.

GciNbStoreTrav provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.

See Also

GciNbEnd
GciNbMoreTraversal
GciNbStoreTrav
GciNbStoreTravDoTrav_
GciNbTraverseObjs
GciStoreTrav

GciNbStoreTravDo_

Store multiple traversal buffer values in objects, execute the specified code, and return the resulting object (non-blocking).

Syntax

void GciNbStoreTravDo_(
GciStoreTravDoArgsSType * storeTravArgs);

Arguments

storeTravArgs

An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_

Return Value

Unlike GciStoreTravDo_, the GciNbStoreTravDo_ function does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciStoreTravDo_ by using the argument to GciNbEnd.

Description

The GciNbStoreTravDo_ function is equivalent in effect to GciStoreTravDo_. However, GciNbStoreTravDo_ permits the application to proceed with non-GemStone tasks while the traversal is done, and GciStoreTravDo_ does not.

See Also

GciNbEnd
GciNbMoreTraversal
GciNbStoreTrav
GciNbStoreTravDoTrav_
GciStoreTravDo_

GciNbStoreTravDoTrav_

Combine in a single function the calls to GciNbStoreTravDo_ and GciNbClampedTrav, to store multiple traversal buffer values in objects, execute the specified code, and traverse the result object (non-blocking).

Syntax

void GciNbStoreTravDoTrav_(
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );

Arguments

storeTravArgs   

An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_.

clampedTravArgs

An instance of GciClampedTravArgsSType. For details, refer to the discussion of GciClampedTrav.

Return Value

The GciNbStoreTravDoTrav_ function, unlike GciStoreTravDoTrav_, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciStoreTravDoTrav_ by using the argument to GciNbEnd.

Description

This function allows the client to execute behavior on the Gem and return the traversal of the result object in a single network round-trip.

The GciNbStoreTravDoTrav_ function is equivalent in effect to GciStoreTravDoTrav_. However, GciNbStoreTravDoTrav_ permits the application to proceed with non-GemStone tasks while the traversals are stored, and GciStoreTravDoTrav_ does not.

See Also

GciNbEnd
GciNbMoreTraversal
GciNbStoreTrav
GciNbStoreTravDo_
GciNbStoreTravDoTravRefs_
GciStoreTravDoTrav_

GciNbStoreTravDoTravRefs_

Combine in a single function modifications to session sets, traversal of objects to the server, optional Smalltalk execution, and traversal to the client of changed objects and (optionally) the result object (non blocking).

Syntax

void GciNbStoreTravDoTravRefs_(
const OopType * oopsNoLongerReplicated,
int numNotReplicated,
const OopType * oopsGcedOnClient,
int numGced,
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );

Arguments

oopsNoLongerReplicated

An Array of objects to be removed from the PureExportSet and added to the ReferencedSet.

numNotReplicated

The number of elements in oopsNoLongerReplicated.

oopsGcedOnClient

An Array of objects to be removed from both the PureExportSet and ReferencedSet.

numGced   

The number of elements in oopsGcedOnClient.

storeTravArgs

An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_.

clampedTravArgs

An instance of GciClampedTravArgsSType. For details, see the discussion of GciClampedTrav on here.

Return Value

The GciNbStoreTravDoTravRefs_ function, unlike GciStoreTravDoTravRefs_, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciStoreTravDoTravRefs_ by using the argument to GciNbEnd

Description

This function allows the client to modify the PureExportSet and ReferencedSet, modify or create any number of objects on the server, execute behavior on the Gem, and return the traversal of the result object, all in a single network round-trip.

The GciNbStoreTravDoTravRefs_ function is equivalent in effect to GciStoreTravDoTravRefs_. However, GciNbStoreTravDoTravRefs_ permits the application to proceed with non-GemStone tasks while the traversals are stored, and GciStoreTravDoTravRefs_ does not.

See Also

GciNbEnd
GciNbMoreTraversal
GciNbStoreTrav
GciNbStoreTravDo_
GciNbStoreTravDoTrav_
GciStoreTravDoTravRefs_

GciNbTraverseObjs

Traverse an array of GemStone objects (nonblocking).

Syntax

void GciNbTraverseObjs(
const OopType theOops[ ],
int numOops,
GciTravBufType * travBuff,
int level );

Arguments

theOops

An array of OOPs representing the objects to be traversed.

numOops

The number of elements in theOops.

travBuff

A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType.

level

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

Return Value

The GciNbTraverseObjs function, unlike GciTraverseObjs, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciTraverseObjs by using the argument to GciNbEnd.

Description

The GciNbTraverseObjs function is equivalent in effect to GciTraverseObjs. However, GciNbTraverseObjs permits the application to proceed with non-GemStone tasks while the traversal is completed, and GciTraverseObjs does not.

GciNbTraverseObjs provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.

See Also

GciNbEnd
GciNbMoreTraversal
GciNbStoreTrav
GciNbStoreTravDo_
GciNbStoreTravDoTrav_
GciTraverseObjs

GciNewByteObj

Create and initialize a new byte object.

Syntax

OopType GciNewByteObj(
OopType aClass,
const ByteType * value,
int64 valueSize );

Arguments

aClass   

The OOP of the class of which the new object is an instance. aClass must be a class whose format is BYTE.

value   

Pointer to an array of byte values to be stored in the newly-created object.

valueSize

The number of byte values in value.

Return Value

The OOP of the newly created object.

Description

Returns a new instance of aClass, of size valueSize, and containing a copy of the bytes located at value. Equivalent to GciNewOop followed by GciStoreBytes. aClass must be a class whose format is Bytes.

See Also

GciNewCharObj
GciNewOop
GciNewString

GciNewCharObj

Create and initialize a new character object.

Syntax

OopType GciNewCharObj(
OopType aClass,
const char * cString );

Arguments

aClass   

The OOP of the class of which the new object is an instance. aClass must be a class whose format is BYTE.

cString   

Pointer to an array of characters to be stored in the newly-created object. The terminating '\0' character is not stored.

Return Value

The OOP of the newly-created object.

Description

Returns a new instance of aClass which has been initialized to contain the bytes of cString, excluding the null terminator.

See Also

GciNewByteObj
GciNewOop
GciNewString

GciNewDateTime

Create and initialize a new instance of DateTime or a subclass of DateTime.

Syntax

OopType GciNewDateTime(
OopType theClass,
const GciDateTimeSType * datetimeVal );

Arguments

theClass   

The class of the object to be created, which must be OOP_CLASS_DATE_TIME or a subclass.

datetimeVal   

The time value to be assigned to the newly-created object.

Return Value

Returns the OOP of the newly-created object. If an error occurs, returns OOP_ILLEGAL.

Description

Creates a new instance of theClass having the value that timeVal points to. For details on GciDateTimeSType, see GciDateTimeSType.

See Also

GciNewDateAndTime
GciNewDateAndTimePosix

GciNewDateAndTime

Create and initialize a new instance of DateAndTime.

Syntax

OopType GciNewDateTime(
const GciDateAndTime* dateAndTimeVal );

Arguments

dateAndTimeVal   

The date and time value to be assigned to the newly-created object.

Return Value

Returns the OOP of the newly-created object. If an error occurs, returns OOP_ILLEGAL.

Description

Creates a new instance of DateAndTime having the value that dateAndTimeVal points to. For details on GciDateAndTime, see GciDateAndTime.

See Also

GciNewDateTime
GciNewDateAndTimePosix

GciNewDateAndTimePosix

Create and initialize a new instance of DateAndTime.

Syntax

OopType GciNewDateTimePosix(
int64 microseconds,
int offsetSeconds);

Arguments

microseconds

The number of microseconds UTC since the start of January 1, 1900

offsetSeconds

The number of seconds of the offset from UTC (timeszone)

Return Value

Returns the OOP of the newly-created object. If an error occurs, returns OOP_ILLEGAL.

Description

Creates a new instance of DateAndTime with the given posix seconds and offset.

See Also

GciNewDateTime
GciNewDateAndTime

GciNewOop

Create a new GemStone object.

Syntax

OopType GciNewOop(
OopType aClass );

Arguments

aClass

The OOP of the class of which the new object is an instance. This may be the OOP of a class that you have created, or it may be one of the Smalltalk kernel classes, such as OOP_CLASS_STRING for an object of class String. It may not be Symbol or DoubleByteSymbol. See $GEMSTONE/include/gcioop.ht for the C constants that are defined for GemStone kernel classes.

Return Value

Returns the OOP of the new object. In case of error, this function returns OOP_NIL.

Description

This function creates a new object of the specified class and returns the object’s OOP. It cannot be used to create instances of Symbol or DoubleByteSymbol.

Example

OopType newOop_example(void)
{
  // create a new instance of String
  OopType result = GciNewOop(OOP_CLASS_STRING);
  return result;
}
 

See Also

GciNewOop
GciNewString
GciNewSymbol
GciNewUtf8String

GciNewOops

Create multiple new GemStone objects.

Syntax

void GciNewOops(
int numOops,
const OopType classes[ ],
const int64 idxSize[ ],
OopType result[ ] );

Arguments

numOops

The number of new objects to be created.

classes   

An Array of the OOPs of the classes of each new object, of which the new object is an instance. This may be the OOP of a class that you have created, or it may be one of the Smalltalk kernel classes, such as OOP_CLASS_STRING for an object of class String. It may not be Symbol or DoubleByteSymbol. See $GEMSTONE/include/gcioop.ht for the C constants that are defined for GemStone kernel classes.

idxSize   

For each new object, the number of its indexed variables. If the specified oclass of an object is not indexable, its idxSize is ignored.

result   

An array of the OOPs of the new objects created with this function.

Return Value

If an error is encountered, this function will stop at the first error and the contents of the result array will be undefined.

Description

This function creates multiple objects of the specified classes and sizes, and returns the OOPs of the new objects.

Each OOP in classes may be the OOP of a class that you have created, or it may be one of the Smalltalk kernel classes, such as OOP_CLASS_STRING for an object of class String. This function cannot be used to create instances of Symbol or DoubleByteSymbol. If classes contains the OOP of a class with special implementation (such as Boolean), then the corresponding element in result is OOP_NIL. See $GEMSTONE/include/gcioop.ht for the C constants that are defined for GemStone kernel classes.

GciNewOops generates an error when either of the following conditions is TRUE for any object:

  • idxSize < 0
  • (idxSize + number_of_named_instance_variables) > maxSmallInt

Example

void newOops_example(void)
{
  enum { num_objs = 3 };
  OopType classes[num_objs];
  classes[0] = OOP_CLASS_STRING;
  classes[1] = OOP_CLASS_IDENTITY_SET;
  classes[2] = OOP_CLASS_ARRAY;
 
  int64 sizes[num_objs];
  sizes[0] = 50;
  sizes[1] = 0;   /* ignored for NSCs anyway */
  sizes[2] = 3;
 
  OopType newObjs[num_objs];
 
  GciNewOops(num_objs, classes, sizes, newObjs);
  GciErrSType errInfo;
  if (GciErr(&errInfo)) {
    printf("error category "FMT_OID" number %d, %s\n",
         errInfo.category, errInfo.number, errInfo.message);
  } else {
    printf("objIds of new objects are "FMT_OID" "FMT_OID" "FMT_OID"\n",
     newObjs[0], newObjs[1], newObjs[2]);
  }
}
 

See Also

GciNewOop
GciNewString
GciNewSymbol
GciNewUtf8String

GciNewOopUsingObjRep

Create a new GemStone object from an existing object report.

Syntax

void GciNewOopUsingObjRep(
GciObjRepSType * anObjectReport );

Arguments

anObjectReport

Pointer to an object report, which will be modified to contains the OOP of the new object (hdr.objId), the ID of the object’s security policy (hdr.objectSecurityPolicyId), the number of named instance variables in the object (hdr.namedSize), the updated number of the object’s indexed variables (hdr.idxSize), and the object’s complete size (the sum of its named and unnamed variables, hdr.objSize).

Description

This function allows you to submit an object report that creates a GemStone object and specifies the values of its instance variables. You can use this function to define a String, pointer, or NSC object with known OOPs.

The object report consists of two parts: a header (a GciObjRepHdrSType structure) followed by a value buffer (an array of values of the object’s instance variables). For more information on object reports, see Object Report Structure - GciObjRepSType.

GciNewOopUsingObjRep provides automatic byte swizzling for Float and SmallFloat objects. (For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.)

Error Conditions

In addition to general GemBuilder error conditions, this function generates an error if any of the following conditions exist:

  • If (idxSize < 0)
  • If (idxSize + namedSize) > maxSmallInt
  • If firstOffset > (objSize + 1)
  • For pointer objects and NSCs, if valueBuffSize is not divisible by 4
  • If the specified oclass is not the OOP of a Smalltalk class object
  • If the specified oclass and implementation (objImpl) do not agree
  • If objId is a Float or SmallFloat, then startIndex must be one and valueBuffSize must be the actual size for the class of objId.

Note that you cannot use this function to create new special objects (instances of SmallInteger, Character, Boolean, SmallDouble, or UndefinedObject).

Example

void newOopUsingObjRep_example(void)
{
  int arrSize = 100;
  size_t bodySize = sizeof(OopType) * arrSize ;
  size_t rptSize = GCI_ALIGN(sizeof(GciObjRepSType) + bodySize );
  GciObjRepSType *rpt = (GciObjRepSType*) malloc(rptSize);
  if (rpt == NULL) {
    printf("malloc failure\n");
    return;
  }
  rpt->hdr.objId = OOP_NIL; // ignored by GciNewOopUsingObjRep
  rpt->hdr.oclass = OOP_CLASS_ARRAY;
  rpt->hdr.setObjImpl(GC_FORMAT_OOP);
  rpt->hdr.segmentId = WORLD_RW_SEGMENT_ID ;
  rpt->hdr.firstOffset = 1;
  rpt->hdr.namedSize = 0;    // ignored by GciNewOopUsingObjRep
  rpt->hdr.setIdxSize( arrSize );
  rpt->hdr.valueBuffSize = bodySize ;
 
  OopType *body = rpt->valueBufferOops();
  for (int i = 0; i < arrSize; i += 1)  {
    body[i] = GciI32ToOop(i);
  }
  GciNewOopUsingObjRep(rpt);
 
  GciErrSType errInfo;
  if (GciErr(&errInfo)) {
    printf("error category "FMT_OID" number %d, %s\n",
       errInfo.category, errInfo.number, errInfo.message);
  }
}

See Also

GciNewOops
GciNewString
GciNewSymbol
GciNewUtf8String
GciNewString

GciNewString

Create a new String object from a C character string.

Syntax

OopType GciNewString(
const char * cString );

Arguments

cString

Pointer to a character string.

Return Value

The OOP of the newly created object.

Description

Returns a new instance of OOP_CLASS_STRING with the value that cString points to.

GciNewSymbol

Create a new Symbol object from a C character string.

Syntax

OopType GciNewSymbol(
const char * cString );

Arguments

cString   

Pointer to a character string.

Return Value

The OOP of the newly-created object.

Description

Returns a new instance of OOP_CLASS_SYMBOL with the value that cString points to.

GciNewUtf8String

GciNewUtf8String_

Create a new Unicode string object from a UTF-8 encoded C character string.

Syntax

OopType GciNewUtf8String(
const char * unicodeCString,
BoolType utf8OrUnicode );

OopType GciNewUtf8String_(
const char * unicodeCString,
size_t nBytes,
BoolType utf8OrUnicode );

Arguments

unicodeCString

Pointer to a null-terminated UTF-8 encoded character string.

nBytes

The length in bytes of the UTF-8 encoded character string.

utf8OrUnicode

Boolean indicating whether to create an instance of Utf8 or of a Unicode class. If utf8OrUnicode = 0, return an instance of Utf8. If utf8OrUnicode=1, return an instance of Unicode7, Unicode16, or Unicode32, the minimal character size required to represent unicodeCString.

Return Value

The OOP of the newly created object.

Description

Returns a new instance of Utf8, Unicode7, Unicode16, or Unicode32, with the value that the UTF-8 encoded unicodeCString points to.

With the GciNewUtf8String_ option, you provide the length of the C string; with GciNewUtf8String, strlen() is used to compute the size.

GciNscIncludesOop

Determines whether the given OOP is present in the specified unordered collection.

Syntax

BoolType GciNscIncludesOop(
OopType theNsc,
OopType theOop );

Arguments

theNsc

The unordered collection in which to search.

theOop

The OOP to search for.

Return Value

True if the OOP was found; false otherwise.

Description

GciNscIncludesOop searches the specified unordered collection to determine if it includes the specified object. It is equivalent to the GemStone Smalltalk method UnorderedCollection >> includesIdentical:.

Example

BoolType nscIncludesOop_example(OopType nscOop, OopType anOop)
{
  if (!GciIsKindOfClass(nscOop, OOP_CLASS_IDENTITY_BAG) ) {
    printf("first argument is not an Nsc\n");
    return FALSE; /* error: nscOop is not an NSC */
  }
 
  return GciNscIncludesOop(nscOop, anOop);
}
 

See Also

GciAddOopToNsc
GciAddOopsToNsc
GciRemoveOopFromNsc
GciRemoveOopsFromNsc

GciObjExists

Determine whether or not a GemStone object exists.

Syntax

BoolType GciObjExists(
OopType theObject );

Arguments

theObject  

The OOP of an object.

Return Value

Returns TRUE if theObject exists, FALSE otherwise.

Description

This function tests an OOP to see if the object to which it points is a valid object.

GciObjInCollection

Determine whether or not a GemStone object is in a Collection.

Syntax

BoolType GciObjInCollection(
OopType anObj,
OopType aCollection );

Arguments

anObj   

The OOP of an object for which to check.

aCollection

The OOP of a collection.

Return Value

Returns TRUE if anObj exists in aCollection, FALSE otherwise.

Description

Searches the specified collection for the specified object. If aCollection is an NSC (such as a Bag or Set), this is a tree lookup. If aCollection is a kind of Array or String, this is a sequential scan. This function is equivalent to the GemStone Smalltalk method Object >> in:.

GciObjIsCommitted

Determine whether or not an object is committed.

Syntax

BoolType GciObjIsCommitted(
OopType theOop );

Arguments

theOop   

The OOP of an object.

Return Value

GciObjIsCommitted returns TRUE if the object theOop is committed, FALSE otherwise.

Description

The GciObjIsCommitted function determines if the given object is committed or not.

See Also

GciObjExists

GciObjRepSize_

Find the number of bytes in an object report.

Syntax

size_t GciObjRepSize_(anObjectReport)
const GciObjRepHdrSType * anObjectReport;

Arguments

anObjectReport

A pointer to an object report returned by GciFindObjRep.

Return Value

Returns the size of the specified object report.

Description

This function calculates the number of bytes in an object report. Before your application allocates memory for a copy of the object report, it can call this function to obtain the size of the report.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

void objRepSize_example(void)
{
  OopType rootObj = GciResolveSymbol("AllAccounts", OOP_NIL);
  GciTravBufType *buf = GciAllocTravBuf(8000);
 
  GciTraverseObjs(&rootObj, 1, buf, 10);
  GciObjRepHdrSType *rpt = buf->firstReportHdr();
  GciObjRepHdrSType *limit = buf->readLimitHdr();
  if (rpt < limit) {
    size_t reportSize = GciObjRepSize_(rpt);
    printf("size of first report is %ld bytes\n", reportSize);
  } else {
    printf("error, GciTraverseObjs returned empty buffer\n");
  }
}

See Also

GciFindObjRep
GciMoreTraversal
GciTraverseObjs

GCI_OOP_IS_BOOL

(MACRO) Determine whether or not a GemStone object represents a GemStone Smalltalk Boolean.

Syntax

BoolType GCI_OOP_IS_BOOL(theOop)

Arguments

theOop 

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a Boolean, FALSE otherwise.

Description

This macro tests to see if theOop represents a Boolean object.

See Also

GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SmallTime
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_CHAR

(MACRO) Determine whether or not a GemStone object represents a Character.

Syntax

BoolType GCI_OOP_IS_CHAR(theOop)

Arguments

theOop

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a GemStone Character, FALSE otherwise.

Description

This macro tests to see if theOop represents a Character.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SmallTime
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_SmallDate

(MACRO) Determine whether or not a GemStone object represents a SmallDate.

Syntax

BoolType GCI_OOP_IS_SmallDate(theOop)

Arguments

theOop

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a SmallDate, FALSE otherwise.

Description

This macro tests to see if theOop represents a SmallDate.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SmallTime
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_SmallDateAndTime

(MACRO) Determine whether or not a GemStone object represents a SmallDateAndTime.

Syntax

BoolType GCI_OOP_IS_SmallDateAndTime(theOop)

Arguments

theOop

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a SmallDateAndTime, FALSE otherwise.

Description

This macro tests to see if theOop represents a SmallDateAndTime.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SmallTime
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_SMALL_DOUBLE

(MACRO) Determine whether or not a GemStone object represents a SmallDouble.

Syntax

BoolType GCI_OOP_IS_SMALL_DOUBLE(theOop)

Arguments

theOop

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a SmallDouble, FALSE otherwise.

Description

This macro tests to see if theOop represents a SmallDouble.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SmallTime
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_SMALL_FRACTION

(MACRO) Determine whether or not a GemStone object represents a SmallFraction.

Syntax

BoolType GCI_OOP_IS_SMALL_FRACTION(theOop)

Arguments

theOop

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a SmallFraction, FALSE otherwise.

Description

This macro tests to see if theOop represents a SmallFraction.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SmallTime
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_SMALL_INT

(MACRO) Determine whether or not a GemStone object represents a SmallInteger.

Syntax

BoolType GCI_OOP_IS_SMALL_INT(theOop)

Arguments

theOop 

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a SmallInteger, FALSE otherwise.

Description

This macro tests to see if theOop represents a SmallInteger.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SmallTime
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_SmallScaledDecimal

(MACRO) Determine whether or not a GemStone object represents a SmallScaledDecimal.

Syntax

BoolType GCI_OOP_IS_SmallScaledDecimal(theOop)

Arguments

theOop

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a SmallScaledDecimal, FALSE otherwise.

Description

This macro tests to see if theOop represents a SmallScaledDecimal.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallTime
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_SmallTime

(MACRO) Determine whether or not a GemStone object represents a SmallTime.

Syntax

BoolType GCI_OOP_IS_SmallTime(theOop)

Arguments

theOop

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object represents a SmallTime, FALSE otherwise.

Description

This macro tests to see if theOop represents a SmallTime.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SPECIAL

GCI_OOP_IS_SPECIAL

(MACRO) Determine whether or not a GemStone object has a special representation.

Syntax

BoolType GCI_OOP_IS_SPECIAL(theOop)

Arguments.

theOop 

The OOP of the object to test.

Return Value

A C Boolean value. Returns TRUE if the object has a special representation, FALSE otherwise.

Description

This macro tests to see if theOop has a special representation. GemStone specials are objects in which the OOP encodes the value, including Boolean, Character, SmallInteger, SmallDouble, and SmallFraction.

See Also

GCI_OOP_IS_BOOL
GCI_OOP_IS_CHAR
GCI_OOP_IS_SmallDate
GCI_OOP_IS_SmallDateAndTime
GCI_OOP_IS_SMALL_DOUBLE
GCI_OOP_IS_SMALL_FRACTION
GCI_OOP_IS_SMALL_INT
GCI_OOP_IS_SmallScaledDecimal
GCI_OOP_IS_SmallTime

GciOopToBool

Convert a Boolean object to a C Boolean value.

Syntax

BoolType GciOopToBool(
OopType theOop );

Arguments

theOop 

The OOP of the Boolean object to be translated into a C Boolean value.

Return Value

Returns the C Boolean value that corresponds to the GemStone object. In case of error, this function returns FALSE.

Description

This function translates a GemStone Boolean object into the equivalent C Boolean value.

Example

BoolType oopToBoolExample(OopType anObj)
{
  BoolType aBool = GciOopToBool(anObj);
 
  GciErrSType errInfo;
  if (GciErr(&errInfo)) {
    // argument was not a Boolean
    printf("error category "FMT_OID" number %d, %s\n",
       errInfo.category, errInfo.number, errInfo.message);
    return 0;
  }
  return aBool;
}
 

See Also

GCI_BOOL_TO_OOP

GCI_OOP_TO_BOOL

(MACRO) Convert a Boolean object to a C Boolean value.

Syntax

GCI_OOP_TO_BOOL(theOop)

Arguments

theOop

The OOP of the Boolean object to be translated into a C Boolean value.

Return Value

A C Boolean value. Returns the C Boolean value that corresponds to the GemStone object. In case of error, this macro returns FALSE.

Description

This macro translates a GemStone Boolean object into the equivalent C Boolean value.

Provided for compatibility only. New code should use GciOopToBool. For the definition of GCI_OOP_TO_BOOL, see $GEMSTONE/include/gcicmn.ht

See Also

GCI_BOOL_TO_OOP

GciOopToChar16

Convert a Character object to a 16-bit C character value.

Syntax

unsigned int GciOopToChar16(
OopType theOop );

Arguments

theOop 

The OOP of the Character object to be translated into a 16-bit C character value.

Return Value

Returns the 16-bit C character value that corresponds to the GemStone object. In case of error, this function returns zero.

Description

This function translates a GemStone Character object into the equivalent 16-bit C character value.

See Also

GciOopToChar32
GciOopToChr

GciOopToChar32

Convert a Character object to a 32-bit C character value.

Syntax

unsigned int GciOopToChar32(
OopType theOop);

Arguments

theOop 

The OOP of the Character object to be translated into a 32-bit C character value.

Return Value

Returns the 32-bit C character value that corresponds to the GemStone object. In case of error, this function returns zero.

Description

This function translates a GemStone Character object into the equivalent 32-bit C character value.

See Also

GciOopToChar16
GciOopToChr

GciOopToChr

Convert a Character object to a C character value.

Syntax

char GciOopToChr(
OopType theOop );

Arguments

theOop  

The OOP of the Character object to be translated into a C character value.

Return Value

Returns the C character value that corresponds to the GemStone object. In case of error, this function returns zero.

Attempting to convert a GemStone Character that is outside the range of C characters will result in an error.

Description

This function translates a GemStone Character object into the equivalent C character value.

Example

BoolType oopToChr_example(void)
{
  OopType theOop = GCI_CHR_TO_OOP('a'); 
  int aChar = GciOopToChr(theOop);
  if ( aChar == 0 ) {
    printf("GciOopToChr failed\n"); 
    return false;
    }
    return (aChar == (int) 'a');
} 

See Also

GCI_CHR_TO_OOP
GciOopToChar16
GciOopToChar32
GCI_OOP_TO_CHR

GCI_OOP_TO_CHR

(MACRO) Convert a Character object to a C character value.

Syntax

GCI_OOP_TO_CHR(theOop)

Arguments

theOop 

The OOP of the Character object to be translated into a C character value.

Return Value

The GCI_OOP_TO_CHR macro returns the C character value that corresponds to the GemStone object. In case of error, it returns zero.

Description

Provided for compatibility only. New code should use GciOopToChr or GciOopToChar16.

See Also

GciOopToChar16
GciOopToChr

GciOopToFlt

Convert a SmallDouble, Float, or SmallFloat object to a C double.

Syntax

double GciOopToFlt(
OopType theObject );

Arguments

theObject 

The OOP of the specified SmallDouble, Float, or SmallFloat object.

Return Value

Returns the C double precision value that corresponds to the GemStone object. In case of any error other than HOST_ERR_INEXACT_PRECISION, this function returns a PlusQuietNaN.

Description

This function translates a GemStone Float object into the equivalent C double precision value.

If your C compiler’s floating point package doesn’t have a representation that corresponds to one of the values listed below, GciOopToFlt may generate the following errors when converting GemStone Float objects into C values:

HOST_ERR_INEXACT_PRECISION
when called to convert a number whose precision exceeds that of the C double type

HOST_ERR_MAGNITUDE_OUT_OF_RANGE
when called to convert a number whose exponent is too large (or small) to be held in a C double precision value

HOST_ERR_NO_PLUS_INFINITY
when called to convert a value of positive infinity

HOST_ERR_NO_MINUS_INFINITY
when called to convert a value of negative infinity

HOST_ERR_NO_PLUS_QUIET_NAN
when called to convert a positive quiet NaN

HOST_ERR_NO_MINUS_QUIET_NAN
when called to convert a negative quiet NaN

HOST_ERR_NO_PLUS_SIGNALING_NAN
when called to convert a positive signaling NaN

HOST_ERR_NO_MINUS_SIGNALING_NAN
when called to convert a negative signaling NaN

Example

double oopToFlt_example(OopType arg)
{
  double d = GciOopToFlt(arg);
 
  GciErrSType errInfo;
  if (GciErr(&errInfo)) {
    // argument was not a Float, SmallFloat or SmallDouble
    printf("error category "FMT_OID" number %d, %s\n",
       errInfo.category, errInfo.number, errInfo.message);
    return 0.0 ;
  }
  return d;
}
 

See Also

GciFltToOop
Gci_doubleToSmallDouble

GciOopToI32

GciOopToI32_

Convert a GemStone object to a C 32-bit integer value.

Syntax

int GciOopToI32(
OopType theObject );

int GciOopToI32_(
OopType theObject,
BoolType * error );

Arguments

theObject 

The OOP of the specified Integer object.

error  

TRUE if theObject does not fit in the result type or is not an Integer, otherwise unchanged.

Return Value

The GciOopToI32 and GciOopToI32_ functions return the C 32-bit integer value that is equivalent to the value of theObject.

Description

The GciOopToI32 and GciOopToI32_ functions translate a GemStone object into the equivalent C 32-bit integer value. The GemStone object must be a SmallInteger within the range of C integers.

Otherwise, GciOopToI32 generates an error; GciOopToI32_ does not generate an error, but places a boolean in the error argument.

See Also

GciOopToI64

GciOopToI64

GciOopToI64_

Convert a GemStone object to a C 64-bit integer value.

Syntax

int64 GciOopToI64(
OopType theObject );

int64 GciOopToI64_(
OopType theObject,
BoolType * error );

Arguments

theObject  

The OOP of the Integer object.

error  

TRUE if theObject does not fit in the result type or is not an Integer, otherwise unchanged.

Return Value

The GciOopToI64 and GciOopToI64_ functions return the C int64_t value that is equivalent to the value of theObject.

Description

The GciOopToI64 and GciOopToI64_ functions translate a GemStone object into the equivalent C 64-bit integer value.

The object identified by theObject must be a SmallInteger or a LargeInteger. If the object is not one of these kinds, GciOopToI64 generates an error; GciOopToI64_ places a boolean in the argument error.

See Also

GciOopToI32

GciPerform

Send a message to a GemStone object.

Syntax

OopType GciPerform(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs );

Arguments

receiver

The OOP of the receiver of the message.

selector

A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

Return Value

Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.

Description

This function sends a message (that is, the selector along with any keyword arguments and their corresponding values) to the specified receiver (an object in the GemStone database). Because GciPerform calls the virtual machine, you can issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.

Example

BoolType perform_example()
{
   GciErrSType errInfo;
   OopType userGlobals = GciResolveSymbol("UserGlobals", OOP_NIL);
   
   OopType argList[2];
   argList[0] = GciNewSymbol("myNumber");
   argList[1] = GciI32ToOop(55);
   
   OopType result = GciPerform(userGlobals, "at:put:", argList, 2);
   if (result == OOP_NIL) {
      if (GciErr(&errInfo)) {
         printf("GciPerform failed; error %d, %s\n", errInfo.number, errInfo.message); 
         return false;
      }
   } 
   BoolType err = false;
   int64 val = GciOopToI64_(result, &err);
   if (err) {
      printf("GciOopToI64 failed\n");
      return false;
   } 
   return (val = 55);
}

See Also

GciExecuteStr
GciNbPerform
GciPerformNoDebug
GciPerformSymDbg
GciPerformTrav
GciPerformTraverse

GciPerformFetchBytes

Send a message to a GemStone object, returning byte results.

Syntax

OopType GciPerformFetchBytes(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
ByteType * result,
ssize_t maxResultSize);

Arguments

receiver

The OOP of the receiver of the message.

selector

A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

result

Array containing the bytes of the result of the execution.

maxResultSize

Maximum size of result.

Return Value

Returns number of bytes returned in *result, or -1 if an error is available to be fetched with GciErr.

Description

This function sends a message (that is, the selector along with any keyword arguments and their corresponding values) to the specified receiver (an object in the GemStone database), and puts the result, which should be a byte format object, in the *result buffer.

Because GciPerformFetchBytes calls the virtual machine, you can issue a soft break while this function is executing.

See Also

GciExecuteStrFetchBytes
GciNbPerformFetchBytes
GciPerform
GciPerformTrav
GciPerformTraverse

 

 

GciPerformNoDebug

Send a message to a GemStone object, and temporarily disable debugging.

Syntax

OopType GciPerformNoDebug(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
int flags );

Arguments

receiver

The OOP of the receiver of the message.

selector

A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

flags

Flags to disable or permit asynchronous events and debugging in Smalltalk. Use one or more of the GemBuilder mnemonics described below.

Return Value

Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.

Description

This function is a variant of GciPerform that is identical to it except for just one difference. GciPerformNoDebug disables any breakpoints and single step points that currently exist in GemStone while the message is executing. This feature is typically used while implementing a Smalltalk debugger.

Values for flags are described in gcicmn.ht,and can include:

  • 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.

See Also

GciExecuteStr
GciNbPerformNoDebug
GciPerform
GciPerformSymDbg
GciPerformTrav
GciPerformTraverse

GciPerformSymDbg

Send a message to a GemStone object, using a String object as a selector.

Syntax

OopType GciPerformSymDbg(
OopType receiver,
OopType selector,
const OopType args[ ],
int numArgs,
int flags );

Arguments

receiver

The OOP of the receiver of the message.

selector

The OOP of a string object that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

flags

Flags to disable or permit asynchronous events and debugging in Smalltalk.

Return Value

Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.

Description

If the isNoDebug flag is FALSE, this function is a variant of GciPerform; if the flag is TRUE, this function is a variant of GciPerformNoDebug. In either case, its operation is identical to the other function. The difference is that GciPerformSymDbg takes an OOP as its selector instead of a C string.

See Also

GciExecute
GciPerform

GciPerformTrav

First send a message to a GemStone object, then traverse the result of the message.

Syntax

BoolType GciPerformTrav(
OopType receiver,
const char * selector,
const OopType * args,
int numArgs,
GciClampedTravArgsSType * travArgs );

Arguments

receiver

The OOP of the receiver of the message.

selector

A pointer to a character collection that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

travArgs

Pointer to an instance of GciClampedTravArgsSType. See GciClampedTrav for documentation of the fields in travArgs. The result of the GciPerform is the first object in the resulting travBuff field in travArgs.

Return Value

Returns TRUE if the result is complete and no errors occurred. Returns FALSE if the traversal is not yet completed. You can then call GciMoreTraversal to proceed, if there is no GciError.

Description

This function is does the equivalent of a GciPerform using the first four arguments, and then performs a GciClampedTrav, starting from the result of the perform, and doing a traversal as specified by travArgs. In all GemBuilder traversals, objects are traversed post depth first.

See Also

GciClampedTrav
GciNbPerformTrav
GciPerform
GciPerformTraverse

GciPerformTraverse

First send a message to a GemStone object, then traverse the result of the message.

Syntax

BoolType GciPerformTraverse(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
GciTravBufType * travBuff,
int level );

Arguments

receiver

The OOP of the receiver of the message.

selector

A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:).

args

An array of OOPs. Each element in the array corresponds to an argument for the message. If there are no message arguments, use a dummy OOP here.

numArgs

The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero.

travBuff

A traversal buffer in which the results of the traversal are placed.

level

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

Return Value

Returns FALSE if the traversal is not yet completed, but further traversal would cause the travBuffSize to be exceeded. If the travBuffSize is reached before the traversal is complete, you can then call GciMoreTraversal to proceed from the point where travBuffSize was exceeded.

Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal.

Description

This function does a perform, then traverses the result of the perform.

GciPerformTraverse provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.

Example

The following two functions are equivalent:

BoolType performTraverse_example1(void)
{
  OopType receiver = GciResolveSymbol("AllUsers", OOP_NIL);
  OopType arg = GciI32ToOop(1);
  GciTravBufType *buf = GciAllocTravBuf(80000);
  
  BoolType atEnd = GciPerformTraverse(receiver, "at:", &arg, 1, buf, 2);
  return atEnd;
}
BoolType performTraverse_example2(void)
{
  OopType receiver = GciResolveSymbol("AllUsers", OOP_NIL);
  OopType arg = GciI32ToOop(1);
  OopType obj = GciPerform(receiver, "at:", &arg, 1);
 
  GciTravBufType *buf = GciAllocTravBuf(80000);
  BoolType atEnd = GciTraverseObjs(&obj, 1, buf, 2);    
  return atEnd;
}

 

See Also

GciClampedTrav
GciMoreTraversal
GciNbPerformTrav
GciPerform
GciPerformTrav
GciTraverseObjs

GciPointerToByteArray

Given a C pointer, return a SmallInteger or ByteArray containing the value of the pointer.

Syntax

OopType GciPointerToByteArray(
void * pointer );

Arguments

pointer  

A C pointer.

Return Value

Returns a GemStone SmallInteger or ByteArray containing the value of the pointer.

If the argument is a 64-bit pointer aligned on an 8-byte boundary, or is a 32-bit pointer, the result is a SmallInteger. Otherwise, the result is a ByteArray.

Description

The result has a machine-dependent byte order and is not intended to be committed.

See Also

GciByteArrayToPointer

GciPollForSignal

Poll GemStone for signal errors without executing any Smalltalk methods.

Syntax

BoolType GciPollForSignal( )

Return Value

This function returns TRUE if a signal error or an asynchronous error exists, and FALSE otherwise.

Description

GemStone permits selective response to signal errors: RT_ERR_SIGNAL_ABORT, RT_ERR_SIGNAL_COMMIT, and RT_ERR_SIGNAL_GEMSTONE_SESSION. The default condition is to leave them all invisible. GemStone responds to each single kind of signal error only after an associated method of class System has been executed: enableSignaledAbortError, enableSignaledObjectsError, and enableSignaledGemStoneSessionError respectively.

After GciInit executes successfully, the GemBuilder default condition also leaves all signal errors invisible. The GciPollForSignal function permits GemBuilder to check signal errors manually. However, GemStone must respond to each kind of error in order for GemBuilder to respond to it. Thus, if an application calls GciPollForSignal, then GemBuilder can check exactly the same kinds of signal errors as GemStone responds to. If GemStone has not executed any of the appropriate System methods, then this call has no effect until it does.

GemBuilder treats any signal errors that it finds just like any other errors, through GciErr or the GciLongJmp mechanism, as appropriate. Instead of checking manually, these errors can be checked automatically by calling the GciEnableSignaledErrors function.

GciPollForSignal also detects any asynchronous errors whenever they occur, including but not limited to the following errors: ABORT_ERR_LOST_OT_ROOT, GS_ERR_SHRPC_CONNECTION_FAILURE, GS_ERR_STN_NET_LOST, GS_ERR_STN_SHUTDOWN, and GS_ERR_SESSION_SHUTDOWN.

See Also

GciEnableSignaledErrors
GciErr

GciPollSocketForRead

Wait for the specified socket to be read-ready.

Syntax

int GciPollSocketForRead(
int socketFd,
int timeoutMs);

Arguments

socketFd   

A file descriptor for a socket.

timeoutMs 

Milliseconds to wait for a response before timing out and returning 0.

Return Value

This function returns 0 if timed out, 1 if socket is ready for read, and an int < 0 if an error occurred. The result in this cases is the negated errno value.

Description

Wait timeoutMs milliseconds for the specified socket to be read-ready or to have an error.

This function retrys the poll on EINTR , even if a SIGTERM was received.

This is a thread safe function, and has no relationship to the current GCI session .

GciPopErrJump

Discard a previously saved error jump buffer.

Syntax

void GciPopErrJump(
GciJmpBufSType * jumpBuffer );

Arguments

jumpBuffer

A pointer to a jump buffer specified in an earlier call to GciPushErrJump.

Description

This function discards one or more jump buffers that were saved with earlier calls to GciPushErrJump. Your program must call this function when a saved execution environment is no longer useful for error handling.

GemBuilder maintains a stack of error jump buffers. After your program calls GciPopErrJump, the jump buffer at the top of the stack will be used for subsequent GemBuilder error handling. If no jump buffers remain, your program will need to call GciErr and test for errors locally.

To pop multiple jump buffers in a single call to GciPopErrJump, specify the jumpBuffer argument from an earlier call to GciPushErrJump. See the following example.

Example

void popErr_example(void)
{
  GciJmpBufSType jumpBuff1, jumpBuff2, jumpBuff3, jumpBuff4;
 
  GciPushErrJump(&jumpBuff1);
 
  GciPushErrJump(&jumpBuff2);
 
  GciPushErrJump(&jumpBuff3);
 
  GciPushErrJump(&jumpBuff4);
 
  GciPopErrJump(&jumpBuff1);  /*  pops buffers 1-4 */
}
 

See Also

GciErr
GciPushErrJump
GciSetErrJump
GciLongJmp

GciProcessDeferredUpdates_

Process deferred updates to objects that do not allow direct structural update.

Syntax

int64 GciProcessDeferredUpdates_( )

Return Value

Returns the number of objects that had deferred updates.

Description

This function processes updates to instances of classes that have the noStructuralUpdate bit set, including AbstractDictionary, Bag, Set, and their subclasses. After operations that modify an instance of once of these classes, either GciProcessDeferredUpdates_ must be called, or the final GciStoreTrav must have GCI_STORE_TRAV_FINISH_UPDATES set.

The following GemBuilder calls operate on instances whose classes have noStructuralUpdate set: GciCreateOopObj, GciStoreTrav, GciStore...Oops, GciAdd...Oops, GciReplace...Oops. Behavior of other GemBuilder update calls on such instances is undefined.

An attempt to commit automatically executes a deferred update.

Executing a deferred update before all forward references are resolved can produce errors that require the application to recover by doing a GciAbort or GciLogout.

An OOP buffer used to update the varying portion of an object with noStructuralUpdate must contain the OOPs to be added to the varying portion of the object, with two exceptions:

  • If the object is a kind of KeyValueDictionary that does not store Associations, the buffer must contain (key, value) pairs.
  • If the object is a kind of AbstractDictionary that stores Associations or (key, Association) pairs, the value buffer must contain Associations.

See Also

GciStoreTrav

GciProduct

Return an 8-bit unsigned integer that indicates the GemStone/S product.

Syntax

unsigned char GciProduct( );

Return Value

Returns an 8-bit unsigned integer indicating the GemStone/S product to which the client library belongs. This will always return 3 in GemStone/S 64 Bit.

Description

GciProduct allows a GemBuilder client to determine which GemStone/S product it is talking to. Combined with GciVersion, it allows the client to adapt to differences between GemBuilder features across different products and versions.

Currently-defined integers are:
1 — 32-bit GemStone/S
2 — GemStone/S 2G (discontinued product)
3 — GemStone/S 64 Bit

Any future products in the GemStone/S line will be assigned integers beginning with 4.

The integer zero is reserved, and will never be assigned to any product.

See Also

GciVersion

GciPushErrJump

Associate GemBuilder error handling with a jump buffer by pushing a jump buffer onto the stack.

Syntax

void GciPushErrJump(
GciJmpBufSType * jumpBuffer );

Arguments

jumpBuffer 

A pointer to a jump buffer, as described below. The jumpBuffer must have been initialized by passing it as the argument to the macro Gci_SETJMP.

Description

Associate GemBuilder error handling with a jump buffer by pushing a jump buffer onto the stack.

This function allows your application program to take advantage of the setjmp/longjmp style of error-handling mechanism from within any GemBuilder function call. However, you cannot use this mechanism to handle errors within GciPushErrJump itself, or within the related functions GciPopErrJump and GciSetErrJump.

Rather than using setjmp and longjmp directly, this style of error handling in GemBuilder requires you to use Gci_SETJMP and GciLongJmp.

When your program calls Gci_SETJMP, the context of the C environment is saved in a jump buffer that you designate. To associate subsequent GemBuilder error handling with that jump buffer, you would then call GciPushErrJump.

GemBuilder maintains a stack of up to 20 error jump buffers. A buffer is pushed onto the stack when GciPushErrJump is called, and popped when GciPopErrJump is called. When an error occurs during a GemBuilder call, the GemBuilder implementation calls GciLongJmp using the buffer currently at the top of GemBuilder’s error jump stack, and pops that buffer from the stack.

For functions with local error recovery, your program can call GciSetErrJump to temporarily disable the GciLongJmp mechanism (and to re-enable it afterwards).

Whenever the jump stack is empty, the application must use GciErr to poll for GBC errors.

Example

For an example of how GciPushErrJump is used, see GciPopErrJump.

See Also

GciErr
GciLongJmp
GciPopErrJump
GciSetErrJump
Gci_SETJMP

GciRaiseException

Signal an error, synchronously, within a user action.

Syntax

void GciRaiseException(
const GciErrSType * error );

Arguments

error

A pointer to the error type to raise.

Description

When executed from within a user action, this function raises an exception and passes the given error to the error signaling mechanism, causing control to return to Smalltalk. In order to signal an error on the Smalltalk client, this function must be invoked.

This function has no effect when executed outside of a user action.

Example

OopType res = GciNewOop(anOopClass);GciErrSType theErr;// the term res==OOP_NIL is a performance optimization if (res == OOP_NIL && GciErr(&theErr)) {	GciRaiseException(&theErr);	}

GciReadSharedCounter

Lock and fetch the value of a shared counter.

Syntax

BoolType GciReadSharedCounter(
int counterIdx,
int64_t * value);

Arguments

counterIdx

The offset into the shared counters array of the value to fetch.

value

Pointer to a value for this shared counter.

Return Value

Returns a C Boolean value indicating whether the value was successfully read. Returns TRUE if successful, FALSE if an error occurred.

Description

Lock the shared counter indicated by counterIdx, and fetch its value. The contents of the value pointer will be set to the value of the shared counter.

Not supported for remote GCI interfaces.

See Also

GciDecSharedCounter
GciFetchNumSharedCounters
GciFetchSharedCounterValuesNoLock
GciIncSharedCounter
GciReadSharedCounterNoLock
GciSetSharedCounter

GciReadSharedCounterNoLock

Fetch the value of a shared counter without locking it.

Syntax

BoolType GciReadSharedCounterNoLock(
int counterIdx,
int64_t * value);

Arguments

counterIdx 

The offset into the shared counters array of the value to fetch.

value

Pointer to a value for this shared counter.

Return Value

Returns a C Boolean value indicating whether the value was successfully read. Returns TRUE if successful, FALSE if an error occurred.

Description

Fetch the value of the shared counter indicated by counterIdx. The contents of the value pointer will be set to the value of the shared counter. This function is faster than GciReadSharedCounter, but may be less accurate.

Not supported for remote GCI interfaces.

See Also

GciDecSharedCounter
GciFetchNumSharedCounters
GciFetchSharedCounterValuesNoLock
GciIncSharedCounter
GciReadSharedCounter
GciSetSharedCounter

GciReleaseAllGlobalOops

Remove all OOPS from the PureExportSet, making these objects eligible for garbage collection.

Syntax

void GciReleaseAllGlobalOops( )

Description

The GciReleaseAllGlobalOops function removes all OOPs from the PureExportSet, thus permitting GemStone to consider removing them as a result of garbage collection. Objects that are referenced from persistent objects are not removed during garbage collection, even if they are not in PureExportSet. If invoked from a user action, this function does not affect the user action’s export set.

GciReleaseAllGlobalOops is similar to GciReleaseAllOops, with the exception that OOPs are removed from the PureExportSet regardless of whether it is called from within a user action or not.

The GciSaveGlobalObjs or GciSaveGlobalObjs functions may be used to make objects ineligible for garbage collection. Note that results of the GciNew..., GciCreate..., GciPerform..., and GciExecute... functions are automatically added to the PureExportSet. You must release those objects explicitly if they are to be eligible for garbage collection.

CAUTION
Before releasing all objects, be sure that you will not need any of them again.

See Also

Garbage Collection
GciReleaseAllGlobalOops
GciReleaseAllOops
GciReleaseGlobalOops
GciReleaseOops
GciSaveObjs

GciReleaseAllOops

Remove all OOPS from the PureExportSet, or if in a user action, from the user action’s export set, making these objects eligible for garbage collection.

Syntax

void GciReleaseAllOops( )

Description

The GciReleaseAllOops function removes all OOPs from the applicable export set, thus permitting GemStone to consider removing them as a result of garbage collection. If called from within a user action, GciReleaseAllOops releases only those objects that have been saved since the beginning of the user action and are therefore in the user action’s export set. If not called from within a user action, GciReleaseAllOops removes all OOPs from the PureExportSet. To remove all objects from the PureExportSet, regardless of user action context, use GciReleaseAllGlobalOops.

Objects that are referenced by persistent objects are not removed during garbage collection, even if they are not in an export set. It is typical usage to call GciReleaseAllOops after successfully committing a transaction.

The GciSaveObjs or GciSaveGlobalObjs functions may be used to make objects ineligible for garbage collection. Note that results of the GciNew..., GciCreate..., GciPerform..., and GciExecute... functions are automatically ineligible. You must release those objects explicitly if they are to be eligible.

CAUTION
Before releasing all objects, be sure that you will not need any of them again.

See Also

Garbage Collection
GciReleaseAllGlobalOops
GciReleaseGlobalOops
GciReleaseOops
GciSaveGlobalObjs
GciSaveObjs

 

GciReleaseGlobalOops

Remove an array of GemStone OOPs from the PureExportSet, making them eligible for garbage collection.

Syntax

void GciReleaseGlobalOops(
const OopType theOops[ ],
int numOops );

Arguments

theOops     

An array of OOPs. Each element of the array corresponds to an object to be released.

numOops

The number of elements in theOops.

Description

The GciReleaseGlobalOops function removes the specified OOPs from the PureExportSet, thus making them eligible to be garbage collected.

This function differs from GciReleaseOops in that it operates the same if invoked from within a user action or not.

The GciSaveObjs or GciSaveGlobalObjs functions may be used to make objects ineligible for garbage collection. Note that results of the GciNew..., GciCreate..., GciPerform..., and GciExecute... functions are automatically ineligible. You must release those objects explicitly if they are to be eligible.

CAUTION
Before releasing any of your objects, be sure that you will not need them again.

See Also

Garbage Collection
GciReleaseAllGlobalOops
GciReleaseOops
GciSaveGlobalObjs

GciReleaseOops

Remove an array of GemStone OOPs from the PureExportSet, or if in a user action, remove them from the user action’s export set, making them eligible for garbage collection.

Syntax

void GciReleaseOops(
const OopType theOops[ ],
int numOops );

Arguments

theOops     

An array of OOPs. Each element of the array corresponds to an object to be released.

numOops

The number of elements in theOops.

Description

The GciReleaseOops function removes the specified OOPs from the applicable export set, thus making them eligible to be garbage collected. If invoked from within a user action, the specified OOPs are removed from the user action’s export set, otherwise the OOPs are removed from the PureExportSet.

To remove OOPs from the PureExportSet, regardless of user action context, use GciReleaseGlobalOops.

The GciSaveObjs or GciSaveGlobalObjs functions may be used to make objects ineligible for garbage collection. Note that results of the GciNew..., GciCreate..., GciPerform..., and GciExecute... functions are automatically ineligible. You must release those objects explicitly if they are to be eligible.

CAUTION
Before releasing any of your objects, be sure that you have other references, or will not need them again.

Example

void releaseOops_example(void)
{
   OopType oArray = GciExecuteStr("UserGlobals at: #myArray put: (Array new: 5)", OOP_NIL);
 
   OopType ivs[3];
   ivs[0] = GciNewString("This is a string");
   ivs[1] = GciI32ToOop(5699); // a SmallInteger; don't need to release
   ivs[2] = GciFltToOop(9.0e6); // a Float or SmallDouble
   GciStoreOops(oArray, 1, ivs, 3); 
 
   // release newly created objects,so that if oArray is removed from
   // UserGlobals by other application code, these new objects can
   // be garbage collected.
   OopType releaseBuf[3];
   releaseBuf[0] = ivs[0];  // a String
   releaseBuf[1] = ivs[2];  // might be a Float
   releaseBuf[2] = oArray;  // the array instance
   GciReleaseOops(releaseBuf, 3);
   GciErrSType err;
   if (GciErr(&err)) {
      printf("Error %d, %s\n", err.number, err.message); }
}

See Also

Garbage Collection
GciReleaseAllGlobalOops
GciReleaseAllOops
GciSaveGlobalObjs
GciSaveObjs

 

GciRemoveOopFromNsc

Remove an OOP from an NSC.

Syntax

BoolType GciRemoveOopFromNsc(
OopType theNsc,
OopType theOop );

Arguments

theNsc

The OOP of the NSC from which to remove the OOP.

theOops

The OOP of the object to be removed from the NSC.

Return Value

Returns FALSE if theOop was not present in the NSC. Returns TRUE if theOop was present.

Description

This function removes an OOP from the unordered variables of an NSC, using structural access.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

BoolType removeOopFromNsc_example(void)
{
   OopType anAccount = GciExecuteStr("AllAccounts detect: [:ea | ea id=1073", OOP_NIL);
   OopType aColl = GciResolveSymbol("AllAccounts", OOP_NIL);
  
   BoolType wasPresent = GciRemoveOopFromNsc(aColl, anAccount);
 
   /* release because it is the result from an execute */
   GciReleaseOops(&anAccount, 1); 
   return wasPresent;
}

See Also

GciAddOopToNsc
GciAddOopsToNsc
GciNscIncludesOop
GciRemoveOopsFromNsc

GciRemoveOopsFromNsc

Remove one or more OOPs from an NSC.

Syntax

BoolType GciRemoveOopsFromNsc(
OopType theNsc,
const OopType theOops[ ],
int numOops );

Arguments

theNsc

The OOP of the NSC from which the OOPs will be removed.

theOops

The array of OOPs to be removed from the NSC.

numOops

The number of OOPs to remove.

Return Value

Returns FALSE if any element of theOops was not present in the NSC. Returns TRUE if all elements of theOops were present in the NSC.

Description

This function removes multiple OOPs from the unordered variables of an NSC, using structural access. If any individual OOP is not present in the NSC, this function returns FALSE, but it still removes all OOPs that it finds in the NSC.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

BoolType removeOopsFromNsc_example(void)
{
   OopType subColl = GciExecuteStr(
      "AllAccounts select:[ea|ea id > 2000 ]", OOP_NIL);
      
   OopType buf[10];
   int numRet = GciFetchVaryingOops(subColl, 1, buf, 10);
   /* buf contains at most 10 accounts with ids > 2000 */
    
   OopType aColl = GciResolveSymbol("AllAccounts", OOP_NIL);
   BoolType allPresent = GciRemoveOopsFromNsc(aColl, buf, numRet);
 
   /* release because it is the result from an execute */
   GciReleaseOops(&subColl, 1);
   return allPresent;
}

See Also

GciAddOopToNsc
GciAddOopsToNsc
GciNscIncludesOop
GciRemoveOopFromNsc

GciReplaceOops

Replace all instance variables in a GemStone object.

Syntax

void GciReplaceOops(
OopType theObj,
const OopType theOops[ ],
int numOops );

Arguments

theObj  

The object whose instance variables are to be replaced.

theOops 

An array of OOPs used as the replacements.

numOops

The number of elements in theOops.

Description

GciReplaceOops uses structural access to replace all the instance variables in the object. However, it does so in a context that is external to the object. Hence, it completely ignores private named instance variables in its operation.

If theObj is of fixed size, then it is an error for numOops to be of a different size. If theObj is of a variable size, then it is an error for numOops to be of a size smaller than the number of named instance variables (namedSize) of the object. For variable-sized objects, GciReplaceOops resets the number of unnamed variables to numOops - namedSize.

GciReplaceOops is not recommended for use with variable-sized objects unless they are indexable or are NSCs. Other variable-sized objects, such as KeyValue dictionaries, do not store values at fixed offsets.

See Also

GciReplaceVaryingOops
GciStoreIdxOops
GciStoreNamedOops
GciStoreOops

GciReplaceVaryingOops

Replace all unnamed instance variables in an NSC object.

Syntax

void GciReplaceVaryingOops(
OopType theNsc,
const OopType theOops[ ],
int numOops );

Arguments

theNsc

The NSC object whose unnamed instance variables are replaced.

theOops 

An array of OOPs used as the replacements.

numOops

The number of elements in theOops.

Description

GciReplaceVaryingOops uses structural access to replace all unnamed instance variables in the NSC object.

See Also

GciReplaceOops
GciStoreIdxOops
GciStoreNamedOops
GciStoreOops

GciResolveSymbol

Find the OOP of the object to which a symbol name C string refers, in the context of the current session’s user profile.

Syntax

OopType GciResolveSymbol(
const char * cString,
OopType symbolList );

Arguments

cString

The name of a Symbol as a C character string.

symbolList

The OOP of a GemStone symbol list, an instances of OOP_CLASS_SYMBOL_LIST. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

The OOP of the object that corresponds to the specified string.

Description

Attempts to resolve the symbol name cString using symbol list symbolList. If symbolList is OOP_NIL, this function searches the symbol list in the user’s UserProfile. If the symbol is not found or an error is generated, the result is OOP_ILLEGAL. If result is OOP_ILLEGAL and GciErr reports no error, then the symbol could not be resolved using the given symbolList. If an error such as an authorization error occurs, the result is OOP_ILLEGAL and the error is accessible by GciErr.

This function is similar to GciResolveSymbolObj, except that the symbol argument is a C string instead of an object identifier.

See Also

GciResolveSymbolObj

GciResolveSymbolObj

Find the OOP of the object to which a symbol name String or MultiByteString refers, in the context of the current session’s user profile.

Syntax

OopType GciResolveSymbolObj(
OopType aStringObj,
OopType symbolList );

Arguments

aStringObj

The OOP of a kind of String or MultiByteString.

symbolList

The OOP of a GemStone symbol list, an instances of OOP_CLASS_SYMBOL_LIST. A value of OOP_NIL means to use the default symbol list for the current GemStone session (that is, System myUserProfile symbolList).

Return Value

The OOP of the Symbol that corresponds to the specified String.

Description

Attempts to resolve aStringObj using symbol list symbolList. If symbolList is OOP_NIL, this function searches the symbol list in the user’s UserProfile. If the symbol is not found or an error is generated, the result is OOP_ILLEGAL. If the result is OOP_ILLEGAL and GciErr reports no error, then the symbol could not be resolved using the given symbolList. If an error such as an authorization error occurs, the result is OOP_ILLEGAL and the error is accessible by GciErr.

This function is similar to GciResolveSymbol, except that the symbol argument is an object identifier for a String instead of a C string.

See Also

GciResolveSymbol

GciRtlIsLoaded

Report whether a GemBuilder library is loaded.

Syntax

BoolType GciRtlIsLoaded( )

Return Value

Returns TRUE if a GemBuilder library is loaded and FALSE if not.

Description

The GciRtlIsLoaded function reports whether an executable has loaded one of the versions of GemBuilder. The GemBuilder library files are dynamically loaded at run time. See The GemBuilder for C Shared Libraries for more information.

See Also

GciRtlLoad
GciRtlUnload

GciRtlLoad

Load a GemBuilder library.

Syntax

BoolType GciRtlLoad(
BoolType useRpc,
const char * path,
char errBuf[ ],
size_t errBufSize );

Arguments

useRpc

A flag to specify the RPC or linked version of GemBuilder.

path

A list of directories (separated by ;) to search for the GemBuilder library.

errBuf

A buffer to store any error message.

errBufSize

The size of errBuf.

Return Value

Returns TRUE if a GemBuilder library loads successfully. If the load fails, the return value is FALSE, and a null-terminated error message is stored in errBuf, unless errBuf is NULL.

Description

The GciRtlLoad function attempts to load one of the GemBuilder libraries. If useRpc is TRUE, the RPC version of GemBuilder is loaded. If useRpc is FALSE, the linked version of GemBuilder is loaded. See The GemBuilder for C Shared Libraries for more information.

If path is not NULL, it must point to a list of directories to search for the library to load. If path is NULL, then a default path is searched: the appropriate subdirectory of $GEMSTONE, depending on the platform and if it is 32-bit or 64-bit.

If a GemBuilder library is already loaded, the call fails.

Example

void load_library(void)
{
  char errBuf[1024];
  BoolType result = GciRtlLoad(true, "$GEMSTONE/lib", errBuf, sizeof(errBuf));
  if (result == FALSE)  
     printf("Library load failed, %s\n", errBuf); 
}

See Also

GciRtlIsLoaded
GciRtlUnload

GciRtlUnload

Unload a GemBuilder library.

Syntax

void GciRtlUnload( )

Description

The GciRtlUnload function causes the library loaded by GciRtlLoad to be unloaded. Once the current library is unloaded, GciRtlLoad can be called again to load a different GemBuilder library. See The GemBuilder for C Shared Libraries for more information.

See Also

GciRtlIsLoaded
GciRtlLoad

 

GciSaveGlobalObjs

Add an array of OOPs to the PureExportSet, making them ineligible for garbage collection.

Syntax

void GciSaveGlobalObjs(
const OopType theOops[ ],
int numOops );

Arguments

theOops

An array of OOPs.

numOops

The number of elements in theOops.

Description

The GciSaveGlobalObjs function places the specified OOPs in the PureExportSet, thus preventing GemStone from removing them as a result of garbage collection. GciSaveGlobalObjs can add any OOP to the PureExportSet. It differs from GciSaveObjs in that OOPs are placed in the PureExportSet regardless of user action context.

The GciSaveGlobalObjs function does not itself make objects persistent, and it does not create a reference to them from a persistent object so that the next commit operation will try to do so either. It only protects them from garbage collection.

Note that results of the GciNew..., GciCreate..., GciPerform..., GciExecute..., and GciResolve... functions are automatically added to the export set. The GciRelease... functions may be used to make objects eligible for garbage collection.

See Also

Garbage Collection
GciReleaseAllGlobalOops
GciReleaseAllOops
GciReleaseGlobalOops
GciReleaseOops
GciSaveObjs

GciSaveObjs

Add an array of OOPs to the PureExportSet, or if in a user action to the user action’s export set, making them ineligible for garbage collection.

Syntax

void GciSaveObjs(
const OopType theOops[ ],
int numOops );

Arguments

theOops

An array of OOPs.

numOops

The number of elements in theOops.

Description

The GciSaveObjs function places the specified OOPs in the applicable export set, thus preventing GemStone from removing them as a result of garbage collection. If invoked from within a user action, the OOPs are added to the user action’s export set; otherwise the OOPs are added to the PureExportSet. To add OOPS to the PureExportSet, regardless of the user action context, use GciSaveGlobalObjs. GciSaveObjs can add any OOP to the export set.

The GciSaveObjs function does not itself make objects persistent, and it does not create a reference to them from a persistent object so that the next commit operation will try to do so either. It only protects them from garbage collection.

Note that results of the GciNew..., GciCreate..., GciPerform..., GciExecute..., and GciResolve... functions are automatically added to the export set. The GciRelease... functions may be used to make objects eligible for garbage collection.

See Also

Garbage Collection
GciReleaseAllGlobalOops
GciReleaseAllOops
GciReleaseGlobalOops
GciReleaseOops
GciSaveGlobalObjs

GciServerIsBigEndian

Determine whether or not the server process is big-endian.

Syntax

BoolType GciServerIsBigEndian( );

Return Value

Returns TRUE if the session is RPC and the server process is big-endian, or if the session is linked and this process is big-endian. Returns FALSE otherwise.

Description

This function determines whether the server process is big-endian. If the current session is invalid, this generates an error.

GciSessionIsRemote

Determine whether or not the current session is using a Gem on another machine.

Syntax

BoolType GciSessionIsRemote( )

Return Value

Returns TRUE if the current GemBuilder session is connected to a remote Gem. It returns FALSE if the current GemBuilder session is connected to a linked Gem.

GciSessionIsRemote raises an error if the current session is invalid.

GciSetCacheName_

Set the name that a linked application will be known by in the shared cache.

Syntax

BoolType GciSetCacheName_(
char * name );

Arguments

name  

The processName reported by System cacheStatistics.

Return Value

Returns FALSE if called before GciInit and GciIsRemote returns FALSE.

Description

This function sets the name that a linked application will be known by in the shared cache. This function has no effect if GciIsRemote returns TRUE.

GciSetErrJump

Enable or disable the current error handler.

Syntax

BoolType GciSetErrJump(
BoolType aBoolean );

Arguments

aBoolean

TRUE enables error jumps to the execution environment saved by the most recent GciPushErrJump; FALSE disables error jumps.

Return Value

Returns TRUE if error handling was previously enabled for the jump buffer at the top of the error jump stack. Returns FALSE if error handling was previously disabled. If your program has no buffers saved in its error jump stack, this function returns FALSE. (This function cannot generate an error.)

For most GemBuilder functions, calling GciErr after a successful function call will return zero (that is, false). In such cases, the GciErrSType error report structure will contain some default values. (See GciErr for details.) However, a successful call to GciSetErrJump does not alter any previously existing error report information. That is, calling GciErr after a successful call to GciSetErrJump will return the same error information that was present before this function was called.

Description

This function enables or disables the error handler at the top of GemBuilder’s error jump stack.

Example

void setErrJump_example(void)
{
   GciJmpBufSType jumpBuf1;
   GciPushErrJump(&jumpBuf1);
 
   if (Gci_SETJMP(&jumpBuf1)) {
     GciErrSType errInfo;
     if (GciErr(&errInfo)) {
       printf("LONGJMP, error category "FMT_OID" number %d, %s\n",
         errInfo.category, errInfo.number, errInfo.message);
     } else {
       printf("GCI longjmp, but no error found\n"); // should not happen
     }
     GciPopErrJump(&jumpBuf1);
     return;
   }
   BoolType prevVal = GciSetErrJump(FALSE); // disable error jumps
   printf("error jumps previously %s\n", prevVal ? "enabled" : "disabled");
 
   OopType oRcvr = GciI32ToOop(3);
   GciPerform(oRcvr, "frob", NULL, 0);  // expect does-not-understand error
   GciErrSType errInfo;
   if (GciErr(&errInfo)) {
     printf("error category "FMT_OID" number %d, %s\n",
       errInfo.category, errInfo.number, errInfo.message);
   } else {
     printf("expected error but found none\n");
   }
   
   GciSetErrJump(TRUE); 
   GciPerform(oRcvr, "frob", NULL, 0);  // expect a longjmp 
 
   printf("GCI longjmp did not happen\n"); // should not reach here 
}
 

See Also

GciErr
GciLongJmp
GciPopErrJump
GciPushErrJump
GciSetErrJump

GciSetHaltOnError

Halt the current session when a specified error occurs.

Syntax

int GciSetHaltOnError(
int errNum );

Arguments

errNum

When this error occurs, halt the current session.

Return Value

Returns the previous error number on which the session was to halt.

Description

The GciSetHaltOnError function causes the current session to halt for internal debugging when the specified GemBuilder error occurs.

To unset after a previous call to GciSetHaltOnError, invoke this function with an errNum of zero.

See Also

GciContinue
GciDbgEstablish

Gci_SETJMP

(MACRO) Save a jump buffer in GemBuilder’s error jump stack.

Syntax

void Gci_SETJMP(
GciJmpBufSType * jumpBuffer );

Arguments

jumpBuffer

A pointer to a jump buffer.

Description

When your program calls this macro, the context of the C environment is saved in a jump buffer that you designate. GemBuilder maintains a stack of up to 20 error jump buffers.

See Also

GciErr
GciLongJmp
GciPopErrJump
GciPushErrJump
GciSetErrJump

GciSetNet

Set network parameters for connecting the user to the Gem and Stone processes.

Syntax

void GciSetNet(
const char stoneNameNrs[ ],
const char HostUserId[ ],
const char HostPassword[ ],
const char gemServiceNrs[ ] );

Arguments

stoneNameNrs

The NRS for the Stone repository to login into.

hostUserId

UNIX host login user Id. This may be NULL or an empty string if the Gem will run using the userId of the NetLDI process .

hostPassword

Password of the UNIX user, or NULL if not specifying hostUserId.

gemServiceNrs

The NRS for the GemService, gemnetobject or a custom gem script.

If an empty string, specifies a linked login.

Description

Your application, your GemStone session (Gem), and the database monitor (Stone) can all run in separate processes, on separate machines in your network. GciSetNet specifies the network parameters that are used to connect the current user to GemStone on the host, whenever GciLogin is called. Network resource strings specify the information needed to establish communications between these processes . See the System Administration Guide for GemStone/S 64 Bit for complete information on NRS Syntax and the network environment.

stoneNameNrs identifies the name and network location of the database monitor process (Stone), which is the final arbiter of all sessions that access a specific database.

A Stone process called “gs64stone” on node “lichen” could be described in a network resource string as:

!@lichen!gs64stone

A Stone of the same name that is running on the same machine as the application could be described in shortened form simply as:

gs64stone

gemServiceNrs identifies the name and network location of the GemStone service that creates a session process (Gem), which then arbitrates data access between the database and the application. Every GemStone session requires a Gem. In linked applications, one Gem is present within the same process as the application; in remote applications the Gem is a separate process specific to that login session. Each time an application user logs in to GemStone (after the first time in linked applications), the GemStone service must create a new Gem. gemServiceNrs is required except in the special case of a linked application that limits itself to one GemStone login per application process. In this special case, specify gemServiceNrs as an empty string.

For most installations, the GemStone service name is gemnetobject. Specify, for example:

!@lichen!gemnetobject

HostUserId and HostPassword are your login name and password, respectively, on the machines that host the Gem and Stone processes. Do not confuse these values with your GemStone username and password - the GemStone username and password will be provided as arguments to GciLogin. HostUserId and HostPassword provide authentication for such tasks as creating a Gem and establishing communications with a Stone, and are optional in some configuration. When such authentication is required, an application user cannot login to GemStone until the host login is verified for the machine running the Stone or Gem, in addition to the GemStone login itself.

Authentication is always required if the NetLDI process that is related to the Stone is running in secure mode. In this case, it makes no difference whether the application is linked or remote. Authentication is also required to create a remote Gem, unless the NetLDI process is running in guest mode.

If the HostUserId argument is set to an empty C string or a NULL pointer, GemBuilder will try to find a username and password for authentication on a host machine in your network initialization file. To prevent GemBuilder from looking for authentication information in the network initialization file, supply a valid non-empty C string for the HostUserId argument, and a non-empty string for the HostPassword argument to provide a password. An empty string and a NULL pointer both mean that no password will be used for authentication.

Example

For an example of how GciSetNet is used, see the example for GciLogin.

See Also

GciEncrypt
GciLogin
GciLoginEx
GciSetNetEx

GciSetNetEx

GciSetNetEx_

Set network parameters for connecting the user to the Gem and Stone processes, allowing encryption.

Syntax

void GciSetNetEx(
const char stoneNameNrs[ ],
const char hostUserId[ ],
const char hostPassword[ ],
const char gemServiceNrs[ ] ,
BoolType hostPasswordIsEncrypted);

BoolType GciSetNetEx_(
const char StoneNameNrs[ ],
const char hostUserId[ ],
const char hostPassword[ ],
const char gemServiceNrs[ ] ,
BoolType hostPasswordIsEncrypted,
char * errString,
size_t maxErrSize);

Arguments

stoneNameNrs

The NRS for the Stone repository to login into.

hostUserId

UNIX host login user Id. This may be NULL or an empty string if the Gem will run using the userId of the NetLDI process .

hostPassword

Password of the UNIX user, or NULL if not specifying hostUserId.

gemServiceNrs

The NRS for the GemService, gemnetobject or a custom gem script.

If an empty string, specifies a linked login.

hostPwIsEncrypted

TRUE if the value for hostPassword has been encrypted using GciEncrypt.

errString

If there is a syntax error in the NRS for the StoneName or GemService, GciSetNetEx_ returns FALSE and sets errString to the details of the error.

maxErrSize

Maximum number of bytes of error message to return.

Return Value

GciSetNetEx has no return value.  GciSetNetEx_ returns TRUE if the network parameters were set correctly, FALSE if there was a syntax error in stoneNameNrs or gemServiceNrs.

Description

This function is similar to GciSetNet, but allows specifying additional behavior. For details on how to specify the StoneName and GemService using NRS, and the requirements for HostUserId, HostPassword, see GciSetNet.

GciSetNetEx allows you to specify that the host password you send is encrypted. The host password may be encrypted using GciEncrypt. To encrypt the GemStone password, use GciLoginEx and specify the associated login flag.

Example

For an example of how GciSetNet is used, see GciLogin.

See Also

GciEncrypt
GciLogin
GciLoginEx
GciSetNet

GciSetSessionId

Set an active session to be the current one.

Syntax

void GciSetSessionId(
GciSessionIdType sessionId );

Arguments

sessionId 

The session ID of an active (logged-in) GemStone session.

Description

This function can be used to switch between multiple GemStone sessions in an application program with multiple logins.

See Also

GciGetSessionId
GciLogin

GciSetSharedCounter

Set the value of a shared counter.

Syntax

BoolType GciSetSharedCounter(
int counterIdx,
int64_t * value);

Arguments

counterIdx

The offset into the shared counters array of the value to modify.

value

Pointer to a value that containing the new value for this shared counter.

Return Value

Returns a C Boolean value indicating whether the value was successfully changed. Returns TRUE if the modification succeeded, FALSE if it failed.

Description

Set the value of the shared counter indicated by counterIdx. The contents of the value pointer indicate the new value of the shared counter.

Not supported for remote GCI interfaces.

See Also

GciDecSharedCounter
GciFetchNumSharedCounters
GciFetchSharedCounterValuesNoLock
GciIncSharedCounter
GciReadSharedCounter
GciReadSharedCounterNoLock

GciSetTraversalBufSwizzling

Control swizzling of the traversal buffers.

Syntax

BoolType GciSetTraversalBufSwizzling(
BoolType enabled );

Arguments

enabled

If TRUE, enable normal byte-order swizzling of traversal buffers for the current RPC session. This is the default state for a session created by successful GciLogin.

If FALSE, the application program is responsible for subsequent swizzling of traversal buffers if needed.

Return Value

Returns the previous value of swizzling of traversal buffers. When called on a linkable session, returns FALSE and has no effect. If the current session is invalid, generates an error and returns FALSE.

Description

GciSetTraversalBufSwizzling controls swizzling of the traversal buffers used by these calls in an RPC session:

GciStoreTrav, GciNbStoreTrav
GciStoreTravDo_
, GciNbStoreTravDo_
GciStoreTravDoTrav_
, GciNbStoreTravDoTrav_
GciClampedTrav
, GciNbClampedTrav
GciMoreTraversal, GciNbMoreTraversal
GciPerformTrav
, GciNbPerformTrav
GciExecuteStrTrav
, GciNbExecuteStrTrav

For more information on swizzling, see Byte-Swizzling of Binary Floating-Point Values.

GciSetVaryingSize

Set the size of a collection.

Syntax

void GciSetVaryingSize(
OopType collection,
int64 size );

Arguments

collection

The OOP of the collection whose size you are specifying.

size

The desired number of elements in the collection.

Description

GciSetVaryingSize changes the size of a collection, adding nils to grow it, or truncating it, as necessary. It is equivalent to the Smalltalk method Object >> size:. It does not change the number of any named instance variables.

Example

void setVaryingSize_example(void)
{
  OopType oArr = GciNewOop(OOP_CLASS_ARRAY); // create new Array of size 0
 
  GciSetVaryingSize(oArr, 1000000);  
  // logical size now 1 million
 
  GciStoreOop(oArr, 500000, GciI32ToOop(5678));
}
 

See Also

GciFetchVaryingSize_

GciShutdown

GciShutdown_

Logout from all sessions and deactivate GemBuilder.

Syntax

void GciShutdown( );

void GciShutdown_(
BoolByte doLogouts );

Arguments

doLogouts

If FALSE, does not performs an orderly logout of the all sessions. GciShutdown() is equivalent to GciShutdown(TRUE), which does perform a logout on all sessions.

Description

This function is intended to be called by image exit routines, such as the on_exit system call. In the linkable GemBuilder, GciShutdown calls GciLogout. In the RPC version, it logs out all sessions connected to the Gem process and shuts down the networking layer, thus releasing all memory allocated by GemBuilder.

GciSoftBreak

Interrupt the execution of Smalltalk code, but permit it to be restarted.

Syntax

void GciSoftBreak( )

Description

This function sends a soft break to the current user session (set by the last GciLogin or GciSetSessionId).

GemBuilder allows users of your application to terminate Smalltalk execution. This is useful, for example, if the a Smalltalk method is invoked that enters an infinite loop.

GciSoftBreak interrupts only the Smalltalk virtual machine (if it is running), and does so in such a way that the it can be restarted. The only GemBuilder functions that can recognize a soft break include GciSendMessage, GciPerform, and GciContinue, and the GciExecute... functions.

GciHardBreak has no effect if called from within a User Action.

In order for GemBuilder functions in your program to recognize interrupts, your program will need a signal handler that can call the functions GciSoftBreak and GciHardBreak. Since GemBuilder does not relinquish control to an application until it has finished its processing, soft and hard breaks must be initiated from another thread.

If GemStone is executing when it receives the break, it replies with the error message RT_ERR_SOFT_BREAK. Otherwise, it ignores the break.

Example

 
#include "signal.h"
 
extern "C" {
  static void doSoftBreak(int sigNum, siginfo_t* info, void* ucArg) 
  {
    GciSoftBreak();
  }
}
 
void softBreakExample(void)
{
  // save previous SIGINT handler and install ours
  struct sigaction oldHandler;
  struct sigaction newHandler;
  newHandler.sa_handler = SIG_DFL;
  newHandler.sa_sigaction = doSoftBreak; 
  newHandler.sa_flags = SA_SIGINFO | SA_RESTART ;
  sigaction(SIGINT, &newHandler, &oldHandler);
  
  // execute a loop that will take 120 seconds to execute and
  // return the SmallInteger with value 11 .
  OopType result = GciExecuteStr(
     "| a | a := 1 . 10 timesRepeat:[ System sleep:10. a := a + 1]. ^ a",
     OOP_NIL/*use default symbolList for execution*/);
 
  BoolType done = FALSE;
  int breakCount = 0;
  do {
    // assume the user may type ctl-C or issue kill -INT from
    //  another shell process  during the 120 seconds .
    GciErrSType errInfo;
    if ( GciErr(&errInfo)) {
      if (errInfo.number == RT_ERR_SOFT_BREAK) {
        // GciExecuteStr was interrupted by a GciSoftBreak .
        breakCount++ ;
        // now continue the execution to finish the computation
        result = GciContinue(errInfo.context);
      } else {
         		// FMT_OID format string is defined in gci.ht 
        printf("unexpected error category "FMT_OID" number %d, %s\n",
           errInfo.category, errInfo.number, errInfo.message);
        // terminate the execution
        GciClearStack(errInfo.context);
        done = TRUE;
      }
    } else {
      // GciExecuteStr or GciContinue completed without error
      done = TRUE;
      BoolType conversionErr = FALSE;
      int val = GciOopToI32_(result, &conversionErr);
      if (conversionErr) {
        printf("Error converting result to C int\n");
      } else {
        printf("Got %d interrupts, result = %d\n", breakCount, val);
      }
    }
  } while (! done);
 
  // restore previous SIGINT handler
  sigaction(SIGINT, &oldHandler, NULL);
}

See Also

GciClearStack
GciContinue
GciHardBreak

GciStep

GciStep_

Continue code execution in GemStone with specified single-step semantics.

Syntax

OopType GciStep(
OopType gsProcess,
int level );

OopType GciStep_(
OopType gsProcess,
int level
BoolType through);

Arguments

gsProcess

The OOP of a GsProcess object (obtained as the value of the context field of an error report returned b y GciErr).

level

One of the following values:
0 — step-into semantics starting from top of stack
1 — step-over semantics starting from top of stack
> 1 — step-over semantics from specified level on stack

through

When level =1 and this argument is TRUE, provides step through semantics, stopping in blocks for which the top of the stack frame is the home method.

Return Value

Returns the OOP of the result of the Smalltalk execution. Returns OOP_ILLEGAL in case of error.

Description

This function continues code execution in GemStone using the specified single-step semantics. This function is intended for use by debuggers.

If you specify a level that is either less than zero or greater than the value represented by GciPerform(gsProcess, "stackDepth", NULL, 0), this function generates an error.

GciStoreByte

Store one byte in a byte object.

Syntax

void GciStoreByte(
OopType theObject,
int64 atIndex,
ByteType theByte );

Arguments

theObject

The OOP of the GemStone byte object into which the store will be done.

startIndex

The index into theObject at which to begin storing bytes.

theByte   

The 8-bit value to be stored.

Description

This function stores a single element in a byte object at a specified index, using structural access.

GciStoreByte raises an error if theObject is a Float or SmallFloat. You must store all the bytes of a Float or SmallFloat if you store any.

Example

void storeByte_example(void)
{
  OopType oString = GciNewOop(OOP_CLASS_STRING);
 
  for (int j = 0; j < 200; j++) {
    ByteType val = j;
    GciStoreByte(oString, j + 1 , val );
  }
}

See Also

GciFetchByte
GciStoreBytes

GciStoreBytes

(MACRO) Store multiple bytes in a byte object.

Syntax

void GciStoreBytes(
OopType theObject,
int64 startIndex,
const ByteType theBytes[ ],
int64 numBytes );

Arguments

theObject   

The OOP of the GemStone byte object, into which the bytes will be stored.

startIndex

The index into theObject at which to begin storing bytes.

theBytes   

The array of bytes to be stored.

numBytes

The number of elements to store.

Description

This macro uses structural access to store multiple elements from a C array in a byte object, beginning at a specified index. A common application of GciStoreBytes would be to store a text string. For an object with multiple bytes per character or digit, theBytes is expected to be in client native byte order, and will be swizzled if needed by the server.

Error Conditions

GciStoreBytes raises an error if theObject is a Float or SmallFloat. Use GciStoreBytesInstanceOf instead for Float or SmallFloat objects.

Example

void storeBytes_example(void)
{
  OopType oString = GciNewOop(OOP_CLASS_STRING);
 
  enum { buf_size = 2000 };
  ByteType buf[buf_size];
  for (int j = 0; j < buf_size; j++) {
    buf[j] = (ByteType)j;
  }
  GciStoreBytes(oString, 1, buf, buf_size);
}
 

See Also

GciFetchByte
GciFetchBytes_
GciStoreByte
GciStoreBytesInstanceOf
GciStoreChars

GciStoreBytesInstanceOf

Store multiple bytes in a byte object.

Syntax

void GciStoreBytesInstanceOf(
OopType theClass,
OopType theObject,
int64 startIndex,
const ByteType theBytes[ ],
int64 numBytes );

Arguments

theClass   

The OOP of the class of the GemStone byte object.

theObject   

The OOP of the GemStone byte object into which the bytes will be stored.

startIndex

The index into theObject at which to begin storing bytes.

theBytes   

The array of bytes to be stored.

numBytes

The number of elements to store

Description

This function uses structural access to store multiple elements from a C array into a byte object, beginning at a specified index. A common application of GciStoreBytesInstanceOf would be to store a Float or LargeInteger object.

GciStoreBytesInstanceOf provides automatic byte swizzling for objects such as Float, LargeInteger, and DoubleByteString that use multiple bytes per digit or character. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values. For these objects, theBytes is assumed to be in client native byte order. For DoubleByteStrings, startIndex must be aligned on character boundaries and numBytes must be a multiple of the number of bytes per character; for numeric objects startIndex must be one and the numBytes the size of the numeric class.

The presence of the argument theClass enables the swizzling to be implemented more efficiently. If theObject is a Float or SmallFloat, then theClass must match the actual class of theObject, startIndex must be one, and numBytes must be the actual size for theClass. If any of these conditions are not met, then GciStoreBytesInstanceOf raises an error as a safety check.

If theObject is not a Float or SmallFloat, then theClass is ignored. Hence, you must supply the correct class for theClass if theObject is a Float or SmallFloat, but you can use OOP_NIL otherwise.

Example

void storeBytesInstof_example(void)
{
  double pi = 3.1415926;
  OopType oFloat = GciNewOop(OOP_CLASS_FLOAT);
  GciStoreBytesInstanceOf(OOP_CLASS_FLOAT, oFloat, 1,
           		   (ByteType *)&pi, sizeof(pi));
}
 

See Also

GciFetchByte
GciFetchBytes_
GciStoreByte
GciStoreBytes
GciStoreChars

GciStoreChars

Store multiple ASCII characters in a byte object.

Syntax

void GciStoreChars(
OopType theObject,
int64 startIndex,
const char * aString );

Arguments

theObject 

The OOP of the GemStone byte object, into which the chars will be stored.

startIndex

The index into theObject at which to begin storing bytes.

aString  

The string to be stored.

Description

This function uses structural access to store a C string in a byte object, beginning at a specified index.

GciStoreChars raises an error if theObject is a Float or SmallFloat. ASCII characters have no meaning as bytes in a Float or SmallFloat object.

Example

void storeChars_example(void)
{
  OopType oString = GciNewOop(OOP_CLASS_STRING);
  
  GciStoreChars(oString, 1, "some string data");
}
 

See Also

GciFetchBytes_
GciStoreBytes

GciStoreDynamicIv

Create or change the value of an object’s dynamic instance variable.

Syntax

void GciStoreDynamicIv(
OopType theObject,
OopType aSymbol,
OopType value);

Arguments

theObject

The OOP of the object.

aSymbol

Specifies the name of the dynamic instance variable.

value

The value to store in the dynamic instance variable.

Return Value

Creates or changes the value of the dynamic instance variable specified by aSymbol within theObject.

Description

This function stores a value into the dynamic instance variable specified by aSymbol.

Dynamic instance variables are not allowed in instances of ExecBlock, Behavior, GsNMethod, or special objects.

To delete a dynamic instance variable, pass OOP_REMOTE_NIL as the value.

See Also

GciFetchDynamicIv
GciFetchDynamicIvs

GciStoreIdxOop

Store one OOP in an indexable pointer object’s unnamed instance variable.

Syntax

void GciStoreIdxOop(
OopType theObject,
int64 atIndex,
OopType theOop );

Arguments

theObject

The OOP of a pointer object, into which the theOop will be stored

atIndex

The index into theObject at which to store theOop.

theOop

The OOP to be stored.

Description

This function stores a single OOP into an indexed variable of a pointer object at the specified index, using structural access. Note that this function cannot be used for NSCs. (To add an OOP to an NSC, use GciAddOopToNsc.)

Example

void storeIdxOop_example(void)
{
   GciErrSType err;
   OopType oArray = GciExecuteStr("Array new: 5", OOP_NIL);
   OopType oSet = GciExecuteStr("Set with: 'GBS/VA' with: 'GBS/VW'", OOP_NIL); 
      
   // store the Set into the 3rd slot of the Array
   GciStoreIdxOop(oArray, 3, oSet);
   
   // release results of execution
   GciReleaseOops(&oArray, 1);   
   GciReleaseOops(&oSet, 1); 
}

See Also

GciAddOopToNsc
GciFetchVaryingOop
GciFetchVaryingOops
GciStoreIdxOops

GciStoreIdxOops

Store one or more OOPs in an indexable pointer object’s unnamed instance variables.

Syntax

void GciStoreIdxOops(
OopType theObject,
int64 startIndex,
const OopType theOops[ ],
int numOops );

Arguments

theObject

The OOP of a pointer object into which theOops will be stored.

startIndex

The index into theObject at which to begin storing OOPs.

theOops 

The array of OOPs to be stored.

numOops

The number of elements to store

Description

This function uses structural access to store multiple OOPs from a C array into the indexed variables of a pointer object, beginning at the specified index. Note that this call cannot be used with NSCs. (To add multiple OOPs to an NSC, use GciAddOopsToNsc.)

Example

This example creates a new Array containing the first 10 elements of Globals.

BoolType storeIdxOops_example(void)

{

GciErrSType err;

OopType oArray = GciExecuteStr("Array new: 10", OOP_NIL);

OopType oGlobals = GciExecuteStr("Globals", OOP_NIL);

int buf_size = 10;

OopType oBuffer[buf_size];

 

// Fetch first 10 elements in Globals

int numRet = GciFetchVaryingOops(oGlobals, 1, oBuffer, buf_size);

// and put these in oArray

GciStoreIdxOops(oArray, 1, oBuffer, numRet);

if (GciErr(&err)) {

printf("Error %d, %s\n", err.number, err.message);

return false; }

// release results of execution

GciReleaseOops(&oArray, 1);

return true;

}

See Also

GciAddOopToNsc
GciFetchVaryingOops
GciReplaceOops
GciReplaceVaryingOops
GciStoreIdxOops
GciStoreNamedOops
GciStoreOops

GciStoreNamedOop

Store one OOP into an object’s named instance variable.

Syntax

void GciStoreNamedOop(
OopType theObject,
int64 atIndex,
OopType theOop );

Arguments

theObject

The Object into which to store the OOP.

startIndex

The index into theObject’s named instance variables at which to begin storing OOPs.

theOops

The array of OOPs to be stored.

Description

This function stores a single OOP into an object’s named instance variable at the specified index, using structural access.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

void storeNamedOop_example(OopType anAccount)
{
   OopType newName = GciNewString("Josiah Chang");
   
   //  assign new value to instvar at a hardcoded offset
   int indexOfSalesRep = 3;
   GciStoreNamedOop(anAccount, indexOfSalesRep, newName);
 
   //  assign new value to instvar without knowing offset
   GciStoreNamedOop(anAccount,
	     GciIvNameToIdx(GciFetchClass(anAccount), "salesRep"), 
        newName);
}

See Also

GciFetchNamedOop
GciFetchVaryingOop
GciStoreIdxOop
GciStoreNamedOops

GciStoreNamedOops

Store one or more OOPs into an object’s named instance variables.

Syntax

void GciStoreNamedOops(
OopType theObject,
int64 startIndex,
const OopType theOops[ ],
int numOops );

Arguments

theObject

The Object in which to store the OOP.

startIndex

The index into theObject’s named instance variables at which to begin storing OOPs.

theOops

The array of OOPs to be stored.

numOops

The number of OOPs to store. If (numOops+startIndex) exceeds the number of named instance variables in theObject, an error is generated.

Description

This function uses structural access to store multiple OOPs from a C array into an object’s named instance variables, beginning at the specified index.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

void storeNamedOops_example(OopType anAddress)
{
   // allocation buffer for unknown number of instvars 
   int namedSize = GciFetchNamedSize(anAddress);
   if (namedSize == 0) { return ; }
   OopType *oBuffer = (OopType*) malloc( sizeof(OopType) * namedSize );
   if (oBuffer == NULL) { return; }
  
   // fetch existing values
   int numRet = GciFetchNamedOops(anAddress, 1, oBuffer, namedSize);
   if (numRet != namedSize) {
      printf("error during fetch\n");
      return;
   }
 
   // update street and city, but not state
   OopType newValue = GciNewString("4545 45th Str");
   int ivOffset = GciIvNameToIdx(GciFetchClass(anAddress), "street");
   oBuffer[ivOffset  - 1 ] = newValue;
   newValue = GciNewString("Tualatin");
   ivOffset = GciIvNameToIdx(GciFetchClass(anAddress), "city");
   oBuffer[ivOffset  - 1 ] = newValue;
    
   // store changes
   GciStoreNamedOops(anAddress, 1, oBuffer, namedSize);
}

See Also

GciAddOopToNsc
GciFetchNamedOops
GciFetchVaryingOops
GciReplaceOops
GciReplaceVaryingOops
GciStoreIdxOops
GciStoreNamedOop
GciStoreOops

GciStoreOop

Store one OOP into an object’s instance variable.

Syntax

void GciStoreOop(
OopType theObject,
int64 atIndex,
OopType theOop );

Arguments

theObject

The Object in which to store the OOP.

startIndex

The index into theObject’s named or unnamed instance variables at which to store the OOP. This function does not distinguish between named and unnamed instance variables. Indices are based at the beginning of an object’s array of instance variables. In that array, the object’s named instance variables are followed by its unnamed instance variables

theOops

The OOP to be stored.

Description

This function stores a single OOP into an object at the specified index, using structural access. Note that this function cannot be used for NSCs. To add an object to an NSC, use GciAddOopToNsc.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

void storeOop_example(OopType anAccount)
{
   // Two ways to assign new value to a named instance variable of anAccount 
   OopType newName = GciNewString("Jeni Johnson-Klien");
   int indexOfSalesRep = 3;
   GciStoreOop(anAccount, indexOfSalesRep, newName);
   GciStoreNamedOop(anAccount, indexOfSalesRep, newName);
 
   // Two ways to assign a product string to the first indexed instance variable
   OopType newProduct = GciNewString("GemConnect");
   GciStoreOop(anAccount, GciFetchNamedSize(anAccount) + 1, newProduct);
   GciStoreIdxOop(anAccount, 1, newProduct);
}
 

See Also

GciAddOopToNsc
GciFetchNamedOop
GciFetchVaryingOop
GciFetchOops
GciStoreOops

GciStoreOops

Store one or more OOPs into an object’s instance variables.

Syntax

void GciStoreOops(
OopType theObject,
int64 startIndex,
const OopType theOops[ ],
int numOops );

Arguments

theObject

The Object in which to store the OOPs.

startIndex

The index into theObject’s named or unnamed instance variables at which to begin storing OOPs. This function does not distinguish between named and unnamed instance variables. Indices are based at the beginning of an object’s array of instance variables. In that array, the object’s named instance variables are followed by its unnamed instance variables

theOops

The OOP to be stored.

numOops

The number of OOPs to store

Description

This function uses structural access to store multiple OOPs from a C array into a pointer object, beginning at the specified index. Note that this call cannot be used with NSCs. To add multiple OOPs to an NSC, use GciAddOopsToNsc.

Example

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

void storeOops_example(OopType anAccount)
{
   int namedSize = GciFetchNamedSize(anAccount);
   int64 instSize = GciFetchSize_(anAccount);
  
   // allow space in buffer for storing into first varying instVar plus
   // appending a new varying instVar
   int64 bufVaryingSize = instSize - namedSize + 1;
  
   int64 bufSize = namedSize + bufVaryingSize;
   OopType *buf = (OopType*) malloc(sizeof(OopType) * bufSize);
   if (buf == NULL) {
      printf("malloc failure");
      return;
   }
   GciFetchOops(anAccount, 1, buf, instSize);
 
   OopType newName = GciNewString("Josiah Chang");
   int indexOfSalesRep = GciIvNameToIdx(GciFetchClass(anAccount), "salesRep");
   buf[indexOfSalesRep - 1] = newName;
 
   OopType firstProduct = GciNewString("GS64");
   OopType newProduct = GciNewString("GemConnect");
    
  // assign first element 
  buf[namedSize] = firstProduct;
  
  // append new product
  int64 newSize = instSize + 1;
  buf[newSize - 1] = newProduct;
  
  // now store all the instVars back to the repository
  GciStoreOops(anAccount, 1, buf, newSize);
}
 

See Also

GciAddOopsToNsc
GciFetchNamedOops
GciFetchVaryingOop
GciFetchOops
GciRemoveOopsFromNsc
GciReplaceOops
GciReplaceVaryingOops
GciStoreIdxOops
GciStoreNamedOops
GciStoreOops

GciStorePaths

Store selected multiple OOPs into an object tree.

Syntax

BoolType GciStorePaths(
const OopType theOops[ ],
int numOops,
const int paths[ ],
const int pathSizes[ ],
int numPaths,
const OopType newValues[ ],
int * failCount );

Arguments

theOops

A collection of OOPs into which you want to store new values.

numOops

The size of theOops.

paths

An array of integers. This one-dimensional array contains the elements of all constituent paths, laid end to end.

pathSizes

An array of integers. Each element of this array is the length of the corresponding path in the paths array (that is, the number of elements in each constituent path).

numPaths

The number of paths in the paths array. This should be the same as the number of integers in the pathSizes array.

newValues

An array containing the new values to be stored into theOops.

failCount

A pointer to an integer that indicates which element of the newValues array could not be successfully stored. If all values were successfully stored, failCount is 0. If the ith store failed, failCount is i. If any of the objects in newValues does not exist, or is not an OOP allocated to GemBuilder, failCount is 1.

Return Value

Returns TRUE if all values were successfully stored. Returns FALSE if the store on any path fails for any reason.

Description

This function allows you to store multiple objects at selected positions in an object tree with a single GemBuilder call, exporting only the desired information to the database.

Each path in the paths array is itself an array of longs. Those longs are offsets that specify a path along which to store objects. In each path, a positive integer x refers to an offset within an object’s named instance variables, while a negative integer -x refers to an offset within an object’s indexed instance variables.

The newValues array contains (numOops * numPaths) elements, stored in the following order:

[0,0]..[0,numPaths-1]..[1,0]..[1,numPaths-1]..[numOops-1,0]..[numOops-1,numPaths-1]

The first element of this newValues array is stored along the first path into the first element of theOops. New values are then stored into the first element of theOops along each remaining element of the paths array. Similarly, new values are stored into each subsequent element of theOops, until all paths have been applied to all its elements.

The new value to be stored into object i along path j is thus represented as:

newValues[ ((i-1) * numPaths) + (j-1) ]

The expressions i-1 and j-1 are used because C has zero-based arrays.

If the store on any path fails for any reason, this function stops and generates a GemBuilder error. Any objects that were successfully stored before the error occurred will remain stored.

Example of a single object and a single path

See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.

This example updates the street address along one path for a single account.

BoolType storePaths_example1(OopType anAccount)
{
   GciErrSType errInfo;
   int path_size = 3;
   int aPath[path_size]; 
   aPath[0] = 2; //customer
   aPath[1] = 2; //address
   aPath[2] = 1; //street
 
   // update anAccount.customer.address.street with the newValue
   OopType newValue = GciNewString("312 North Rd"); 
   int failCount;
   GciStorePaths(&anAccount, 1, aPath, &path_size, 1, &newValue, &failCount);
   if (failCount != 0) {
      printf("GciStorePaths fail count is %d\n", failCount);
      return false;
      }
   if (GciErr(&errInfo)) {
      printf("GciStorePaths error %d, %s\n", errInfo.number, errInfo.message);
      return false;
    }
   return true;
}

Example with multiple objects and multiple paths

This example updates several values along two paths for two Accounts.

BoolType storePaths_example2(int numOfAccounts, OopType* resultAccounts)
{
   GciErrSType errInfo;
   OopType myAccts; 
   myAccts = GciExecuteStr("AllAccounts", OOP_NIL);
   if (myAccts == OOP_NIL) { return false; }
 
   int numRet = GciFetchVaryingOops(myAccts, 1, resultAccounts, numOfAccounts);
   if (numRet != numOfAccounts) { return false; }
  
   int path_segments[2]; 
   path_segments[0] = 2;
   path_segments[1] = 3;
   int serialPath[6]; // size is sum of path_segments
   serialPath[0] = 2; //customer
   serialPath[1] = 1; //name
   serialPath[2] = 2; //customer
   serialPath[3] = 2; //address
   serialPath[4] = 2; //city
   
   OopType newValues[2 * numOfAccounts]; 
      // size of path_segments * number of accounts
   newValues[0] = GciNewString("Samual B. Houston"); 
   newValues[1] = GciNewString("Paisley"); 
   newValues[2] = GciNewString("Maya J. Johnson"); 
   newValues[3] = GciNewString("Bend"); 
 
   int failCount;
   GciStorePaths(resultAccounts, numOfAccounts, serialPath, 
      path_segments, 2, newValues, &failCount);
          
   if (failCount != 0) {
      printf("GciStorePaths fail count is %d\n", failCount);
      return false;
      }
   if (GciErr(&errInfo)) {
      printf("GciStorePaths error %d, %s\n", errInfo.number, errInfo.message);
      return false;
    }
   return true;
}

See Also

GciFetchPaths

GciStoreTrav

Store multiple traversal buffer values in objects.

Syntax

void GciStoreTrav(
GciTravBufType * travBuff,
int behaviorFlag );

Arguments

travBuff 

A traversal buffer, which contains object data to be stored.

behaviorFlag

Flag bits that determines how the objects should be handled. Either use GCI_STORE_TRAV_DEFAULT, or any combination of the other flags.

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

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

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 .

Description

This function stores data from the traversal buffer travBuff into multiple GemStone objects. A traversal buffer is a specialized C structure that optimizes transfer of data. GciStoreTrav, by providing a way to modify and create a number of new object in one command, allows you to reduce the number of GemBuilder calls that are required for your application program to store complex objects in the database.

The first element in the traversal buffer is an integer that indicates how many bytes are stored in the buffer. The remainder of the traversal buffer consists of a series of object reports. Each object report is a C structure of type GciObjRepSType. A GciObjRepSType includes a header with the OOP and class of the object, and a variable-length data area. GciStoreTrav stores data object by object, using one object report at a time.

GciStoreTrav can create new objects and store data into them, or it can modify existing objects with the data in their object reports, or a combination of the two. By default (GCI_STORE_TRAV_DEFAULT), it only modifies existing objects, and it raises an error if an object does not already exist. When GCI_STORE_TRAV_CREATE is used, it modifies any object that already exists and creates a new object when an object does not exist. The new object is initialized with the data in its object report.

To create a new object based on an object report, you need to provide the OOP of the object, using GciGetFreeOops.

When GciStoreTrav modifies an existing object of byte or pointer format, it replaces that object’s data with the data in its object report, regardless of behaviorFlag. All instance variables, named (if any) or indexed (if any), receive new values. Named instance variables for which values are not given in the object report are initialized to nil or to zero. Indexable objects may change in size; the object report determines the new number of indexed variables.

When an existing NSC is modified, it replaces all named instance variables of the NSC (if any), but adds further data in its object report to the unordered variables, increasing its size. If behaviorFlag includes GCI_STORE_TRAV_NSC_REP, then it removes all existing unordered variables and adds new unordered variables with values from the object report.

GciStoreTrav provides automatic byte swizzling. See Byte-Swizzling of Binary Floating-Point Values.

This function raises an error if the traversal buffer contains a report for any object of special implementation format; special objects cannot be modified.

Use of Object Reports

GciStoreTrav stores values in GemStone objects according to the object reports contained in travBuff. Each object report is an instance of the C++ class GciObjRepSType (described in Object Report Header - GciObjRepHdrSType). GciStoreTrav uses the fields in each object report as follows:

report->header.valueBuffSize
The size (in bytes) of the value buffer, where object data is stored. If objId is a Float or SmallFloat and valueBuffSize differs from the actual size for objects of objId’s class, then GciStoreTrav raises an error.

report->header.setIdxSize()
Only needs to be called if the object is indexable. The number of indexed variables in the object stored by GciStoreTrav is never less than this quantity. It may be more if the value buffer contains enough data. GciStoreTrav stores all the indexed variables that it finds in the value buffer. If an existing object has more indexed variables, then it also retains the extras, up to a total of idxSize, and removes any beyond idxSize. If idxSize is larger than the number of indexed variables in both the current object and the value buffer, then GciStoreTrav creates slots for elements in the stored object up to index idxSize and initializes any added elements to nil.

report->header.firstOffset
Ignored for NSC objects. The absolute offset into the target object at which to begin storing values from the value buffer. The absolute offset of the object’s first named instance variable (if any) is one; the offset of its first indexed variable (if any) is one more than the number of its named instance variables. Values are stored into the object in the order that they appear in the value buffer, ignoring the boundary between named and indexed variables. Variables whose offset is less than firstOffset (if any) are initialized to nil or zero. For nonindexable objects, GciStoreTrav raises an error if valueBuffSize and firstOffset imply a size that exceeds the actual size of the object. If objId is a Float or SmallFloat and firstOffset is not one, then GciStoreTrav raises an error.

report->header.objId
The OOP of the object to be stored.

report->header.oclass
Used only when creating a new object, to identify its intended class.

report->header.objectSecurityPolicyId
The ID of the object’s security policy.

report->header.clearBits()
Must be called before any of the following:

report->header.setObjImpl()
You must call rpt->hdr.setObjImpl to set this field to be consistent with the object’s implementation. Formats usable here are GC_FORMAT_OOP, GC_FORMAT_BYTE, and GC_FORMAT_NSC.

report->header.setInvariant()
Boolean value. Call rpt->hdr.setInvariant(TRUE) if you want this object to be made invariant after the store specified by report* is completed.

report->valueBufferBytes()
The value buffer of an object of byte format.

report->valueBufferOops()
The value buffer of an object of pointer or NSC format.

Handling Error Conditions

If you get a runtime error while executing GciStoreTrav, the recommended course of action is to abort the current transaction.

See Also

GciMoreTraversal
GciNbStoreTrav
GciNewOopUsingObjRep
GciProcessDeferredUpdates_
GciStoreTravDo_
GciTraverseObjs

GciStoreTravDo_

Store multiple traversal buffer values in objects, execute the specified code, and return the resulting object.

Syntax

OopType GciStoreTravDo_(
GciStoreTravDoArgsSType * storeTravArgs );

Arguments

storeTravArgs  

An instance of GciStoreTravDoArgsSType.

Return Value

Returns the OOP of the result of executing the specified code. In case of error, this function returns OOP_NIL.

Description

GciStoreTravDo_, like GciStoreTrav, stores data from a traversal buffer into multiple GemStone objects, and also executes supplied code, all in the same network round-trip.

For details of the fields in the instance of GciStoreTravDoArgsSType, see Store Traversal Arguments - GciStoreTravDoArgsSType. The fields of this structure include the traversal buffer and flags as described under GciStoreTrav.

GciStoreTravDoArgsSType includes the doPerform field to indicate different perform options.

  • If doPerform is 0, this function executes a string using args->u.executestr, with the semantics of GciExecuteFromContext.
  • If doPerform is any other value, then executes a perform using
    args->u.perform, with the semantics of GciPerformNoDebug.

The remaining fields supply needed output after the function has completed. Read alteredTheOops to get the OOPs of the objects that were modified and read alteredCompleted to determine if the array as originally allocated was large enough to hold all the modified objects. If the value is false, the array was too small and holds only some of the modified objects; in this case, call GciAlteredObjs for the rest.

Similarly to GciStoreTrav, GciStoreTravDo_ provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.

Handling Error Conditions

If you get a run time error while executing GciStoreTravDo_, we recommend that you abort the current transaction.

See Also

GciAlteredObjs
GciExecuteStrFromContext
GciMoreTraversal
GciNbStoreTravDo_
GciNewOopUsingObjRep
GciPerformNoDebug
GciProcessDeferredUpdates_
GciStoreTrav
GciTraverseObjs

GciStoreTravDoTrav_

Combine in a single function the calls to GciStoreTravDo_ and GciClampedTrav, to store multiple traversal buffer values in objects, execute specified code, and traverse the result object.

Syntax

BoolType GciStoreTravDoTrav_(
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );

Arguments

storeTravArgs   

An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_.

clampedTravArgs   

An instance of GciClampedTravArgsSType. For details, refer to the discussion of GciClampedTrav.

Return Value

Returns FALSE if the traversal is not yet completed. Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal (that is, an object report was constructed for each object, minus the special objects).

Description

This function allows the client to execute behavior on the Gem and return the traversal of the result object in a single network round-trip. See the descriptions for GciStoreTravDo_ on GciStoreTravDo_ and GciClampedTrav on GciClampedTrav for details.

See Also

GciClampedTrav
GciStoreTrav
GciStoreTravDo_

GciStoreTravDoTravRefs_

Combine in a single function modifications to session sets, traversal of objects to the server, optional Smalltalk execution, and traversal to the client of changed objects and (optionally) the result object.

Syntax

int GciStoreTravDoTravRefs_(
const OopType * oopsNoLongerReplicated,
int numNotReplicated,
const OopType * oopsGcedOnClient,
int numGced,
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );

Argumentsv

oopsNoLongerReplicated

An Array of objects to be removed from the PureExportSet and added to the ReferencedSet.

numNotReplicated

The number of elements in oopsNoLongerReplicated.

oopsGCedOnClient

An Array of objects to be removed from both the PureExportSet and ReferencedSet.

numGCed

The number of elements in oopsGcedOnClient.

storeTravArgs

An instance of GciStoreTravDoArgsSType, as described under Store Traversal Arguments - GciStoreTravDoArgsSType.

clampedTravArgs

An instance of GciClampedTravArgsSType. For details, see Clamped Traversal Arguments - GciClampedTravArgsSType, and the discussion of GciStoreTrav.

There is one exception: in this function, retrievalFlags GCI_RETRIEVE_EXPORT and GCI_CLEAR_EXPORT are ignored.

Return Value

Returns an int with the following meaning:

0 — traversal of both altered objects and execution result completed.

1 — traversal buffer became full. You must call GciMoreTraversal to finish traversal of the altered and result objects.

Description

This function allows the client to modify the PureExportSet and ReferencedSet, modify or create any number of objects on the server, execute behavior on the Gem, and return the traversal of the changed objects and the result object, all in a single network round-trip.

The elements in oopsGcedOnClient are removed from both PureExportSet and ReferencedSet, and the elements in oopsNoLongerReplicated are removed from the PureExportSet and added to the ReferencedSet.

GciStoreTravDoArgsSType includes the doPerform field to indicate different perform options. The doPerform, which also determines which nested structure is used in the union field.

  • If doPerform is 0, this function executes a string using args->u.executestr, with the semantics of GciExecute.
  • If doPerform is 1, then executes a perform using
    args->u.perform, with the semantics of GciPerform.
  • If doPerform 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 doPerform 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 doPerform is 4, resume execution of a suspended Smalltalk Process using stdArgs->u.continueArgs, with the semantics of GciContinueWith.

Objects in the ReferencedSet are protected from garbage collection, but may be faulted out of memory. Dirty tracking is not done on objects in the ReferencedSet.

Then per the stdArgs, a GciStoreTrav is done, which may modify or create any number of objects on the server. Newly created objects are added to the PureExportSet.

Then, if specified, Smalltalk execution is performed as in GciPerformNoDebug, GciExecuteStrFromContext, or executing the block code with the given arguments.

Finally, this function does a special GciClampedTrav starting with altered objects, followed by the execution result from the previous step. If no execution was specified, the specified object is traversed as if it was an execution result. Altered objects are those that would be returned from a GciAlteredObjs after the code execution step. This traversal both relies on the contents of the PureExportSet and ReferencedSet does not, and also modifies those sets in ways that GciClampedTrav does not. For details, see the comments in gci.hf.

GciStoreTravDoTravRefs_ is not intended for use within a user action.

See Also

GciAlteredObjs
GciClampedTrav
GciExecuteStrFromContext
GciMoreTraversal
GciNbStoreTravDoTravRefs_
GciPerformNoDebug
GciStoreTrav
GciStoreTravDo_
GciStoreTravDoTrav_
GciTraverseObjs

GciStringToInteger

Convert a C string to a GemStone SmallInteger or LargeInteger object.

Syntax

OopType GciStringToInteger(
const char* string,
int64 stringSize );

Arguments

string

The C string to be translated into a GemStone SmallInteger or LargeInteger object.

stringSize

The length of string.

Return Value

Returns the OOP of the GemStone SmallInteger or LargeInteger object. If string has an invalid format, this function returns OOP_NIL without an error.

Description

The GciStringToInteger function translates a C string to a GemStone SmallInteger or LargeInteger object that has the same value.

Leading blanks are ignored. Trailing non-digits are ignored.

GciStrKeyValueDictAt

Find the value in a symbol KeyValue dictionary at the corresponding string key.

Syntax

void GciStrKeyValueDictAt(
OopType theDict,
const char * keyString,
OopType * value );

Arguments

theDict

The OOP of a SymbolKeyValueDictionary.

keyString

A string that matches a key in theDict.

value

A pointer to the variable that is to receive the OOP of the returned value.

Description

Returns the value in symbol KeyValue dictionary theDict that corresponds to key keyString. If an error occurs or keyString is not found, value is OOP_ILLEGAL. KeyValue dictionaries do not have associations, so no association is returned. GciStrKeyValueDictAt is equivalent to GciStrKeyValueDictAtObj except that the key is a character string, not an object.

See Also

GciStrKeyValueDictAtObj
GciStrKeyValueDictAtPut

GciStrKeyValueDictAtObj

Find the value in a symbol KeyValue dictionary at the corresponding object key.

Syntax

void GciStrKeyValueDictAtObj(
OopType theDict,
OopType keyObj,
OopType * value );

Arguments

theDict

The OOP of a SymbolKeyValueDictionary.

keyObj

The OOP of a key in theDict.

value

A pointer to the variable that is to receive the OOP of the returned value.

Description

Returns the value in symbol KeyValue dictionary theDict that corresponds to key keyObj. If an error occurs or keyObj is not found, value is OOP_ILLEGAL. KeyValue dictionaries do not have associations, so no association is returned. Equivalent to the GemStone Smalltalk expression:

^ { theDict at:keyObj }

See Also

GciStrKeyValueDictAt
GciStrKeyValueDictAtObjPut

GciStrKeyValueDictAtObjPut

Store a value into a symbol KeyValue dictionary at the corresponding object key.

Syntax

void GciStrKeyValueDictAtObjPut(
OopType theDict,
OopType keyObj,
OopType theValue );

Arguments

theDict

The OOP of a SymbolKeyValueDictionary into which the object is to be stored.

keyObj

The OOP of a key under which the value is to be stored.

theValue

The OOP of the object to be stored in the SymbolKeyValueDictionary.

Description

Adds object theValue to symbol KeyValue dictionary theDict with key keyObj. Equivalent to the Smalltalk expression:

theDict at: keyObj put: theValue

See Also

GciStrKeyValueDictAtObj
GciStrKeyValueDictAtPut

GciStrKeyValueDictAtPut

Store a value into a symbol KeyValue dictionary at the corresponding string key.

Syntax

void GciStrKeyValueDictAtPut(
OopType theDict,
const char * keyString,
OopType theValue );

Arguments

theDict

The OOP of a SymbolKeyValueDictionary into which the object is to be stored.

keyObj

The string key under which the value is to be stored.

theValue

The OOP of the object to be stored in the SymbolKeyValueDictionary.

Description

Adds object theValue to symbol KeyValue dictionary theDict with key keyString. GciStrKeyValueDictAtPut is equivalent to GciStrKeyValueDictAtObjPut, except the key is a character string, not an object.

See Also

GciStrKeyValueDictAt
GciStrKeyValueDictAtObjPut

GciSymDictAt

Find the value in a symbol dictionary at the corresponding string key.

Syntax

void GciSymDictAt(
OopType theDict,
const char * keyString,
OopType * value,
OopType * association );

Arguments

theDict

The OOP of a SymbolDictionary.

keyObj

The OOP of a key in theDict.

value

A pointer to the variable that is to receive the OOP of the returned value.

association

A pointer to the variable that is to receive the OOP of the association.

Description

Returns the value in symbol dictionary theDict that corresponds to key keyString. If an error occurs or keyString is not found, value is OOP_ILLEGAL. If association is not NULL and an error does not occur, stores the OOP of the association for keyString at *association, or stores OOP_ILLEGAL if keyString was not found. Equivalent to GciSymDictAtObj except that the key is a character string, not an object.

To operate on kinds of Dictionary other than SymbolDictionary, such as KeyValueDictionary, use GciPerform, since the KeyValueDictionary class is implemented in Smalltalk. If your dictionary will be large (greater than 20 elements) a KeyValueDictionary is more efficient than a SymbolDictionary.

See Also

GciStrKeyValueDictAt
GciSymDictAtObj
GciSymDictAtPut

GciSymDictAtObj

Find the value in a symbol dictionary corresponding to the key object.

Syntax

void GciSymDictAtObj(
OopType theDict,
OopType keyObj,
OopType * value,
OopType * association );

Arguments

theDict

The OOP of a SymbolDictionary.

keyObj

The OOP of a key in theDict.

value

A pointer to the variable that is to receive the OOP of the returned value.

association

A pointer to the variable that is to receive the OOP of the association.

Description

Fetches the value in symbol dictionary theDict that corresponds to key keyObj. If an error occurs or keyObj is not found, value is OOP_ILLEGAL. If association is not NULL and an error does not occur, stores the OOP of the association for keyObj at *association, or stores OOP_ILLEGAL if keyObj was not found. Similar to the GemStone Smalltalk expression:

^ { theDict at: keyObj . theDict associationAt: keyObj }

See Also

GciStrKeyValueDictAtObj
GciSymDictAt
GciSymDictAtObjPut

GciSymDictAtObjPut

Store a value into a symbol dictionary at the corresponding object key.

Syntax

void GciSymDictAtObjPut(
OopType theDict,
OopType keyObj,
OopType theValue );

Arguments

theDict

The OOP of a SymbolDictionary into which the object is to be stored.

keyObj 

The OOP of a key under which the value is to be stored.

theValue

The OOP of the object to be stored in the SymbolDictionary.

Description

Adds object theValue to symbol dictionary theDict with key keyObj. Equivalent to the Smalltalk expression:

theDict at: keyObj put: theValue

See Also

GciStrKeyValueDictAtObjPut
GciSymDictAtObj
GciSymDictAtPut

GciSymDictAtPut

Store a value into a symbol dictionary at the corresponding string key.

Syntax

void GciSymDictAtPut(
OopType theDict,
const char * keyString,
OopType theValue );

Arguments

theDict

The OOP of a SymbolDictionary into which the object is to be stored.

keyString

The string key under which the value is to be stored.

theValue

The OOP of the object to be stored in the SymbolDictionary.

Description

Adds object theValue to symbol dictionary theDict with key keyString. Equivalent to GciSymDictAtObjPut, except the key is a character string, not an object.

See Also

GciStrKeyValueDictAtPut
GciSymDictAt
GciSymDictAtObjPut

GciTraverseObjs

Traverse an array of GemStone objects.

Syntax

BoolType GciTraverseObjs(
const OopType theOops[ ],
int numOops,
GciTravBufType * travBuff,
int level );

Arguments

theOops

An array of OOPs representing the objects to be traversed.

numOops

The number of elements in theOops.

travBuff

A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType.

level

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

Return Value

Returns FALSE if the traversal is not yet completed. Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal.

Description

This function allows you to reduce the number of GemBuilder calls that are required for your application program to obtain information about complex objects in the database.

There are no built-in limits on how much information can be obtained in the traversal. You can use the level argument to restrict the size of the traversal.

GciTraverseObjs provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.

Organization of the Traversal Buffer

The first element placed in a traversal buffer is an integer that indicates how many bytes were actually stored in the buffer by this function. The remainder of the traversal buffer consists of a series of object reports, each of which is of type GciObjRepSType, as described under Use of Object Reports.

To create a traversal buffer, use GciAllocTravBuf. This function takes an argument of the size of traversal buffer to allocate. Multiple the number of object m by the object size to determine the size buffer you require. If the traversal buffer is not large enough, you will need to perform GciMoreTraversal.

The Value Buffer

The object report’s value buffer begins at the first byte following the object report header. For byte objects, the value buffer rpt->valueBufferBytes() is an array of type ByteType; for pointer objects and NSCs, the buffer rpt->valueBufferOops() is an array of type OopType. The size of the report’s value buffer (rpt->hdr.valueBuffSize) is the number of bytes of the object’s value returned by this traversal. That number is no greater than the size of the object.

How This Function Works

This section explains how GciTraverseObjs stores object reports in the traversal buffer and values in the value buffer.

1. First, GciTraverseObjs verifies that the traversal buffer is large enough to accommodate at least one object report header (GciObjRepHdrSType). If the buffer is too small, GemBuilder returns an error.

2. For each object in the traversal, GciTraverseObjs discovers if there is enough space left in the traversal buffer to store both the object report header and the object’s values. If there isn’t enough space remaining, the function returns FALSE, and your program can call GciMoreTraversal to continue the traversal. Otherwise (if there is enough space), the object’s values are stored in the traversal buffer.

3. When there are no more objects left to traverse, GciTraverseObjs returns TRUE to indicate that the traversal is complete.

Special Objects

For each occurrence of an object with a special implementation (that is, an instance of SmallInteger, Character, Boolean, or UndefinedObject) contained in theOops, this function will return an accurate object report. For any special object encountered at some deeper point in the traversal, no object report will be generated.

Authorization Violations

If the user is not authorized to read some object encountered during the traversal, the traversal will continue. No value will be placed in the object report’s value buffer, but the report for the forbidden object will contain the following values:

hdr.valueBuffSize

0

hdr.namedSize

0

hdr.idxSize

0

hdr.firstOffset

1

hdr.objId

theOop

hdr.oclass

OOP_NIL

hdr.objectSecurityPolicyId

0

hdr.objImpl

GC_FORMAT_SPECIAL

hdr.isInvariant

0

Incomplete Object Reports

It is possible for an object report to not contain all the instance variables of an object, due to traversal specifications or buffer size limitations. The value buffer is incomplete when hdr.isPartial() returns non-zero.

Continuing the Traversal

When the amount of information obtained in a traversal exceeds the amount of available memory, your application can break the traversal into manageable amounts of information by issuing repeated calls to GciMoreTraversal. Generally speaking, an application can continue to call GciMoreTraversal until it has obtained all requested information.

During the entire sequence of GciTraverseObjs and GciMoreTraversal calls that constitute a traversal, any single object report will be returned exactly once. Regardless of the connectivity of objects in the GemStone database, only one report will be generated for any non-special object.

When Traversal Can’t Be Continued

Naturally, GemStone will not continue an incomplete traversal if there is any chance that changes to the database in the intervening period might have invalidated the previous report or changed the connectivity of the objects in the path of the traversal. Specifically, GemStone will refuse to continue a traversal if, in the interval before attempting to continue, you:

  • Modify the objects in the database directly, by calling any of the GciStore... or GciAdd... functions;
  • Call one of the Smalltalk message-sending functions GciPerform, GciContinue, or any of the GciExecute... functions;
  • Abort your transaction, thus invalidating any subsequent information from that traversal.

Any attempt to call GciMoreTraversal after one of these actions will generate an error.

Note that this holds true across multiple GemBuilder applications sharing the same GemStone session. Suppose, for example, that you were holding on to an incomplete traversal buffer and the user moved from the current application to another, did some work that required executing Smalltalk code, and then returned to the original application. You would be unable to continue the interrupted traversal.

Example

For an example of how GciTraverseObjs is used, see GciMoreTraversal.

See Also

GciFindObjRep
GciMoreTraversal
GciNbTraverseObjs
GciNewOopUsingObjRep
GciObjRepSize_
GciStoreTrav

GciUncompress

Uncompress the supplied data, assumed to have been compressed with GciCompress.

Syntax

int GciUncompress(
char * dest,
uint * destLen,
const char * source,
uint sourceLen );

Arguments

dest

Pointer to the buffer to hold the resulting uncompressed data.

destLen

Length, in bytes, of the buffer intended to hold the uncompressed data.

source

Pointer to the source data to uncompress.

sourceLen

Length, in bytes, of the source data.

Return Value

GciUncompress returns Z_OK (equal to 0) if the decompression succeeded, or various error values if it failed; see the documentation for the uncompress function in the GNU zlib library at http://www.gzip.org.

Description

GciUncompress passes the supplied inputs unchanged to the uncompress function in the GNU zlib library Version, and returns the result exactly as the GNU uncompress function returns it.

See Also

GciCompress

GciUncompressUsingLz4

Uncompress the supplied data, assumed to have been compressed with GciCompressUsingLz4.

Syntax

int GciUncompress(const char* compressedSource,char* dest,int compressedSourceLen,int destLen);

Arguments

dest

Pointer to the buffer to hold the resulting uncompressed data.

destLen

Length, in bytes, of the buffer intended to hold the uncompressed data.

compressedSource

Pointer to the source data to uncompress.

compressedSourceLen

Length, in bytes, of the source data.

Return Value

Returns the number of bytes decompressed into *dest, or a negative value if an error occurs.

Description

GciUncompress is a wrapper for the lz4 function Wrapper for LZ4_decompress_safe(). Decompress the compressed string at *compressedSource and place the result in *dest. *dest must be already allocated. The exact size of the compressed string at *compressedSource, and the maximum size for the destination must be provided; if destLen is insufficient, decompression stops and the functions returns a negative result.

See Also

GciCompressUsingLz4

GciUserActionInit

Declare user actions for GemStone.

Syntax

void GciUserActionInit( )

Description

GciUserActionInit is implemented by the application developer, but it is called by GciInit. It enables Smalltalk to find the entry points for the application’s user actions, so that they can be executed from the database.

See Also

Chapter 4, “Writing User Actions”
GciDeclareAction
GciInstallUserAction
GciInUserAction
GciUserActionShutdown

GciUserActionShutdown

Enable user-defined clean-up for user actions.

Syntax

void GciUserActionShutdown( )

Description

GciUserActionShutdown is implemented by the application developer, and is called when a session user action library is unloaded. It enables user-defined clean-up for the application’s user actions.

See Also

Chapter 4, “Writing User Actions”
GciDeclareAction
GciInstallUserAction
GciInUserAction
GciUserActionInit

GciUtf8To8Bit

Convert UTF-8 input to 8 bit data.

Syntax

BoolType GciUtf8To8bit(
const char * src,
char * dest,
ssize_t * destSize );

Description

GciUtf8To8bit converts Utf8 input in *src to 8 bit data in *dest. If all code points in *src are in the range 0..255, and the result fits in destSize-1, returns TRUE and *dest is null terminated, otherwise returns FALSE.

GciVersion

Return a string that describes the GemBuilder version.

Syntax

const char* GciVersion( )

Return Value

A null-terminated string, containing period-separated fields that describe the specific release of GemBuilder.

Description

GciVersion gets version information from the shared libraries. The string returned describes the GCI version (that is, the version of the shared libraries, not the version of a GemStone repository).

The version number is provided as a series of period-delimited fields within the string, with the first field being the major version number, the second field the minor version number, and so on. There may be any number of additional fields for a particular version of the GCI. Following this is the build information.

More detailed version information, including Stone version information, can be retrieved using System class methods such as System class >> stoneVersionReport and System class >> gemVersionReport.

Example

BoolType version_example(void)
{
   const char* buf;
   buf = GciVersion();
   printf("Version is %s\n", buf);  
   return ( buf[0] == '3' );
}

An example of the string that is returned is:

Version is 3.4.0 build 64bit-42647

See Also

GciProduct

GciX509Login

Start an X.509-authenticated user session.

Syntax

BoolType GciX509Login(
GciX509LoginArg loginParameters);

Arguments

loginParameters

Instance of the C++ class GciX509LoginArg. This is defined as:

class CLS_EXPORT GciX509LoginArg
public:
const char *
netldiHostOrIp;
const char *
netldiNameOrPort;
const char *
privateKey;
const char *
cert;
const char *
caCert;
const char *
extraGemArgs;
const char *
dirArg;
const char *
logArg;
unsigned int
loginFlags;
BoolType
argsArePemStrings;
BoolType
executedSessionInit;

If argsArePemStrings is true, the privateKey, cert, and caCert are strings in PEM format. If false, these are strings containing the name of a file that is in PEM format.

Return Value

Returns true if login succeeded, false otherwise

Description

This function creates a user session and its corresponding transaction workspace, using authentication using X.509 certificates. This login requires that the NetLDIs be setup to use X509 authentication, as described in the GemStone/S 64 Bit X509-Secured GemStone Administration Guide. Specifically, note that the Stone name and User name and password are not included; these are obtained from the certificates.

See Also

GciEncrypt
GciLogin
GciSetNet
GciSetNetEx

 

Previous chapter

Next chapter