This chapter describes the GemBuilder functions that may be called by your C application program.
Tables Functions for Controlling Sessions and Transactions through Utility Functions summarize the GemBuilder C functions and the services that they provide to your application.
Create and initialize a new instance of DateTime or a subclass of DateTime. |
|
Create a new GemStone object from an existing object report. |
|
Create a new Unicode string object from a UTF-8 encoded C character string. |
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.
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.
%
Abort the current transaction.
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).
Add an OOP to the unordered variables of a nonsequenceable collection.
This function adds an OOP to the unordered variables of an NSC, using structural access.
Add multiple OOPs to the unordered variables of a nonsequenceable collection.
This function adds multiple OOPs to the unordered variables of an NSC, using structural access.
// 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 ++) {
GciAddOopsToNsc(oNsc, values, AddOopsToNsc_SIZE);
GciAddOopToNsc
GciNscIncludesOop
GciRemoveOopFromNsc
GciRemoveOopsFromNsc
(MACRO) Align an address to a word boundary.
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.
Determine if a String contains only 7-bit ASCII characters.
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.
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.
Find all exported or dirty objects that have changed and are therefore in the ExportedDirtyObjs set.
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.
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:
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.
Append bytes to a byte object.
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.
Append OOPs to the unnamed variables of a collection.
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.
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).
(MACRO) Convert a C Boolean value to a GemStone Boolean object.
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).
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;
}
Given a result from GciPointerToByteArray, return a C pointer.
Given an argument that was the result of GciPointerToByteArray, this function returns the corresponding C pointer.
Determine if a GemBuilder call is currently in progress.
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.
Gather the current authorizations for an array of database objects.
void GciCheckAuth(
const OopType oopArray[ ];
ArraySizeType arraySize;
unsigned char authCodeArray[ ] );
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.
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.
(MACRO) Convert a 32 bit C character value to a GemStone Character object.
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.
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.
OopType GCI_CHR_TO_OOP_example(void)
{
// return the OOP for the ASCII character 'a'
OopType theOop = GCI_CHR_TO_OOP('a');
return theOop;
}
Traverse an array of objects, subject to clamps.
BoolType GciClampedTrav(
const OopType * theOops,
int numOops,
GciClampedTravArgsSType * 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. |
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).
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.
Compile a class method for a class.
OopType GciClassMethodForClass(
OopType source,
OopType aClass,
OopType category,
OopType symbolList );
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.
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.
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);
}
}
Find the number of named instance variables in a class.
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. |
Returns the number of named instance variables in the class, or zero if an error occurs.
This function returns the number of named instance variables for the specified class, including those inherited from superclasses.
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;
}
Remove all methods from the method dictionary of a class.
void GciClassRemoveAllMethods(
OopType aClass);
void GciClassRemoveAllMethods_(
OopType aClass,
ushort environmentId );
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.
Clear the Smalltalk call stack.
The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr). |
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.
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);
}
}
}
Write the current transaction to the database.
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.
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.
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");
}
}
}
OopType GciCompileMethod(
OopType source,
OopType aClass,
OopType category,
OopType symbolList,
OopType overrideSelector,
int compileFlags,
ushort environmentId );
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.
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.
Compress the supplied data, which can be uncompressed with GciUncompress.
Pointer to the buffer that will hold the resulting compressed data. |
|
Length, in bytes, of the buffer intended to hold the compressed data. |
|
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.
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.
#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;
}
Compress the supplied data, which can be uncompressed with GciUncompressUsingLz4.
Pointer to the buffer that will hold the resulting compressed data. |
|
Length, in bytes, of the buffer intended to hold the compressed data. |
|
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).
Continue code execution in GemStone after an error.
The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr). |
Returns the OOP of the result of the Smalltalk code that was executed. Returns OOP_NIL in case of error.
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.
See the example for GciClearStack.
Continue code execution in GemStone after an error.
OopType GciContinueWith (
OopType gsProcess,
OopType replaceTopOfStack,
int flags,
GciErrSType * continueWithError );
The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr). |
|
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 to disable or permit asynchronous events and debugging in Smalltalk, as defined for GciPerformNoDebug. |
|
If not NULL, continue execution by signalling this error. This argument takes precedence over replaceTopOfStack. |
Returns the OOP of the result of the Smalltalk code that was executed. In case of error, this function returns OOP_NIL.
Create a new byte-format object.
OopType GciCreateByteObj(
OopType aClass,
OopType objId,
const ByteType * values,
int64 numValues,
int clusterId,
BoolType makePermanent );
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.
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.
Create a new pointer-format object.
OopType GciCreateOopObj(
OopType aClass,
OopType objId,
const OopType * values,
int numValues,
int clusterId,
BoolType makePermanent );
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.
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.)
Convert a C date-time representation to the equivalent GemStone representation.
Converts a time_t value to GciDateTimeSType. On systems where time_t is a signed value, GciCTimeToDateTime generates an error if arg is negative.
Convert a GemStone date-time representation to the equivalent C representation.
Specify the debugging function for GemBuilder to execute before most calls to GemBuilder functions.
Returns a pointer to the newDebugFunc specified in the previous GciDbgEstablish call (if any).
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.
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
}
Write trace information for most GemBuilder functions to a file.
BoolType GciDbgEstablishToFile(
const char * fileName );
BoolType GciDbgEstablishToFile_(
const char * fileName ,
GciErrSType *err);
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.
Pass a message to a trace function.
If either GciDbgEstablish or GciDbgEstablishToFile has been called to activate tracing of GemBuilder calls, this function passes the argument to the trace function.
Initiate the connection to another session for debugging.
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. |
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.
Connect to another session for debugging.
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);
Associate a C function with a Smalltalk user action.
void GciDeclareAction(
const char* name,
void* func,
int nunArgs,
uint flags,
BoolType errorIfDuplicate );
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).
(MACRO) Associate a C function with a Smalltalk user action.
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).
Decode an OOP array that was previously run-length encoded.
int GciDecodeOopArray(
OopType * encodedOopArray,
const int numEncodedOops,
OopType * decodedOopArrray,
const int decodedOopsSize);
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.
Decrement the value of a shared counter.
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.
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.
GciFetchNumSharedCounters
GciIncSharedCounter
GciSetSharedCounter
GciReadSharedCounter
GciReadSharedCounterNoLock
GciFetchSharedCounterValuesNoLock
Find all objects in the ExportedDirtyObjs set.
The maximum number of objects that can be put into theOops buffer. On return, the number of dirty exported objects found. |
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.
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:
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.
Begin tracking which objects in the session workspace change.
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:
Find all exported objects that have changed and are therefore in the ExportedDirtyObjs set.
The maximum number of objects that can be put into theOops buffer. On return, the number of dirty cached objects found |
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.
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:
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.
Convert a C double to a SmallDouble object.
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.
Enable full compression between the client and the RPC version of GemBuilder.
Establish or remove GemBuilder visibility to signaled errors from GemStone.
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.
Encode an array of OOPs, using run-length encoding.
int GciEncodeOopArray(
OopType * oopArray,
const int numOops,
OopType * encodedOopArray,
BoolType needsSorting );
If oopArray is known to be in ascending order, set this to FALSE; otherwise set it to TRUE. |
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.
Returns a pointer to the first character of the encrypted password in outBuff[], or NULL if the encrypted password is larger than outBuffSize.
This function encrypts a host or GemStone password for use in GciSetNetEx or GciLogin with password encyrption enabled.
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;
}
Prepare a report describing the most recent GemBuilder error.
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.
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.
Execute a Smalltalk expression contained in a GemStone String or Utf8 object.
Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.
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.
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;
}
Execute a Smalltalk expression contained in a String or Utf8 object as if it were a message sent to another object.
Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.
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.
Execute a Smalltalk expression contained in a C string.
Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.
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.
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);
}
}
Execute a Smalltalk expression contained in a C string, returning byte-format results.
int64 GciExecuteStrFetchBytes(
const char * source,
int64 sourceSize,
OopType sourceClass,
OopType contextObject,
OopType symbolList,
ByteType * result,
int64 maxResultSize );
Execute a Smalltalk expression contained in a C string as if it were a message sent to an object.
OopType GciExecuteStrFromContext(
const char source[ ],
OopType contextObject,
OopType symbolList );
Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.
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.
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);
}
}
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.
BoolType GciExecuteStrTrav(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList,
GciClampedTravArgsSType * travArgs );
A null-terminated string containing a sequence of one or more Smalltalk statements to be executed. |
|
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. |
|
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). |
|
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. |
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.
Fetch one byte from an indexed byte object.
The index into theObject of the element to be fetched. The index of the first element is 1. |
Returns the byte value at the specified index. In case of error, this function returns zero.
This function fetches a single element from a byte object at the specified index, using structural access.
Fetch multiple bytes from an indexed byte object.
int64 GciFetchBytes_(
OopType theObject,
int64 startIndex,
ByteType theBytes[ ],
int64 numBytes );
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.
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.
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;
}
Fetch multiple ASCII characters from an indexed byte object.
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.
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.
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.
#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);
}
Convert the contents of a DateTime object and place the results in a C structure.
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.
Convert the contents of a DateAndTime object and place the results in a C structure.
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.
Convert the contents of a DateAndTime object and place the results in a C structure.
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.
Fetch the OOP of one of an object’s dynamic instance variables.
Returns the OOP of the specified dynamic instance variable. If no such dynamic instance variable exists in the object, this function returns OOP_NIL.
This function fetches the contents of an object’s dynamic instance variable, as specified by aSymbol.
Fetches the OOPs of one or more of an object’s dynamic instance variables.
Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.)
The number of dynamic instance variable pairs returned is (function result / 2). To obtain all dynamic instance variables in one call, use a buffer.
Fetch the OOP of one of an object’s named instance variables.
The index into theObject’s named instance variables of the element to be fetched. The index of the first named instance variable is 1. |
Returns the OOP of the specified named instance variable. In case of error, this function returns OOP_NIL.
This function fetches the contents of an object’s named instance variable at the specified index, using structural access.
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;
}
Fetch the OOPs of one or more of an object’s named instance variables.
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.
This function uses structural access to fetch multiple values from an object’s named instance variables, starting at the specified index.
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) ;
}
Fetch the number of named instance variables in an object.
Returns the number of named instance variables in theObject. In case of error, this function returns zero.
This function returns the number of named instance variables in a GemStone object. See the example for GciFetchNamedOops.
Obtain the number of shared counters available on the shared page cache used by this session.
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.
Fetch information and values from an object.
Pointer to an instance of GciFetchObjInfoArgsSType with the following argument fields:
GciObjInfoSType * info
ByteType * buffer
int64 startIndex
int64 bufSize
int64 numReturned
int retrievalFlags |
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.
Fetch the implementation of an object.
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.
This function obtains the implementation of an object (pointer, byte, NSC, special) from GemStone. For more information about implementation types, see Object implementation.
Fetch the OOP of one instance variable of an object.
Returns the OOP at the specified index of the source object. In case of error, this function returns OOP_NIL.
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.
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;
}
Fetch the OOPs of one or more instance variables of an object.
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.
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.
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;
}
Fetch selected multiple OOPs from an object tree.
BoolType GciFetchPaths(
const OopType theOops[ ],
int numOops,
const int paths[ ],
const int pathSizes[ ],
int numPaths,
OopType results[ ] );
Returns TRUE if all desired objects were successfully fetched. Returns FALSE if the fetch on any path fails for any reason.
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:
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;
}
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;
}
Fetch the value of multiple shared counters without locking them.
int GciFetchSharedCounterValuesNoLock(
int startIndex,
int64_t buffer[ ],
size_t * maxReturn);
Returns an int indicating the number of shared counter values successfully stored in the buffer. Returns -1 if a bad argument is detected.
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.
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:
Number of indexed elements PLUS number of named instance variables |
||
Encode a String, MultiByteString, or Uft8 as UTF-8, and fetch the bytes of the encoded result.
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);
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.
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.
Fetch the OOP of one unnamed instance variable from an indexable pointer object or NSC.
The index of the OOP to be fetched. The index of the first unnamed instance variable’s OOP is 1. |
Returns the OOP of the unnamed instance variable at index atIndex. In case of error, this function returns OOP_NIL.
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.
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;
}
Fetch the OOPs of one or more unnamed instance variables from an indexable pointer object or NSC.
int GciFetchVaryingOops(
OopType theObject,
int64 startIndex,
OopType theOops[ ],
int numOops );
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.
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.
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;
}
Fetch the number of unnamed instance variables in a pointer object or NSC.
Returns the number of unnamed instance variables in theObject. In case of error, this function returns zero.
This function obtains from GemStone the number of indexed variables in an indexable object or the number of unordered variables in an NSC.
See an example under GciFetchOop.
Fetch an object report in a traversal buffer.
Returns a pointer to an object report within the traversal buffer. In case of error, this function returns NULL.
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.
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;
}
Obtain the float kind corresponding to a C double value.
This function obtains the kind of GemStone Float object that corresponds to the C floating point value aReal.
Convert a C double value to a SmallDouble or Float object.
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.
This function translates a C double precision value into the equivalent GemStone Float object.
#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);
}
Returns an unused object identifier (OOP).
You cannot use the result of GciGetFreeOop to create a Symbol object.
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:
GciCreateByteObj
GciCreateOopObj
GciStoreOop
GciStoreOops
GciStoreIdxOop
GciStoreIdxOops
GciStoreNamedOop
GciStoreNamedOops
GciStoreTrav
GciAppendOops
GciAddOopToNsc
GciAddOopsToNsc
GciNewOopUsingObjRep
GciStorePaths
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:
GciCreateByteObj
GciCreateOopObj
GciStoreOop
GciStoreOops
GciStoreIdxOop
GciStoreIdxOops
GciStoreNamedOop
GciStoreNamedOops
GciStoreTrav
GciAppendOops
GciAddOopToNsc
GciAddOopsToNsc
GciNewOopUsingObjRep
GciStorePaths
The number of OOPs to allocate. On return, the number of OOPs that were allocated. |
|
A pointer to memory for holding encoded OOPs. Must be at least the size specified by count. |
Find the ID number of the current user session.
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).
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.
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);
}
}
Interrupt GemStone and abort the current transaction.
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
Determines whether the given OOP is present in the specified hidden set.
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.
Convert a C 32-bit integer value to a GemStone object.
The GciI32ToOop function returns the OOP of a GemStone object whose value is equivalent to anInt.
The GciI32ToOop function translates a C 32bit integer value into the equivalent GemStone object. This function always succeeds.
(MACRO) Determine whether or not a 64-bit C integer is in the SmallInteger range.
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.
Convert a C 64-bit integer value to a GemStone object.
The GciI64ToOop function returns the OOP of a GemStone object whose value is equivalent to anInt.
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.
Increment the value of a shared counter.
Returns a C Boolean value indicating if the shared counter was successfully incremented. Returns TRUE if successful, FALSE if an error occurred.
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.
GciDecSharedCounter
GciFetchNumSharedCounters
GciFetchSharedCounterValuesNoLock
GciReadSharedCounter
GciReadSharedCounterNoLock
GciSetSharedCounter
The function GciInit returns TRUE or FALSE to indicate successful or unsuccessful initialization of GemBuilder. .
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.
Initialize GemBuilder, including arguments.
(int) GciInit_(
BoolType quietMode,
GciProcessType processType,
GciCfgFileArgs *cfg,
char *configFileWarn,
size_t warnSize
);
The function GciInit_ returns 0 for success, -2 for errors in the configuration file, and -2 for memory allocation errors in libgcilnk.
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.
Override the default application configuration file name.
void GciInitAppName(
const char * applicationName,
BoolType logWarnings );
void GciInitAppName_(
const char * applicationName,
BoolType logWarnings,
unsigned int gemTOCOverrideKB,
int gemNativeCodeOverride );
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_.
Associate a C function with a Smalltalk user action.
void GciInstallUserAction(
GciUserActionSType * userAction );
void GciInstallUserAction_(
GciUserActionSType * userAction,
BoolType errorIfDuplicate );
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”
Compile an instance method for a class.
OopType GciInstMethodForClass(
OopType source,
OopType aClass,
OopType category,
OopType symbolList );
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.
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.
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);
}
}
Determine whether or not the current process is executing a user action.
This function returns TRUE if it is called from within a user action, and FALSE otherwise.
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.
Determine whether or not an object is some kind of a given class or class history.
GciIsKindOf returns TRUE when the class of anObj or any of its superclasses is in the class history of possibleClass. It returns FALSE otherwise.
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.
Determine whether or not an object is some kind of a given class.
GciIsKindOfClass returns TRUE when the class of anObject or any of its superclasses is possibleClass. It returns FALSE otherwise.
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.
Determine whether the application is running linked or remotely.
Determine whether or not a class is a subclass of a given class or class history.
GciIsSubclassOf returns TRUE when testClass or any of its superclasses is in the class history of possibleClass. It returns FALSE otherwise.
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.
Determine whether or not a class is a subclass of a given class.
GciIsSubclassOf returns TRUE when testClass or any of its superclasses is possibleClass. It returns FALSE otherwise.
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.
Fetch the index of an instance variable name.
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.
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.
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;
}
Load an application user action library.
BoolType GciLoadUserActionLibrary(
const char * uaLibraryName[ ],
BoolType mustExist,
void ** libHandlePtr,
char infoBuf[ ],
int64 infoBufSize );
The name and location of the user action library file (a null-terminated string). |
|
A buffer to store the name of the user action library or an error message. |
|
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.
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.
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.
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;
}
Start a user session with session configuration
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);
A legacy error number; if nonzero, specifies a value for GEM_HALT_ON_ERROR config parameter. |
Set to TRUE if login succeeded and and GsCurrentSession initialize was executed in the new session. |
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.
For an example, see GciEncrypt
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. |
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.)
Provides equivalent functionality to the corresponding longjmp() or _longjmp() function.
Continue object traversal, reusing a given buffer.
A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType. |
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.
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:
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.
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);
}
Abort the current transaction (nonblocking).
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.
Begin a new transaction (nonblocking).
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.
Traverse an array of objects, subject to clamps (nonblocking).
void GciNbClampedTrav(
const OopType * theOops,
int numOops,
GciClampedTravArgsSType * 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. |
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.
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.
Write the current transaction to the database (nonblocking).
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.
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.
Continue code execution in GemStone after an error (nonblocking).
The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr). |
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.
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.
Continue code execution in GemStone after an error (nonblocking).
void GciNbContinueWith (
OopType process,
OopType replaceTopOfStack,
int flags,
GciErrSType * error );
The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr). |
|
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 to disable or permit asynchronous events and debugging in Smalltalk, as defined for GciPerformNoDebug. |
|
If not NULL, continue execution by signalling this error. This argument takes precedence over replaceTopOfStack. |
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.
Test the status of nonblocking call in progress for completion.
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.
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.
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);
}
}
Test the status of nonblocking call in progress for completion, with timeout.
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.
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.
Execute a Smalltalk expression contained in a String object (nonblocking).
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.
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.
Execute a Smalltalk expression contained in a String object (nonblocking) as if it were a message sent to an object (nonblocking).
void GciNbExecuteFromContextDbg_(
OopType source,
OopType contextObject,
OopType symbolList,
int flags,
ushort environmentId);
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.
Execute a Smalltalk expression contained in a C string (nonblocking).
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.
Execute a Smalltalk expression contained in a C string, returning byte-format results (nonblocking).
void GciNbExecuteStrFetchBytes(
const char * sourceStr,
int64 sourceSize,
OopType sourceClass,
OopType contextObject,
OopType symbolList,
ByteType * result,
int64 maxResultSize );
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.
Execute a Smalltalk expression contained in a C string as if it were a message sent to an object (nonblocking).
void GciNbExecuteStrFromContext(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList );
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.
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).
void GciNbExecuteStrTrav(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList,
GciClampedTravArgsSType * travArgs );
A null-terminated string containing a sequence of one or more Smalltalk statements to be executed. |
|
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. |
|
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). |
|
Pointer to an instance of GciClampedTravArgsSType. See GciExecuteStrTrav for field definitions. |
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.
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.
GciExecuteStrTrav includes information details on traversal.
GciNbEnd
GciNbExecute
GciPerformTraverse
Start a user session with session configuration (nonblocking)
BoolType GciNbLoginEx(
const char gemstoneUsername[ ],
const char gemstonePassword[ ] ,
unsigned int loginFlags,
int haltOnErrNum);
A legacy error number; if nonzero, specifies a value for GEM_HALT_ON_ERROR config parameter. |
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.
Continue object traversal, reusing a given buffer (nonblocking).
A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType. |
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.
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.
Send a message to a GemStone object (nonblocking).
void GciNbPerform(
OopType receiver,
const char selectorStr[ ],
const OopType args[ ],
int numArgs );
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.
Send a message to a GemStone object, returning byte results (nonblocking).
void GciNbPerformFetchBytes(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
ByteType * result,
ssize_t maxResultSize);
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.
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.
Send a message to a GemStone object, and temporarily disable debugging (nonblocking).
void GciNbPerformNoDebug(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
int flags );
A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:). |
|
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. |
|
The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero. |
|
Flags to disable or permit asynchronous events and debugging in Smalltalk. Use one or more of the GemBuilder mnemonics described under GciPerformNoDebug. |
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.
First send a message to a GemStone object, then traverse the result of the message (nonblocking).
void GciNbPerformTrav(
OopType receiver,
const char * selector,
const OopType * args,
int numArgs,
GciClampedTravArgsSType * travArgs );
A string that defines the message selector. For keyword selectors, all keywords are concatenated in the string. (For example, at:put:). |
|
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. |
|
The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero. |
|
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. |
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.
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.
Stores multiple traversal buffer values in objects (nonblocking).
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.
Store multiple traversal buffer values in objects, execute the specified code, and return the resulting object (non-blocking).
An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_ |
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.
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).
void GciNbStoreTravDoTrav_(
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );
An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_. |
|
An instance of GciClampedTravArgsSType. For details, refer to the discussion of GciClampedTrav. |
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.
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.
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).
void GciNbStoreTravDoTravRefs_(
const OopType * oopsNoLongerReplicated,
int numNotReplicated,
const OopType * oopsGcedOnClient,
int numGced,
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );
An Array of objects to be removed from the PureExportSet and added to the ReferencedSet. |
|
An Array of objects to be removed from both the PureExportSet and ReferencedSet. |
|
An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_. |
|
An instance of GciClampedTravArgsSType. For details, see the discussion of GciClampedTrav on here. |
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
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.
Traverse an array of GemStone objects (nonblocking).
void GciNbTraverseObjs(
const OopType theOops[ ],
int numOops,
GciTravBufType * travBuff,
int level );
A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType. |
|
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. |
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.
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.
Create and initialize a new byte object.
The OOP of the class of which the new object is an instance. aClass must be a class whose format is BYTE. |
|
Pointer to an array of byte values to be stored in the newly-created object. |
|
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.
Create and initialize a new character object.
Returns a new instance of aClass which has been initialized to contain the bytes of cString, excluding the null terminator.
Create and initialize a new instance of DateTime or a subclass of DateTime.
Creates a new instance of theClass having the value that timeVal points to. For details on GciDateTimeSType, see GciDateTimeSType.
Create and initialize a new instance of DateAndTime.
Creates a new instance of DateAndTime having the value that dateAndTimeVal points to. For details on GciDateAndTime, see GciDateAndTime.
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.
Create multiple new GemStone objects.
void GciNewOops(
int numOops,
const OopType classes[ ],
const int64 idxSize[ ],
OopType result[ ] );
If an error is encountered, this function will stop at the first error and the contents of the result array will be undefined.
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:
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]);
}
}
Create a new GemStone object from an existing object report.
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.)
In addition to general GemBuilder error conditions, this function generates an error if any of the following conditions exist:
Note that you cannot use this function to create new special objects (instances of SmallInteger, Character, Boolean, SmallDouble, or UndefinedObject).
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);
}
}
Create a new Unicode string object from a UTF-8 encoded C character string.
OopType GciNewUtf8String(
const char * unicodeCString,
BoolType utf8OrUnicode );
OopType GciNewUtf8String_(
const char * unicodeCString,
size_t nBytes,
BoolType utf8OrUnicode );
Determines whether the given OOP is present in the specified unordered collection.
GciNscIncludesOop searches the specified unordered collection to determine if it includes the specified object. It is equivalent to the GemStone Smalltalk method UnorderedCollection >> includesIdentical:.
Find the number of bytes in an object report.
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.
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");
}
}
(MACRO) Determine whether or not a GemStone object represents a GemStone Smalltalk Boolean.
(MACRO) Determine whether or not a GemStone object represents a Character.
(MACRO) Determine whether or not a GemStone object represents a SmallDateAndTime.
(MACRO) Determine whether or not a GemStone object represents a SmallDouble.
(MACRO) Determine whether or not a GemStone object represents a SmallFraction.
(MACRO) Determine whether or not a GemStone object represents a SmallInteger.
(MACRO) Determine whether or not a GemStone object represents a SmallScaledDecimal.
(MACRO) Determine whether or not a GemStone object has a special representation.
A C Boolean value. Returns TRUE if the object has a special representation, FALSE otherwise.
Convert a Boolean object to a C Boolean value.
Returns the C Boolean value that corresponds to the GemStone object. In case of error, this function returns FALSE.
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;
}
(MACRO) Convert a Boolean object to a C Boolean value.
A C Boolean value. Returns the C Boolean value that corresponds to the GemStone object. In case of error, this macro returns FALSE.
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
Convert a Character object to a 16-bit C character value.
Returns the 16-bit C character value that corresponds to the GemStone object. In case of error, this function returns zero.
This function translates a GemStone Character object into the equivalent 16-bit C character value.
Convert a Character object to a 32-bit C character value.
Returns the 32-bit C character value that corresponds to the GemStone object. In case of error, this function returns zero.
This function translates a GemStone Character object into the equivalent 32-bit C character value.
Convert a Character object to a C character 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.
This function translates a GemStone Character object into the equivalent C character value.
(MACRO) Convert a Character object to a C character 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.
Convert a SmallDouble, Float, or SmallFloat object to a C double.
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.
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
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;
}
Convert a GemStone object to a C 32-bit integer value.
TRUE if theObject does not fit in the result type or is not an Integer, otherwise unchanged. |
The GciOopToI32 and GciOopToI32_ functions return the C 32-bit integer value that is equivalent to the value of theObject.
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.
Convert a GemStone object to a C 64-bit integer value.
TRUE if theObject does not fit in the result type or is not an Integer, otherwise unchanged. |
The GciOopToI64 and GciOopToI64_ functions return the C int64_t value that is equivalent to the value of theObject.
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.
Send a message to a GemStone object.
OopType GciPerform(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs );
Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.
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.
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);
}
Send a message to a GemStone object, returning byte results.
OopType GciPerformFetchBytes(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
ByteType * result,
ssize_t maxResultSize);
Returns number of bytes returned in *result, or -1 if an error is available to be fetched with GciErr.
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.
Send a message to a GemStone object, and temporarily disable debugging.
OopType GciPerformNoDebug(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
int flags );
Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.
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:
Send a message to a GemStone object, using a String object as a selector.
OopType GciPerformSymDbg(
OopType receiver,
OopType selector,
const OopType args[ ],
int numArgs,
int flags );
Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.
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.
First send a message to a GemStone object, then traverse the result of the message.
BoolType GciPerformTrav(
OopType receiver,
const char * selector,
const OopType * args,
int numArgs,
GciClampedTravArgsSType * travArgs );
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:). |
|
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. |
|
The number of arguments to the message. For unary selectors (messages with no arguments), numArgs is zero. |
|
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. |
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.
First send a message to a GemStone object, then traverse the result of the message.
BoolType GciPerformTraverse(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
GciTravBufType * travBuff,
int level );
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.
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.
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;
}
Given a C pointer, return a SmallInteger or ByteArray containing the value of the pointer.
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.
Poll GemStone for signal errors without executing any Smalltalk methods.
This function returns TRUE if a signal error or an asynchronous error exists, and FALSE otherwise.
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.
Discard a previously saved error jump buffer.
A pointer to a jump buffer specified in an earlier call to GciPushErrJump. |
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.
void popErr_example(void)
{
GciJmpBufSType jumpBuff1, jumpBuff2, jumpBuff3, jumpBuff4;
GciPushErrJump(&jumpBuff1);
GciPushErrJump(&jumpBuff2);
GciPushErrJump(&jumpBuff3);
GciPushErrJump(&jumpBuff4);
GciPopErrJump(&jumpBuff1); /* pops buffers 1-4 */
}
Process deferred updates to objects that do not allow direct structural update.
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:
Return an 8-bit unsigned integer that indicates the GemStone/S product.
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.
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.
Associate GemBuilder error handling with a jump buffer by pushing a jump buffer onto the stack.
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. |
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.
For an example of how GciPushErrJump is used, see GciPopErrJump.
Signal an error, synchronously, within a user action.
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.
Lock and fetch the value of a shared counter.
Returns a C Boolean value indicating whether the value was successfully read. Returns TRUE if successful, FALSE if an error occurred.
Fetch the value of a shared counter without locking it.
Returns a C Boolean value indicating whether the value was successfully read. Returns TRUE if successful, FALSE if an error occurred.
Remove all OOPS from the PureExportSet, making these objects eligible for garbage collection.
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.
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.
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.
Remove an array of GemStone OOPs from the PureExportSet, making them eligible for garbage collection.
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.
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.
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.
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); }
}
Returns FALSE if theOop was not present in the NSC. Returns TRUE if theOop was present.
This function removes an OOP from the unordered variables of an NSC, using structural access.
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;
}
Remove one or more OOPs from an NSC.
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.
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.
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;
}
Replace all instance variables in a GemStone object.
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.
Find the OOP of the object to which a symbol name C string refers, in the context of the current session’s user profile.
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.
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.
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.
Report whether a GemBuilder library is loaded.
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.
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.
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.
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);
}
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.
Add an array of OOPs to the PureExportSet, making them ineligible for garbage collection.
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.
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.
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.
Determine whether or not the current session is using a Gem on another machine.
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.
Enable or disable the current error handler.
TRUE enables error jumps to the execution environment saved by the most recent GciPushErrJump; FALSE disables error jumps. |
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.
This function enables or disables the error handler at the top of GemBuilder’s error jump stack.
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
}
Halt the current session when a specified error occurs.
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.
(MACRO) Save a jump buffer in GemBuilder’s error jump stack.
Set network parameters for connecting the user to the Gem and Stone processes.
void GciSetNet(
const char stoneNameNrs[ ],
const char HostUserId[ ],
const char HostPassword[ ],
const char gemServiceNrs[ ] );
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.
For an example of how GciSetNet is used, see the example for GciLogin.
Set network parameters for connecting the user to the Gem and Stone processes, allowing encryption.
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);
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.
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.
For an example of how GciSetNet is used, see GciLogin.
Set an active session to be the current one.
This function can be used to switch between multiple GemStone sessions in an application program with multiple logins.
Set the value of a shared counter.
The offset into the shared counters array of the value to modify. |
|
Pointer to a value that containing the new value for this shared counter. |
Returns a C Boolean value indicating whether the value was successfully changed. Returns TRUE if the modification succeeded, FALSE if it failed.
Control swizzling of the traversal buffers.
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.
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 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.
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));
}
Logout from all sessions and deactivate GemBuilder.
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. |
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.
Interrupt the execution of Smalltalk code, but permit it to be restarted.
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.
#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);
}
Continue code execution in GemStone with specified single-step semantics.
OopType GciStep(
OopType gsProcess,
int level );
OopType GciStep_(
OopType gsProcess,
int level
BoolType through);
Returns the OOP of the result of the Smalltalk execution. Returns OOP_ILLEGAL in case of error.
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.
Store one byte in a byte object.
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.
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 );
}
}
(MACRO) Store multiple bytes in a byte object.
void GciStoreBytes(
OopType theObject,
int64 startIndex,
const ByteType theBytes[ ],
int64 numBytes );
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.
GciStoreBytes raises an error if theObject is a Float or SmallFloat. Use GciStoreBytesInstanceOf instead for Float or SmallFloat objects.
Store multiple bytes in a byte object.
void GciStoreBytesInstanceOf(
OopType theClass,
OopType theObject,
int64 startIndex,
const ByteType theBytes[ ],
int64 numBytes );
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.
Store multiple ASCII characters in a byte object.
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.
void storeChars_example(void)
{
OopType oString = GciNewOop(OOP_CLASS_STRING);
GciStoreChars(oString, 1, "some string data");
}
Create or change the value of an object’s dynamic instance variable.
Creates or changes the value of the dynamic instance variable specified by aSymbol within theObject.
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.
Store one OOP in an indexable pointer object’s unnamed instance variable.
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.)
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);
}
Store one or more OOPs in an indexable pointer object’s unnamed instance variables.
void GciStoreIdxOops(
OopType theObject,
int64 startIndex,
const OopType theOops[ ],
int numOops );
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.)
OopType oArray = GciExecuteStr("Array new: 10", OOP_NIL);
OopType oGlobals = GciExecuteStr("Globals", OOP_NIL);
// Fetch first 10 elements in Globals
int numRet = GciFetchVaryingOops(oGlobals, 1, oBuffer, buf_size);
GciStoreIdxOops(oArray, 1, oBuffer, numRet);
printf("Error %d, %s\n", err.number, err.message);
// release results of execution
GciAddOopToNsc
GciFetchVaryingOops
GciReplaceOops
GciReplaceVaryingOops
GciStoreIdxOops
GciStoreNamedOops
GciStoreOops
Store one OOP into an object’s named instance variable.
This function stores a single OOP into an object’s named instance variable at the specified index, using structural access.
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);
}
Store one or more OOPs into an object’s named instance variables.
void GciStoreNamedOops(
OopType theObject,
int64 startIndex,
const OopType theOops[ ],
int numOops );
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.
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 =