7. GemBuilder C Function Reference
This chapter describes the GemBuilder functions that may be called by your C application program.
7.1 Function Summary Tables
Tables Functions for Controlling Sessions and Transactions through Utility Functions summarize the GemBuilder C functions and the services that they provide to your application.
|
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.
7.2 Executing the examples
The following topaz input defines classes and objects that are used in some of the examples for functions.
run
Array subclass: #Account
instVarNames: #(#id #customer #salesRep) inDictionary: UserGlobals.
Object subclass: #Customer
instVarNames: #(#name #address) inDictionary: UserGlobals.
Object subclass: #Address
instVarNames: #(#street #city #state) inDictionary: UserGlobals.
%
run
Account compileMissingAccessingMethods.
Customer compileMissingAccessingMethods.
Address compileMissingAccessingMethods.
%
method: Address
asString
^ self street, ' ', self city, ', ', self state
%
method: Customer
asString
^ self name, ', ', self address asString.
%
method: Account
asString
^'Account ', self id asString, ' for ', self customer asString
%
run
UserGlobals at: #AllAccounts put: IdentityBag new.
%
run
| createBlk |
createBlk := [:data | | addr cust acct |
addr := Address new street: (data at: 2); city: (data at: 3);
state: (data at: 4); yourself.
cust := Customer new name: (data at: 1); address: addr;
yourself.
acct := Account new id: (data at: 5); customer: cust;
salesRep: (data at: 6); yourself.
acct addAll: (data at: 6).
acct].
{
{'Sam Houston' . '2321 Walnut Dr' . 'Myrtle Point' .
'OR' . 7212. 'Mark Rabinowitz'. { 'GS64' . 'GBS/VA'} } .
{'Maya Johnson' . '12 Main Str' . 'Ashland' . 'OR' .
2323. 'Mark Rabinowitz' . {'GS64' . 'GBS/VW' . 'GemConnect'}} .
{'Mario Harar' . '12 N. First Str' . 'Washougal' . 'WA' .
10073. 'Linda Waffle'. { 'GS64' } } }
do:
[:dataArr | AllAccounts add: (createBlk value: dataArr)].
System commitTransaction.
%
GciAbort
Abort the current transaction.
Description
This function causes the GemStone system to abort the current transaction. All changes to persistent objects that were made since the last committed transaction are lost, and the application is connected to the most recent version of the database. Your application must fetch again from GemStone any changed persistent objects, to refresh the copies of these objects in your C program. Use the GciDirtySaveObjs function to determine which of the fetched objects were also changed.
This function has the same effect as issuing a hard break, or the function call GciExecuteStr("System abortTransaction", OOP_NIL).
GciAddOopToNsc
Add an OOP to the unordered variables of a nonsequenceable collection.
Arguments
Description
This function adds an OOP to the unordered variables of an NSC, using structural access.
GciAddOopsToNsc
Add multiple OOPs to the unordered variables of a nonsequenceable collection.
Arguments
Description
This function adds multiple OOPs to the unordered variables of an NSC, using structural access.
Example
OopType GciAddOopsToNsc_example(void)
{
// return an IdentityBag containing the SmallIntegers with value 0..99
enum { AddOopsToNsc_SIZE = 100 };
OopType oNsc = GciNewOop(OOP_CLASS_IDENTITY_BAG);
OopType values[AddOopsToNsc_SIZE];
for (int i = 0; i < AddOopsToNsc_SIZE; i ++) {
values[i] = GciI32ToOop(i);
}
GciAddOopsToNsc(oNsc, values, AddOopsToNsc_SIZE);
return oNsc;
}
GCI_ALIGN
(MACRO) Align an address to a word boundary.
Description
This macro can be used to round up a pointer or size to be a multiple of sizeOf(OopType).
Provided for compatibility. New code should use the accessor functions in GciObjRepHdrSType; see Object Report Header - GciObjRepHdrSType.
GciAll7Bit
Determine if a String contains only 7-bit ASCII characters.
Arguments
Return Value
Returns TRUE if each character in aString is in the 7-bit ASCII range, that is, a value <= 127; FALSE if any characters have values of 128 or higher.
Description
The function GciAll7Bit is used to test if a String is in the ASCII range, which will not involve encoding to UTF-8 for storage.
See Also
GciAlteredObjs
Find all exported or dirty objects that have changed and are therefore in the ExportedDirtyObjs or TrackedDirtyObjs sets.
Arguments
Return Value
The function result indicates whether all dirty objects have been returned. If the operation is not complete, GciAlteredObjs returns FALSE, and it is expected that the application will make repeated calls to this function until it returns TRUE, indicating that all of the dirty objects have been returned. If repeated calls are not made, then the unreturned objects persist in the list until the next time GciAlteredObjs, or another call that destructively accesses the ExportedDirtyObjs or TrackedDirtyObjs sets, is called.
Description
Typically, a GemStone C application program caches some database objects in its local object space, generally in the PureExportSet or if in a user action, in the user action’s export set (see GciSaveObjs). It may also track them by storing them in the GciTrackedObjs set (see GciSaveAndTrackObjs). After an abort or a successful commit, the user’s session is resynchronized with the most recent version of the database. The values of instance variables cached in your C program may no longer accurately represent the corresponding GemStone objects. In such cases, your C program must update its representation of those objects. The function GciAlteredObjs permits you to determine which objects your application needs to reread from the database.
This function returns a list of all objects that are in the PureExportSet and are “dirty”. An object is considered dirty (changed) under one or more of the following conditions:
- The object was changed by Smalltalk execution from this session.
- The object was changed by a call from this session to any GemBuilder function from within a user action.
- The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
- The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
- The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.
Calls to GciStore... (other than GciStorePaths), GciAppend..., GciReplace..., and GciCreate... do not put the modified object into the set of dirty objects (unless the call is from within a user action). The assumption is that the client does not want the dirty set to include modifications that the client has explicitly made.
You must call GciDirtyObjsInit once after GciLogin before you can use GciAlteredObjs.
Note that GciAlteredObjs removes OOPs from the ExportedDirtyObjs set and TrackedDirtyObjs sets as it enumerates.
GciAppendBytes
Append bytes to a byte object.
Arguments
Description
This function appends numBytes bytes to byte object theObject. Its effect is equivalent to GciStoreBytes(x, GciFetchSize_(x)+1, theBytes, numBytes).
GciAppendBytes raises an error if theObject is a Float or SmallFloat. Float and SmallFloat objects are of a fixed and unchangeable size.
See Also
GciAppendOops
Append OOPs to the unnamed variables of a collection.
Arguments
Description
Appends numOops OOPs to the unnamed variables of the collection theObject. If the collection is indexable, this is equivalent to:
GciStoreOops(theObject, GciFetchSize_(theObject)+1, theOops, numOops);
If the collection is an NSC, this is equivalent to:
GciAddOopsToNsc(theObject, theOops, numOops);
If the object is neither indexable nor an NSC, an error is generated.
See Also
GciBegin
Description
This function begins a new transaction. If there is a transaction currently in progress, it aborts that transaction. Calling GciBegin is equivalent to the function call GciExecuteStr("System beginTransaction", OOP_NIL).
See Also
GCI_BOOL_TO_OOP
(MACRO) Convert a C Boolean value to a GemStone Boolean object.
Description
This macro translates a C Boolean value into the equivalent GemStone Boolean object. A C value of 0 translates to the GemStone Boolean object false ( OOP_FALSE). Any other C value translates to the GemStone Boolean object true (OOP_TRUE).
Example
BoolType GCI_BOOL_TO_OOP_example(void)
{
// zero returns OOP_FALSE
OopType result = GCI_BOOL_TO_OOP( 0 );
if ( ! result == OOP_FALSE)
{ return false; }
// any non-zero argument returns OOP_TRUE
result = GCI_BOOL_TO_OOP( 99 );
if ( ! result == OOP_TRUE)
{ return false; }
return true;
}
See Also
GciByteArrayToPointer
Given a result from GciPointerToByteArray, return a C pointer.
Description
Given an argument that was the result of GciPointerToByteArray, this function returns the corresponding C pointer.
See Also
GciCallInProgress
Determine if a GemBuilder call is currently in progress.
Description
This function is intended for use within signal handlers. It can be called any time after GciInit.
GciCallInProgress returns FALSE if the process is currently executing within a user action and the user action’s code is not within a GemBuilder call. It considers the highest (most recent) call context only.
See Also
GciCheckAuth
Gather the current authorizations for an array of database objects.
Syntax
void GciCheckAuth(
const OopType oopArray[ ];
ArraySizeType arraySize;
unsigned char authCodeArray[ ] );
Arguments
Description
GciCheckAuth checks the current user’s authorization for each object in oopArray up to arraySize, returning each authorization code in the corresponding element of authCodeArray. The calling context is responsible for allocating enough space to hold the results.
Special objects, such as instances of SmallInteger, are reported as having read authorization.
Authorization values returned are those that have been committed to the database; they do not reflect changes you might have made in your local workspace. To query the local workspace, send an authorization query message to a particular object security policy using GciPerform.
If any member of oopArray is not a legal OOP, GciCheckAuth generates the error OBJ_ERR_DOES_NOT_EXIST. In that case, the contents of authCodeArray are undefined.
GCI_CHR_TO_OOP_
(MACRO) Convert a 32 bit C character value to a GemStone Character object.
Return Value
The OOP of the GemStone Character object that is equivalent to aChar. If unit is larger than 0x10FFFF, then GCI_CHR_TO_OOP_ returns OOP_ILLEGAL, while GCI_CHR_TO_OOP returns the Character with codePoint 0x10FFFF.
Description
This macro translates a 32-bit C character value into the equivalent GemStone Character object.
The variants differ according to how they handle out of range input arguments.
Example
OopType GCI_CHR_TO_OOP_example(void)
{
// return the OOP for the ASCII character 'a'
OopType theOop = GCI_CHR_TO_OOP('a');
return theOop;
}
See Also
GciClampedTrav
Traverse an array of objects, subject to clamps.
Syntax
BoolType GciClampedTrav(
const OopType * theOops,
int numOops,
GciClampedTravArgsSType * travArgs );
Arguments
|
Pointer to an instance of GciClampedTravArgsSType. See Clamped Traversal Arguments - GciClampedTravArgsSType for details on the specific fields: the OOP for a ClampSpecification, traversal depth, traversal buffer, and retrieval flags. On return, GciClampedTravArgsSType->travBuff is updated. The first element placed in the buffer is the actualBufferSize, an integer that indicates how many bytes were actually stored in the buffer by this function. The remainder of the traversal buffer consists of a series of object reports, each of which is of type GciObjRepSType. |
Return Value
Returns FALSE if the traversal is not yet completed. Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal (that is, an object report was constructed for each object, minus the special objects).
Description
GciClampedTrav initiates a traversal of the specified objects, subject to the clamps in the specified ClampSpecification. In order to guarantee that the root object of the traversal will always have an entry in the traversal buffer, the root object is not subject to the specified clamps. Refer to GciTraverseObjs for a detailed discussion of object traversal.
GemBuilder clamped traversal functions are used by the GemBuilder for Smalltalk implementation of object replication and are intended for similar sophisticated client applications.
See Also
GciClassMethodForClass
Compile a class method for a class.
Syntax
OopType GciClassMethodForClass(
OopType source,
OopType aClass,
OopType category,
OopType symbolList );
Arguments
Return Value
Returns OOP_NIL, unless there were compiler warnings (such as variables declared but not used, etc.), in which case the return will be the OOP of a string containing the warning messages.
Description
This function compiles a class method for the given class. You may not compile any method whose selector begins with an underscore (_) character. Such selectors are reserved for use by the GemStone development team as private methods.
In addition, the Smalltalk virtual machine optimizes a small number of selectors. You may not compile any methods with any of those selectors. See the Programming Guide for a list of the optimized selectors.
To remove a class method, use GciExecuteStr to execute Smalltalk code in GemStone, or GciClassRemoveAllMethods to remove all methods.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
void GciClassMethodForClass_example(void)
{
// Assumes the setup code has been executed.
OopType theClass = GciResolveSymbol("Customer", OOP_NIL);
OopType oCateg = GciNewString("instance creation");
OopType oMethodSrc = GciNewString(
"newNamed: aName address: anAddress.
| n | n := self new. n name: aName. n address: anAddress. ^ n");
GciClassMethodForClass(oMethodSrc, theClass, oCateg, OOP_NIL);
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
}
}
See Also
GciClassNamedSize
Find the number of named instance variables in a class.
Arguments
|
The OOP of the class from which to obtain information about instance variables. For reserved OOPs for Smalltalk kernel classes, see $GEMSTONE/include/gcioop.ht. |
Return Value
Returns the number of named instance variables in the class, or zero if an error occurs.
Description
This function returns the number of named instance variables for the specified class, including those inherited from superclasses.
Example
int namedSizeExample(void)
{
// find the class named Employee in the current symbolList
OopType empClass = GciResolveSymbol(“Employee”, OOP_NIL);
if (empClass == OOP_NIL) {
return -1; // class not found or other error.
}
int numIvs = GciClassNamedSize(empClass);
GciErrSType errInfo;
if (GciErr(&errInfo)) {
return -1; // error occurred
}
// return the number of named instance variables which will
// be >= 0
return numIvs;
}
See Also
GciClassRemoveAllMethods
Remove all methods from the method dictionary of a class.
Description
This function removes all methods from the method dictionary of the specified class.
To remove an individual method, use GciExecuteStr to execute Smalltalk code in GemStone,
GciClearStack
Clear the Smalltalk call stack.
Arguments
|
The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr). |
Description
Whenever a session executes a Smalltalk expression or sequence of expressions, the virtual machine creates and maintains a call stack that provides information about its state of execution. The call stack includes an ordered list of activation records related to the methods and blocks that are currently being executed.
If a soft break or an unexpected error occurs, the virtual machine suspends execution, creates a GsProcess object, and raises an error. The GsProcess object represents both the call stack when execution was suspended and any information that the virtual machine needs to resume execution. If there was no fatal error, your program can call GciContinue to resume execution. Call GciClearStack instead if there was a fatal error, or if you do not want your program to resume the suspended execution.
Example
The following example shows how an application can handle an error and either continue or terminate Smalltalk execution.
void clearStackExample(void)
{
OopType result = GciExecuteStr(
"| a | a := 10 + 10. nil halt . ^ a + 100",
OOP_NIL/*use default symbolList for execution*/);
// halt method is expected to generate error number RT_ERR_GENERIC_ERROR
GciErrSType errInfo;
if (! GciErr(&errInfo)) {
printf("expected an error but none found\n");
return;
}
if (errInfo.number == ERR_Halt) {
// now continue the execution to finish the computation
result = GciContinue(errInfo.context);
} else {
// FMT_OID format string is defined in gci.ht
printf("unexpected error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
// terminate the execution
GciClearStack(errInfo.context);
return;
}
int val = GciOopToI32(result);
if (GciErr(&errInfo)) {
printf("unexpected error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
} else {
if (val != 120) {
printf("Wrong answer = %d\n", val);
} else {
printf("result = %d\n", val);
}
}
}
See Also
GciCommit
Write the current transaction to the database.
Return Value
Returns TRUE if the transaction committed successfully. Returns FALSE if the transaction fails to commit due to a concurrency conflict or in case of error.
Description
The GciCommit function attempts to commit the current transaction to the GemStone database.
GciCommit ignores any commit pending action that may be defined in the current GemStone session state.
Example
void GciCommit_example(void)
{
// Call GciCommit and see if there was an error
if ( ! GciCommit()) {
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf(“commit failed with error %d , %s \n”,
errInfo.number, errInfo.message );
} else {
printf(“commit failed due to transaction conflicts\n”);
}
}
}
See Also
GciCompileMethod
Syntax
OopType GciCompileMethod(
OopType source,
OopType aClass,
OopType category,
OopType symbolList,
OopType overrideSelector,
int compileFlags,
ushort environmentId );
Arguments
Return Value
Returns OOP_NIL, unless there were compiler warnings (such as variables declared but not used, etc.), in which case the return will be the OOP of a string containing the warning messages.
Description
This function is used for compiling a method. Replaces both GciInstMethodForClass and GciClassMethodForClass, and adds the environmentId argument.
This function compiles a method for the given class. You may not compile any method whose selector begins with an underscore (_) character. Such selectors are reserved for use by the GemStone development team as private methods.
In addition, the Smalltalk virtual machine optimizes a small number of selectors. You may not compile any methods with any of those selectors. See the Programming Guide for a list of the optimized selectors.
GciCompress
Compress the supplied data, which can be uncompressed with GciUncompress.
Arguments
|
Pointer to the buffer that will hold the resulting compressed data. |
|
|
Length, in bytes, of the buffer intended to hold the compressed data. |
|
Return Value
GciCompress returns Z_OK (equal to 0) if the compression succeeded, or various error values if it failed; see the documentation for the compress function in the GNU zlib library at http://www.gzip.org.
Description
GciCompress passes the supplied inputs unchanged to the compress function in the GNU zlib library Version 1.2.3, and returns the result exactly as the GNU compress function returns it.
Example
#include <limits.h>
OopType compressByteArray(OopType byteArray)
{
// given an input ByteArray , return a new ByteArray with
// the contents of the input compressed .
if (!GciIsKindOfClass(byteArray, OOP_CLASS_BYTE_ARRAY) )
return OOP_NIL; /* error: input arg is not a ByteArray */
int64 inputSize = GciFetchSize_(byteArray);
if (inputSize > INT_MAX) {
return OOP_NIL; // GciCompress supports max 2G bytes input
}
int64 outputSize = inputSize;
ByteType *inputBuffer = (ByteType*)malloc( inputSize);
if (inputBuffer == NULL) {
return OOP_NIL; // malloc failure
}
ByteType *outputBuffer = (ByteType*)malloc( outputSize);
if (outputBuffer == NULL) {
free(inputBuffer);
return OOP_NIL; // malloc failure
}
OopType resultOop = OOP_NIL;
int64 numRet = GciFetchBytes_(byteArray, 1/* start at first element */,
inputBuffer, inputSize /* max bytes to fetch */ );
if (numRet == inputSize) {
uint compressedSize;
int status = GciCompress( (char *)outputBuffer,
&compressedSize,
(char *) inputBuffer, inputSize);
if (status == 0) {
// compress ok
resultOop = GciNewByteObj(OOP_CLASS_BYTE_ARRAY,
outputBuffer, (int64)compressedSize );
} else {
// compress failed
}
} else {
// error during FetchBytes
}
free(inputBuffer);
free(outputBuffer);
return resultOop;
}
See Also
GciContinue
Continue code execution in GemStone after an error.
Arguments
|
The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr). |
Return Value
Returns the OOP of the result of the Smalltalk code that was executed. Returns OOP_NIL in case of error.
Description
The GciContinue function attempts to continue Smalltalk execution sometime after it was suspended. It is most useful for proceeding after GemStone encounters a pause message, a soft break (GciSoftBreak), or an application-defined error, since continuation is always possible after these events. Because GciContinue calls the virtual machine, the application user can also issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.
It may also be possible to continue Smalltalk execution if the virtual machine detects a nonfatal error during a GciExecute... or GciPerform call. You may then want to use structural access functions to investigate (or modify) the state of the database before you call GciContinue.
Example
See the example for GciClearStack.
GciContinueWith
Continue code execution in GemStone after an error.
Syntax
OopType GciContinueWith (
OopType gsProcess,
OopType replaceTopOfStack,
int flags,
GciErrSType * continueWithError );
Arguments
|
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. |
Return Value
Returns the OOP of the result of the Smalltalk code that was executed. In case of error, this function returns OOP_NIL.
GciCreateByteObj
Create a new byte-format object.
Syntax
OopType GciCreateByteObj(
OopType aClass,
OopType objId,
const ByteType * values,
int64 numValues,
int clusterId,
BoolType makePermanent );
Arguments
Return Value
GciCreateByteObj returns the OOP of the object it creates. The return value is the same as objId unless that value is OOP_ILLEGAL, in which case GciCreateByteObj assigns and returns a new OOP itself.
Description
Creates a new object using an object identifier (OOP) objId previously obtained from GciGetFreeOop or GciGetFreeOops. For more about the semantics of such object identifiers, see GciGetFreeOop.
The object is created in temporary object space, and the garbage collector makes it permanent if the object is referenced, or becomes referenced, by another permanent object.
Values are stored into the object starting at the first named instance variable (if any) and continuing to the indexable (or NSC) instance variables if oclass is indexable or NSC. The caller must initialize any unused elements of *values to OOP_NIL.
If oclass is an indexable or NSC class, then numValues may be as large or as small as desired. If oclass is neither indexable nor NSC, numValues must not exceed the number of named instance variables in the class. If numValues is less than number of named instance variables, then the size of the newly-created object is the number of named instance variables and any instance variables beyond numValues are initialized to OOP_NIL.
For certain classes of byte format, namely DateTime, Float, and LargeInteger, additional size restrictions apply.
For an indexable object, if numValues is greater than zero and values is NULL, then the object is created of size numValues, and is initialized to logical size numValues. (This is equivalent to new: aSize for classes Array or String.)
If GciCreateByteObj is being used to create an instance of OOP_CLASS_FLOAT or OOP_CLASS_SMALL_FLOAT, then the correct number of value bytes must be supplied at the time of creation.
If you are trying to create a Symbol or DoubleByteSymbol, objId must be OOP_ILLEGAL.
See Also
GciCreateOopObj
Create a new pointer-format object.
Syntax
OopType GciCreateOopObj(
OopType aClass,
OopType objId,
const OopType * values,
int numValues,
int clusterId,
BoolType makePermanent );
Arguments
Return Value
GciCreateOopObj returns the OOP of the object it creates. The return value is the same as objId unless that value is OOP_ILLEGAL, in which case GciCreateOopObj assigns and returns a new OOP itself.
Description
Creates a new object using an object identifier (objId) previously obtained from GciGetFreeOop or GciGetFreeOops. For more about the semantics of such object identifiers, see GciGetFreeOop.
The object is created in temporary object space, and the garbage collector makes it permanent if the object is referenced, or becomes referenced, by another permanent object.
Values are stored into the object starting at the first named instance variable (if any) and continuing to the indexable (or NSC) instance variables if oclass is indexable or NSC. Values may be forward references to objects whose identifier has been allocated with GciGetFreeOop, but for which the object has not yet been created with GciCreate.... The caller must initialize any unused elements of *values to OOP_NIL.
Because it is illegal to create a forward reference to a Symbol, any GciCreate... call that creates a Symbol will fail if the client’s objId of the created object was already used as a forward reference.
If oclass is an indexable or NSC class, then numValues may be as large or as small as desired. If oclass is neither indexable nor NSC, numValues must not exceed the number of named instance variables in the class. If numValues is less than number of named instance variables, then the size of the newly-created object is the number of named instance variables and any instance variables beyond numValues are initialized to OOP_NIL.
For an indexable object, if numValues is greater than zero and values is NULL, then the object is created of size numValues, and is initialized to logical size numValues. (This is equivalent to new: aSize for classes Array or String.)
See Also
GciCTimeToDateTime
Convert a C date-time representation to the equivalent GemStone representation.
Arguments
Description
Converts a time_t value to GciDateTimeSType. On systems where time_t is a signed value, GciCTimeToDateTime generates an error if arg is negative.
See Also
GciDateTimeToCTime
Convert a GemStone date-time representation to the equivalent C representation.
See Also
GciDbgEstablish
Specify the debugging function for GemBuilder to execute before most calls to GemBuilder functions.
Arguments
Return Value
Returns a pointer to the newDebugFunc specified in the previous GciDbgEstablish call (if any).
Description
This function establishes the name of a C function (most likely a debugging routine) to be called before your program calls any GemBuilder function or macro (except those named above). Before each GemBuilder call, a single argument, a null-terminated string that names the GemBuilder function about to be executed, is passed to the specified newDebugFunc.
The newDebugFunc function is passed a single null-terminated string argument, (of type const char []), the name of the GemBuilder function about to be called.
To disable previous debugging routines, call GciDbgEstablish with an argument of NULL.
Example
void traceGciFunct(const char* gciFname)
{
printf("trace gci call %s \n", gciFname);
}
void debugEstablishExample(void)
{
GciDbgEstablish(traceGciFunct); // enable tracing
GciFetchSize_(OOP_CLASS_STRING); // this call will be traced
GciDbgEstablish(NULL); // shut off tracing
}
See Also
GciDbgEstablishToFile
Write trace information for most GemBuilder functions to a file.
Description
This function causes trace information for most GemBuilder functions to be written to a file. If the file already exists, it is opened in append mode. If fileName is NULL and tracing to a file is not currently active, trace information will be written to stdout.
Calling GciDbgEstablishToFile supersedes the effect of any previous calls to GciDbgEstablish or GciDbgEstablishToFile.
To terminate tracing to an active file, call GciDbgEstablishToFile with an argument of NULL; alternatively, a call GciShutdown also teminates tracing.
For details about the trace information generated, see GciDbgEstablish.
See Also
GciDbgLogString
Pass a message to a trace function.
Description
If either GciDbgEstablish or GciDbgEstablishToFile has been called to activate tracing of GemBuilder calls, this function passes the argument to the trace function.
See Also
GciDeclareAction
An alternative way to associate a C function with a Smalltalk user action.
Syntax
void GciDeclareAction(
const char* name,
void* func,
int nunArgs,
uint flags,
BoolType errorIfDuplicate );
Arguments
Description
This function associates a user action name (declared in Smalltalk) with a user-written C function. GciDeclareAction allows you to declare a user action by passing each field of the user action structure to the function as a separate argument. Because the user action structure is encapsulated within the function itself, there’s no need to explicitly allocate and free memory, as is required with GciInstallUserAction (which uses the data structure defined by GciUserActionSType).
GciDecodeOopArray
Decode an OOP array that was previously run-length encoded.
Syntax
int GciDecodeOopArray(
OopType * encodedOopArray,
const int numEncodedOops,
OopType * decodedOopArrray,
const int decodedOopsSize);
Description
This function decodes the OOPs in encodedOopArray that were run-length encoded using GciEncodeOopArray and places the result in decodedOopArray.
The decodedOopArraySize must be large enough to hold all decoded OOPs. If it is not, no decode is performed and *decodedOopArraySize is set to -1.
GciDecSharedCounter
Decrement the value of a shared counter.
Arguments
Return Value
Returns a C Boolean value indicating if the shared counter was successfully decremented by the given amount. Returns TRUE if successful, FALSE if an error occurred.
Description
This function decrements the value of a particular shared counter by a specified amount. The shared counter is specified by index. The value of this shared counter cannot be decremented to a value lower than floor.
This function is not supported for remote GCI interfaces, and will always return FALSE.
GciFetchNumSharedCounters
GciIncSharedCounter
GciSetSharedCounter
GciReadSharedCounter
GciReadSharedCounterNoLock
GciFetchSharedCounterValuesNoLock
GciDirtyExportedObjs
Find all objects in the ExportedDirtyObjs set.
Arguments
|
The maximum number of objects that can be put into theOops buffer. On return, the number of dirty exported objects found. |
Return Value
This function returns a C Boolean value indicating whether or not the complete set of dirty objects has been returned in theOops in one or more calls. TRUE indicates that the complete set has been returned, and FALSE indicates that it has not.
Description
This function returns a list of all objects that are in the ExportedDirtyObjs set, which includes all objects in the PureExportSet that have been made “dirty” since the ExportedDirtyObjs set was last initialized or retrieved using any of the following:
GciDirtyAlteredObjs
GciDirtyExportedObjs
GciDirtyObjsInit
GciDirtySaveObjs
GciTrackedObjsFetchAllDirty
Object are added to the PureExportSet using GciSaveObjs or by other functions that invoke GciSaveObjs.
An object is considered dirty (changed) under one or more of the following conditions:
- The object was changed by Smalltalk execution from this session.
- The object was changed by a call from this session to any GemBuilder function from within a user action.
- The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
- The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
- The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.
Calls to GciStore... (other than GciStorePaths), GciAppend..., GciReplace..., and GciCreate... do not put the modified object into the set of dirty objects (unless the call is from within a user action). The assumption is that the client does not want the dirty set to include modifications that the client has explicitly made.
The function GciDirtyObjsInit must be executed once after GciLogin before this function can be called, because it depends upon GemStone’s set of dirty objects.
The user is expected to call this function repeatedly while it returns FALSE, until it finally returns TRUE. When this function returns TRUE, it first clears the set of dirty objects.
Note that GciDirtyExportedObjs removes OOPs from the ExportedDirtyObjs set as they are enumerated.
GciDirtyObjsInit
Begin tracking which objects in the session workspace change.
Description
GemStone can track which objects in a session change, but doing so has a measurable cost. By default, GemStone does not do it. The GciDirtyObjsInit function permits an application to request GemStone to maintain that set of dirty objects, the ExportedDirtyObjects, when it is needed. Once initialized, GemStone tracks dirty objects until GciLogout is executed.
GciDirtyObjsInit must be called once after GciLogin before GciDirtyExportedObjs, GciDirtySaveObjs, or GciTrackedObjsFetchAllDirty in order for those functions to operate properly, because they depend upon GemStone’s set of dirty objects.
An object is considered dirty (changed) under one or more of the following conditions:
- The object was changed by Smalltalk execution from this session.
- The object was changed by a call from this session to any GemBuilder function from within a user action.
- The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
- The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
- The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.
GciDirtySaveObjs
Find all exported or tracked objects that have changed and are therefore in the ExportedDirtyObjs or TrackedDirtyObjs sets.
Arguments
|
The maximum number of objects that can be put into theOops buffer. On return, the number of dirty cached objects found |
Return Value
This function returns a C Boolean value indicating whether or not the complete set of dirty objects has been returned in theOops in one or more calls. TRUE indicates that the complete set has been returned, and FALSE indicates that it has not.
Description
This function finds all objects that are in the ExportedDirtyObjs or TrackedDirtyObjs sets. The ExportedDirtyObjs set includes all objects in PureExportSet that have been made “dirty” since the ExportedDirtyObjs set was last reset, and the TrackedDirtyObjs set includes all objects in the GciTrackedObjs set that have been made “dirty” since the TrackedDirtyObjs set was last reset.
The ExportedDirtyObjs set is initialized by GciDirtyObjsInit.
The ExportedDirtyObjs set is cleared by calls to GciDirtyAlteredObjs, GciDirtyExportedObjs, GciDirtySaveObjs (this function), or GciTrackedObjsFetchAllDirty.
The TrackedDirtyObjs set is initialized by GciTrackedObjsInit .
The TrackedDirtyObjs set is cleared by calls to GciDirtyAlteredObjs, GciDirtySaveObjs (this function), GciDirtyTrackedObjs, or GciTrackedObjsFetchAllDirty.
An object is considered dirty (changed) under one or more of the following conditions:
- The object was changed by Smalltalk execution from this session.
- The object was changed by a call from this session to any GemBuilder function from within a user action.
- The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
- The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
- The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.
Calls to GciStore... (other than GciStorePaths), GciAppend..., GciReplace..., and GciCreate... do not put the modified object into the set of dirty objects (unless the call is from within a user action). The assumption is that the client does not want the dirty set to include modifications that the client has explicitly made.
GciDirtyObjsInit must be called once after GciLogin before GciDirtySaveObjs can be executed, because it depends upon GemStone’s set of dirty objects.
The user is expected to call GciDirtySaveObjs repeatedly while it returns FALSE, until it finally returns TRUE. When GciDirtySaveObjs returns TRUE, it first clears the set of dirty objects.
For details about the PureExportSet, see GciSaveObjs. For details about the GciTrackedObjs set, see GciSaveAndTrackObjs.
Note that GciDirtySaveObjs removes OOPs from the ExportedDirtyObjs and TrackedDirtyObjs sets.
GciDirtyTrackedObjs
Find all tracked objects that have changed and are therefore in the TrackedDirtyObjs set.
Arguments
|
The maximum number of objects that can be put into theOops buffer. On return, the number of dirty tracked objects found. |
Return Value
This function returns a C Boolean value indicating whether or not the complete set of dirty tracked objects has been returned in theOops in one or more calls. TRUE indicates that the complete set has been returned, and FALSE indicates that it has not.
Description
This function returns a list of all objects that are in the TrackedDirtyObjs set, which includes all objects that are in the GciTrackedObjs set and have been made “dirty” since the GciTrackedObjs set was initialized or cleared. Functions that initialize or remove objects from the TrackedDirtyObjs set are GciDirtyAlteredObjs, GciDirtySaveObjs, GciDirtyTrackedObjs (this function), GciTrackedObjsFetchAllDirty and GciTrackedObjsInit.
An object is considered dirty (changed) under one or more of the following conditions:
- The object was changed by Smalltalk execution from this session.
- The object was changed by a call from this session to any GemBuilder function from within a user action.
- The object was changed by a call from this session to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
- The object was read by this session, and after this session did a commit, begin, or abort transaction, the session now has visibility to changes to the object committed by another session.
- The object is persistent, and this session aborted its changes to the object, thus rolling back the Smalltalk in-memory state to the previously committed state.
Calls to GciStore... (other than GciStorePaths), GciAppend..., GciReplace..., and GciCreate... do not put the modified object into the set of dirty objects (unless the call is from within a user action). The assumption is that the client does not want the dirty set to include modifications that the client has explicitly made.
This function may only be called after GciTrackedObjsInit has been executed, because it depends upon GemStone’s set of tracked 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 GciDirtyTrackedObjs removes OOPs from the TrackedDirtyObjs set.
Gci_doubleToSmallDouble
Convert a C double to a SmallDouble object.
Return Value
Returns the OOP of the GemStone SmallDouble object that corresponds to the C value. If the C value is not representable as a GemStone SmallDouble, return OOP_ILLEGAL.
See Also
GciEnableFullCompression
Enable full compression between the client and the RPC version of GemBuilder.
GciEnableSignaledErrors
Establish or remove GemBuilder visibility to signaled errors from GemStone.
Description
GemStone permits selective response to signal errors: RT_ERR_SIGNAL_ABORT, RT_ERR_SIGNAL_COMMIT, and RT_ERR_SIGNAL_GEMSTONE_SESSION. The default condition is to leave them all invisible. GemStone responds to each single kind of signal error only after an associated method of class System has been executed: enableSignaledAbortError, enableSignaledObjectsError, and enableSignaledGemStoneSessionError respectively.
After GciInit executes successfully, the GemBuilder default condition also leaves all signal errors invisible. The GciEnableSignaledErrors function permits GemBuilder to respond automatically to signal errors. However, GemStone must respond to each kind of error in order for GemBuilder to respond to it. Thus, if an application calls GciEnableSignaledErrors with newState equal to TRUE, then GemBuilder responds automatically to exactly the same kinds of signal errors as GemStone. If GemStone has not executed any of the appropriate System methods, then this call has no effect until it does.
When enabled, GemBuilder checks for signal errors at the start of each function that accesses the database. It treats any that it finds just like any other errors, through GciErr or the GciLongJmp mechanism, as appropriate.
Automatic checking for signalled errors incurs no extra runtime cost. The check is optimized into the check for a valid session. However, instead of checking automatically, these errors can be polled by calling the GciPollForSignal function.
GciEnableSignaledErrors may be called before calling GciLogin.
See Also
GciEncodeOopArray
Encode an array of OOPs, using run-length encoding.
Syntax
int GciEncodeOopArray(
OopType * oopArray,
const int numOops,
OopType * encodedOopArray,
BoolType needsSorting );
Arguments
|
If oopArray is known to be in ascending order, set this to FALSE; otherwise set it to TRUE. |
Return Value
Returns the number of elements in the encoded array. Returns -1 indicating an error if the input array was found to be out of sequence and needsSorting was set to FALSE.
GciEncrypt
Arguments
Return Value
Returns a pointer to the first character of the encrypted password in outBuff[], or NULL if the encrypted password is larger than outBuffSize.
Description
This function encrypts a host or GemStone password for use in GciSetNetEx or GciLogin with password encyrption enabled.
Example
BoolType login_encrypt_example(void)
{
// assume the netldi been started with -a -g so that host
// userId and host password are not required.
const char* stoneName = "gs64stone";
const char* gemService = "gemnetobject";
const char* gsUserName = "DataCurator";
// GciInit required before first login
if (!GciInit()) {
printf("GciInit failed\n");
return FALSE;
}
char outBuf[1024];
char * gsPassword = GciEncrypt("swordfish", outBuf,
sizeof(outBuf));
if ( gsPassword == NULL ) {
printf("password encryption failed\n");
return FALSE;
}
GciSetNet(stoneName, "", "", gemService);
BoolType success = GciLoginEx(gsUserName, gsPassword,
GCI_LOGIN_PW_ENCRYPTED | GCI_LOGIN_QUIET, 0);
if (! success) {
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("login encrypted password failed; error %d, %s\n",
errInfo.number, errInfo.message);
}
}
return success;
}
See Also
GciErr
Prepare a report describing the most recent GemBuilder error.
Return Value
TRUE indicates that an error has occurred. The errorReport parameter has been modified to contain the latest error information, and the internal error buffer in GemBuilder has been cleared. You can only call GciErr once for a given error. If GciErr is called a second time, the function returns FALSE.
If the result is TRUE, all objects referenced from errorReport have been added to the PureExportSet, unless the error occurred during a GciStoreTravDoTravRefs_, in which case all objects referenced from errorReport have been added to the ReferencedSet rather than the PureExportSet.
FALSE indicates no error occurred, and the contents of errorReport are unchanged.
Description
Your application program can call GciErr to determine whether or not the previous GemBuilder function call resulted in an error. If an error has occurred, this function provides information about the error and about the state of the GemStone system. In the case of a fatal error, your connection to GemStone is lost, and the current session ID (from GciGetSessionId) is reset to GCI_INVALID_SESSION_ID.
The GciErr function is especially useful when error traps are disabled or are not present. See GciPopErrJump for information about using general-purpose error traps in GemBuilder. The section Error Report Structure - GciErrSType describes the C structure for error reports.
GciExecute
Execute a Smalltalk expression contained in a GemStone String or Utf8 object.
Arguments
Return Value
Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.
Description
This function sends an expression (or sequence of expressions) to GemStone for execution. This is roughly equivalent to executing the body of a nameless procedure (method).
In most cases, you may find it more efficient to use GciExecuteStr. That function takes a C string as its argument, thus reducing the number of network round-trips required to execute the code. With GciExecute, you must first convert the source to a String or Utf8 object (see the following example.) If the source is already one of these kinds of object, however, GciExecute will be more efficient.
Because GciExecute calls the virtual machine, the user can issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.
Example
BoolType execute_example(void)
{
OopType oString = GciNewString(" ^ 3 + 4 ");
OopType result = GciExecute(oString, OOP_NIL);
if (result == OOP_NIL) {
printf("error from execution\n");
return false;
}
BoolType conversionErr = FALSE;
int val = GciOopToI32_(result, &conversionErr);
if (conversionErr) {
printf("Error converting result to C int\n");
} else {
printf("result = %d\n", val);
}
return ! conversionErr;
}
GciExecuteFromContext
Execute a Smalltalk expression contained in a String or Utf8 object as if it were a message sent to another object.
Arguments
Return Value
Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.
Description
This function sends an expression (or sequence of expressions) to GemStone for execution. The source is executed as though contextObject were the receiver. That is, the pseudo-variable self will have the value contextObject during the execution. Messages in the source are executed as defined for contextObject.
For example, if contextObject is an instance of Association, the source can reference the pseudo-variables key and value (referring to the instance variables of the Association contextObject). If any pool dictionaries were available to Association, the source could reference them too.
In most cases, you may find it more efficient to use GciExecuteStrFromContext. That function takes a C string as its argument, thus reducing the number of network round-trips required to execute the code. With GciExecuteFromContext, you must first convert the source to a String or Utf8 object. If the source is already one of these kinds of object, however, GciExecuteFromContext will be more efficient.
Because GciExecuteFromContext calls the virtual machine, the user can issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.
GciExecuteStr
Execute a Smalltalk expression contained in a C string.
Arguments
Return Value
Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.
Description
This function sends an expression (or sequence of expressions) to GemStone for execution.
If the source is already a String object, you may find it more efficient to use GciExecute. That function takes the OOP of a String as its argument.
Because GciExecuteStr calls the virtual machine, the user can issue a soft break while this function is executing. For more information, see .Interrupting GemStone Execution.
Example
void executeStrExample(void)
{
// get the symbolList for UserProfile named 'romeo'
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);
}
}
GciExecuteStrFetchBytes
Execute a Smalltalk expression contained in a C string, returning byte-format results.
Syntax
int64 GciExecuteStrFetchBytes(
const char * source,
int64 sourceSize,
OopType sourceClass,
OopType contextObject,
OopType symbolList,
ByteType * result,
int64 maxResultSize );
Input
GciExecuteStrFromContext
Execute a Smalltalk expression contained in a C string as if it were a message sent to an object.
Syntax
OopType GciExecuteStrFromContext(
const char source[ ],
OopType contextObject,
OopType symbolList );
Arguments
Return Value
Returns the OOP of the execution result. In case of error, this function returns OOP_NIL.
Description
This function sends an expression (or sequence of expressions) to GemStone for execution. The source is executed as though contextObject were the receiver. That is, the pseudo-variable self will have the value contextObject during the execution. Messages in the source are executed as defined for contextObject.
For example, if contextObject is an instance of Association, the source can reference the pseudo-variables key and value (referring to the instance variables of the Association contextObject). If any pool dictionaries were available to Association, the source could reference them too.
Because GciExecuteStrFromContext calls the virtual machine, the user can issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.
Example
void executeFromContextExample(void)
{
// get the Assocation with key UserProfileSet in dictionary Globals
OopType oAssoc = GciExecuteStr("Globals associationAt: #UserProfileSet",
OOP_NIL);
OopType oResult = GciExecuteStrFromContext(" ^ value ", oAssoc, OOP_NIL);
if (oResult != OOP_CLASS_USERPROFILE_SET) {
printf("unexpected result"FMT_OID" \n", oResult);
}
}
GciExecuteStrTrav
First execute a Smalltalk expression contained in a C string as if it were a message sent to an object, then traverse the result of the execution.
Syntax
BoolType GciExecuteStrTrav(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList,
GciClampedTravArgsSType * travArgs );
Arguments
|
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. |
Return Value
Returns FALSE if the traversal is not yet completed. You can then call GciMoreTraversal to proceed. Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal.
GciFetchByte
Fetch one byte from an indexed byte object.
Arguments
|
The index into theObject of the element to be fetched. The index of the first element is 1. |
Return Value
Returns the byte value at the specified index. In case of error, this function returns zero.
Description
This function fetches a single element from a byte object at the specified index, using structural access.
GciFetchBytes_
Fetch multiple bytes from an indexed byte object.
Syntax
int64 GciFetchBytes_(
OopType theObject,
int64 startIndex,
ByteType theBytes[ ],
int64 numBytes );
Arguments
Return Value
Returns the number of bytes fetched. (This may be less than numBytes, depending upon the size of theObject.) In case of error, this function returns zero.
Description
This function fetches multiple elements from a byte object starting at the specified index, using structural access. A common application of GciFetchBytes_ would be to fetch a text string.
GciFetchBytes_ permits theObject to be a byte object with multiple bytes per character or digit, such as DoubleByteString, Float and LargeInteger. In this case, GciFetchBytes_ provides automatic byte swizzling to client native byte order. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values. For MultiByteStrings, startIndex must be aligned on character boundaries and numbytes must be a multiple of the number of bytes per character; for numeric objects startindex must be one and numBytes the size of the numeric class.
Example
This example will print a GemStone String of arbitrarily large size, by repeatedly fetching fixed size buffers.
BoolType fetchBytes_example(OopType anObj)
{
int BUF_SIZE = 5000;
char buff[BUF_SIZE];
BoolType done = FALSE;
int idx = 1;
GciErrSType err;
while (! done) {
int64 numRet = GciFetchBytes_(anObj, idx, (ByteType*)buff, BUF_SIZE - 1);
if (numRet == 0) {
done = TRUE; // hit end of object or error
if (GciErr(&err)) {
printf("error %d, %s\n", err.number, err.message);
return false;
}
} else {
buff[numRet] = '\0';
printf("%s\n", buff);
idx += numRet;
}
}
return true;
}
GciFetchChars_
Fetch multiple ASCII characters from an indexed byte object.
Description
Equivalent to GciFetchBytes_, except that it is assumed that theObject contains ASCII text. The bytes fetched are stored in memory starting at cString. At most maxSize - 1 bytes will be fetched from the object, and a \0 character will be stored in memory following the bytes fetched. The function returns the number of characters fetched, excluding the null terminator character, which is equivalent to strlen(cString) if the object does not contain any null characters. If an error occurs, the function result is 0, and the contents of cString are undefined.
See Also
GciFetchClass
Return Value
Returns the OOP of the object’s class. In case of error, this function returns OOP_NIL.
The GemBuilder include file $GEMSTONE/include/gcioop.ht defines a C constant for each of the Smalltalk kernel classes.
Description
The GciFetchClass function obtains the class of an object from GemStone. The GemBuilder session must be valid when GciFetchClass is called, unless theObject is an instance of one of the following classes: Boolean, Character, JisCharacter, SmallInteger, SmallDouble, or UndefinedObject.
Example
#include <stdlib.h>
void fetchClassExample(void)
{
// random double to Oop conversion producing a Float or SmallDouble
double rand = drand48() * 1.0e38 ;
OopType oFltObj = GciFltToOop(rand);
OopType oClass = GciFetchClass(oFltObj);
const char* kind;
if (oClass == OOP_CLASS_SMALL_DOUBLE) {
kind = "SmallDouble";
} else if (oClass == OOP_CLASS_FLOAT) {
kind = "Float";
} else {
kind = "Unexpected";
}
printf("result is a %s, class oop = "FMT_OID"\n", kind, oClass);
}
GciFetchDateTime
Convert the contents of a DateTime object and place the results in a C structure.
Arguments
GciFetchDynamicIv
Fetch the OOP of one of an object’s dynamic instance variables.
Arguments
Return Value
Returns the OOP of the specified dynamic instance variable. If no such dynamic instance variable exists in the object, this function returns OOP_NIL.
Description
This function fetches the contents of an object’s dynamic instance variable, as specified by aSymbol.
See Also
GciFetchDynamicIvs
Fetches the OOPs of one or more of an object’s dynamic instance variables.
Return Value
Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.)
Description
The number of dynamic instance variable pairs returned is (function result / 2). To obtain all dynamic instance variables in one call, use a buffer.
See Also
GciFetchNamedOop
Fetch the OOP of one of an object’s named instance variables.
Arguments
|
The index into theObject’s named instance variables of the element to be fetched. The index of the first named instance variable is 1. |
Return Value
Returns the OOP of the specified named instance variable. In case of error, this function returns OOP_NIL.
Description
This function fetches the contents of an object’s named instance variable at the specified index, using structural access.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
BoolType fetchNamedOop_example(OopType anAccount)
{
// fetch anAccount's salesRep, hard coding offset
int indexOfSalesRep = 3;
OopType oName1 = GciFetchNamedOop(anAccount, indexOfSalesRep);
// fetch anAccount's salesRep without hardcoding offset
int ivOffset = GciIvNameToIdx(GciFetchClass(anAccount), "salesRep");
OopType oName2 = GciFetchNamedOop(anAccount, ivOffset);
return oName1 = oName2;
}
GciFetchNamedOops
Fetch the OOPs of one or more of an object’s named instance variables.
Arguments
Return Value
Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.) In case of error, this function returns zero.
Description
This function uses structural access to fetch multiple values from an object’s named instance variables, starting at the specified index.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
This example fetches an Account’s id, customer, and salesRep.
BoolType fetchNamedOops_example(OopType anAccount)
{
GciErrSType err;
// fetch the number of named instvars
int namedSize = GciFetchNamedSize(anAccount);
if (namedSize == 0) { return false; }
OopType *oBuffer = (OopType*) malloc( sizeof(OopType) * namedSize );
if (oBuffer == NULL) { return false; }
int numRet = GciFetchNamedOops(anAccount, 1, oBuffer, namedSize);
if (GciErr(&err)) {
printf("Error %d, %s\n", err.number, err.message);
return false;
}
free(oBuffer);
return (numRet == namedSize) ;
}
GciFetchNamedSize
Fetch the number of named instance variables in an object.
Return Value
Returns the number of named instance variables in theObject. In case of error, this function returns zero.
Description
This function returns the number of named instance variables in a GemStone object. See the example for GciFetchNamedOops.
GciFetchNumEncodedOops
GciFetchNumSharedCounters
Obtain the number of shared counters available on the shared page cache used by this session.
Return Value
Returns the number of shared counters available on the shared page cache used by this session, or -1 if the session is not logged in.
GciFetchObjectInfo
Fetch information and values from an object.
Arguments
|
Pointer to an instance of GciFetchObjInfoArgsSType with the following argument fields:
GciObjInfoSType * info
ByteType * buffer
int64 startIndex
int64 bufSize
int64 numReturned
int retrievalFlags |
Description
GciFetchObjectInfo fetches information and values from an object starting at the specified index using structural access. If either info or buffer is NULL, then that part of the result is not filled in. If numReturned is NULL, then buffer will not be filled in.
The offset in startIndex does not distinguish between named and unnamed instance variables. Indices are based at the beginning of the object’s array of instance variables. In that array, any existing named instance variables are followed by any existing unnamed instance variables
If theObject is a byte object with multiple bytes per character or digit, such as DoubleByteString, LargeInteger, or Float, the results in args->buffer will be automatically byte swizzled to client native byte order. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.
For MultiByteStrings, args->startIndex must be aligned on a character boundary and args->bufSize must be a multiple of the number of bytes per character in the string. For numeric objects, args->startIndex must be one and args->bufSize must be the size of the numeric class.
See Also
GciFetchObjImpl
Fetch the implementation of an object.
Return Value
Returns an integer representing the implementation type of theObject (0=pointer, 1=byte, 2=NSC, or 3=special). In case of error, the return value is undefined.
Description
This function obtains the implementation of an object (pointer, byte, NSC, special) from GemStone. For more information about implementation types, see Object implementation.
GciFetchOop
Fetch the OOP of one instance variable of an object.
Return Value
Returns the OOP at the specified index of the source object. In case of error, this function returns OOP_NIL.
Description
This function fetches the OOP of a single instance variable from any object at the specified index, using structural access. It does not distinguish between named and unnamed instance variables. Indices are based at the beginning of the object’s array of instance variables. In that array, any existing named instance variables are followed by any existing unnamed instance variables.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples. This example illustrates fetching one named and one unnamed instance variable from an Account.
BoolType fetchOop_example(OopType anAccount)
{
GciErrSType err;
// fetch the number of named and unnamed instvars
int namedSize = GciFetchNamedSize(anAccount);
int64 varyingSize = GciFetchVaryingSize_(anAccount);
// fetch anAccount's salesRep
int indexOfSalesRep = 3;
if (namedSize < indexOfSalesRep) { return false; }
OopType salesRep = GciFetchOop(anAccount, indexOfSalesRep );
if (GciErr(&err)) {
printf("Error %d, %s\n", err.number, err.message);
return false; }
// fetch the first product in the indexed variables
if (varyingSize < 1) { return false; }
OopType firstProduct = GciFetchOop(anAccount, namedSize + 1 );
if (GciErr(&err)) {
printf("Error %d, %s\n", err.number, err.message);
return false; }
return true;
}
See Also
GciFetchOops
Fetch the OOPs of one or more instance variables of an object.
Arguments
Return Value
Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.) In case of error, this function returns zero.
Description
This function fetches the OOPs of multiple instance variables from any object starting at the specified index, using structural access. It does not distinguish between named and unnamed instance variables. Indices are based at the beginning of the object’s array of instance variables. In that array, any existing named instance variables are followed by any existing unnamed instance variables.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
BoolType fetchOops_example(OopType anAccount)
{
GciErrSType err;
// fetch the number of named and unnamed instvars
int namedSize = GciFetchNamedSize(anAccount);
int64 varyingSize = GciFetchVaryingSize_(anAccount);
int mySize = namedSize + varyingSize;
OopType oBuffer[mySize];
// Two ways to fetch anAccount's products list
GciFetchOops(anAccount, namedSize + 1, oBuffer, varyingSize);
GciFetchVaryingOops(anAccount, 1, oBuffer, varyingSize);
// Fetch the named instance variables PLUS the products list
GciFetchOops(anAccount, 1, oBuffer, mySize);
// oBuffer[0..namedSize-1] are named instVar values
// oBuffer[namedSize] are varying instVar values
if (GciErr(&err)) {
printf("Error %d, %s\n", err.number, err.message);
return false; }
return true;
}
See Also
GciFetchPaths
Fetch selected multiple OOPs from an object tree.
Syntax
BoolType GciFetchPaths(
const OopType theOops[ ],
int numOops,
const int paths[ ],
const int pathSizes[ ],
int numPaths,
OopType results[ ] );
Arguments
Return Value
Returns TRUE if all desired objects were successfully fetched. Returns FALSE if the fetch on any path fails for any reason.
Description
This function allows you to fetch multiple OOPs from selected positions in an object tree with a single GemBuilder call, importing only the desired information from the database.
Each path in the paths array is itself an array of integers. Those integers are offsets that specify a path from which to fetch objects. In each path, a positive integer x refers to an offset within an object’s named instance variables (see GciFetchNamedOop), while a negative integer -x refers to an offset within an object’s indexed instance variables (see GciFetchVaryingOop).
From each object in theOops, this function fetches the object pointed to by each element of the paths array, and stores the fetched object into the results array. The results array contains (numOops * numPaths) elements, stored in the following order:
[0,0]..[0,numPaths-1]..[1,0]..[1,numPaths-1]..[numOops-1,0]..[numOops-1,numPaths-1]
That is, all paths are first applied in order to the first element of theOops. This step is repeated for each subsequent object, until all paths have been applied to all elements of theOops. The result for object i and path j is represented as:
results[ ((i-1) * numPaths) + (j-1) ]
If the fetch on any path fails for any reason, the result of that fetch is reported in the results array as OOP_ILLEGAL. Because some path-fetching errors do not necessarily invalidate the remainder of the information fetched, the system will then attempt to continue its fetching with the remaining paths and objects.
This ability to complete a fetching sequence despite errors means that your application won’t be slowed by a round-trip to GemStone on each fetch to check for errors. Instead, after a fetch is complete, you can cycle through the result and deal selectively at that time with any errors you find.
The appropriate response to an error in path fetching depends both upon the error itself and on your application. Here are some of the reasons why a fetch might not succeed:
- The user had no read authorization for some object in the path. The seriousness of this depends on your application. In some applications, you may simply wish to ignore the inaccessible data.
- The path was invalid for the object to which it was applied. This can happen if the object from which you’re fetching is not of the correct class, or if the path itself is faulty for the class of the object.
- The path was valid but simply not filled out for the object being processed. This would be the case, for example, if you attempted to access address.zip when an Employee’s Address instance variable contained only nil. This is probably the most common path fetching error, and may require only that the application program detect the condition and display some suitable indication to the user that a field is not yet filled in with meaningful data.
Example 1: Calling sequence for a single object and a single path
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
The first example fetches just the street address from a single Account.
OopType fetchPaths_example1(OopType anAccount)
{
GciErrSType errInfo;
int path_size = 3;
int aPath[path_size];
aPath[0] = 2; //name
aPath[1] = 2; //address
aPath[2] = 1; //street
OopType result;
GciFetchPaths(&anAccount, 1, aPath, &path_size, 1, &result);
if (GciErr(&errInfo)) {
printf("Error %d, %s\n", errInfo.number, errInfo.message);
return OOP_NIL;
}
return result;
}
Example 2: Calling sequence for multiple objects with a multiple paths
This example fetches the customer name, and the address city, from two separate accounts.
BoolType fetchPaths_example2(int numOfAccounts, OopType* resultAccounts)
{
GciErrSType errInfo;
OopType myAccts;
myAccts = GciExecuteStr("AllAccounts", OOP_NIL);
if (myAccts == OOP_NIL) { return false; }
int numRet = GciFetchVaryingOops(myAccts, 1, resultAccounts, numOfAccounts);
if (numRet != numOfAccounts) { return false; }
int path_segments[2];
path_segments[0] = 2;
path_segments[1] = 3;
int serialPath[6]; // size is sum of path_segments
serialPath[0] = 2; //customer
serialPath[1] = 1; //name
serialPath[2] = 2; //customer
serialPath[3] = 2; //address
serialPath[4] = 2; //city
OopType results[2 * numOfAccounts]; // size of path_segments * number of accounts
GciFetchPaths(resultAccounts, numOfAccounts, serialPath, path_segments, 2, results);
if (GciErr(&errInfo)) {
printf("GciFetchPaths error %d, %s\n", errInfo.number, errInfo.message);
return false;
}
return true;
}
See Also
GciFetchSharedCounterValuesNoLock
Fetch the value of multiple shared counters without locking them.
Syntax
int GciFetchSharedCounterValuesNoLock(
int startIndex,
int64_t buffer[ ],
size_t * maxReturn);
Arguments
Return Value
Returns an int indicating the number of shared counter values successfully stored in the buffer. Returns -1 if a bad argument is detected.
Description
Fetch the values of multiple shared counters in a single call, without locking any of them. The values of the maxReturn count of shared counters starting at the offset indicated by counterIdx (0-based) are put into the buffer buffer. buffer must be large enough to accommodate maxReturn 8-byte values, and be aligned on an 8-byte boundary.
GciFetchSize_
Description
This function obtains the size of an object from GemStone.
The result of this function depends on the object’s implementation (see GciFetchObjImpl). For byte objects, this function returns the number of bytes in the object. (For Strings, this is the number of Characters in the String; for Floats, the size is 23.) For pointer objects, this function returns the number of named instance variables (GciFetchNamedSize) plus the number of indexed instance variables, if any (GciFetchVaryingSize_). For NSC objects, this function returns the cardinality of the collection. For special objects, the size is always zero.
This differs somewhat from the result of executing the Smalltalk method Object>>size, as shown in Table 7.11:
|
Number of indexed elements PLUS number of named instance variables |
||
GciFetchUtf8Bytes_
Encode a String, MultiByteString, or Uft8 as UTF-8, and fetch the bytes of the encoded result.
Syntax
int64 GciFetchUtf8Bytes_(
OopType oopOfAString,
int64 startIndex,
ByteType * theBytes,
int64 numBytes,
OopType * utf8String,
int flags);
Arguments
Return Value
Returns the number of bytes fetched. (This may be less than numBytes, depending upon the size of theObject.) In case of error, this function returns zero.
Description
This function encodes a kind of String, MultiByteString, or Utf8 into UTF-8. The encoded bytes are placed in the buffer theBytes, and the OOP of the encoded object is placed at utf8String.
The OOP of utf8String is also placed in the ExportSet. The caller must pass the OOP of utf8String to GciReleaseOops after fetching all bytes.
If all characters in aString are < 128, or if the class of aString is Utf8, then the behavior is the same as GciFetchBytes_. No encoding is done; the bytes of aString are place in theBytes. utf8String is the same as aString, and is not added to the ExportSet.
See Also
GciFetchVaryingOop
Fetch the OOP of one unnamed instance variable from an indexable pointer object or NSC.
Arguments
|
The index of the OOP to be fetched. The index of the first unnamed instance variable’s OOP is 1. |
Return Value
Returns the OOP of the unnamed instance variable at index atIndex. In case of error, this function returns OOP_NIL.
Description
This function fetches the OOP of a single unnamed instance variable at the specified index, using structural access. The numerical index of any unordered variable of an NSC can change whenever the NSC is modified.
Example
See Executing the examples for the smalltalk code that supports the examples.
OopType fetchVaryingOop_example(OopType anAccount)
{
GciErrSType err;
int64 varyingSize = GciFetchVaryingSize_(anAccount);
if (varyingSize < 1) { return OOP_NIL; }
// fetch the first product in the indexed variables
OopType firstProduct = GciFetchVaryingOop(anAccount, 1);
if (GciErr(&err)) {
printf("Error %d, %s\n", err.number, err.message);
return OOP_NIL; }
return firstProduct;
}
GciFetchVaryingOops
Fetch the OOPs of one or more unnamed instance variables from an indexable pointer object or NSC.
Syntax
int GciFetchVaryingOops(
OopType theObject,
int64 startIndex,
OopType theOops[ ],
int numOops );
Arguments
Return Value
Returns the number of OOPs fetched. (This may be less than numOops, depending upon the size of theObject.) In case of error, this function returns zero.
Description
This function fetches the OOPs of multiple unnamed instance variables beginning at the specified index, using structural access. The numerical index of any unordered variable of an NSC can change whenever the NSC is modified.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
BoolType fetchVaryingOops_example(OopType anAccount)
{
GciErrSType err;
int64 varyingSize = GciFetchVaryingSize_(anAccount);
if (varyingSize < 1) { return false; }
OopType oBuffer[varyingSize];
// fetch OOPs for all indexed instvars
int numRet = GciFetchVaryingOops(anAccount, 1, oBuffer, varyingSize);
if (GciErr(&err)) {
printf("Error %d, %s\n", err.number, err.message);
return false; }
return numRet = varyingSize;
}
GciFetchVaryingSize_
Fetch the number of unnamed instance variables in a pointer object or NSC.
Return Value
Returns the number of unnamed instance variables in theObject. In case of error, this function returns zero.
Description
This function obtains from GemStone the number of indexed variables in an indexable object or the number of unordered variables in an NSC.
Example
See an example under GciFetchOop.
GciFindObjRep
Fetch an object report in a traversal buffer.
Arguments
Return Value
Returns a pointer to an object report within the traversal buffer. In case of error, this function returns NULL.
Description
This function locates an object report within a traversal buffer that was previously returned by GciTraverseObjs. If the report is not found within the buffer, this function generates the error GCI_ERR_TRAV_OBJ_NOT_FOUND.
Example
GciObjRepHdrSType* findObjRepExample(GciTravBufType *buf, OopType objId)
{
GciObjRepHdrSType *theReport = GciFindObjRep(buf, objId);
if (theReport == NULL) {
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
}
}
return theReport;
}
See Also
GciFloatKind
Obtain the float kind corresponding to a C double value.
Description
This function obtains the kind of GemStone Float object that corresponds to the C floating point value aReal.
See Also
GciFltToOop
Convert a C double value to a SmallDouble or Float object.
Return Value
Returns the OOP of the GemStone SmallDouble or Float object that corresponds to the C value. In case of error, this function returns OOP_NIL.
Description
This function translates a C double precision value into the equivalent GemStone Float object.
Example
#include <stdlib.h>
void fltToOopExample(void)
{
// random double to Oop conversion producing a Float or SmallFloat
double rand = drand48() * 1.0e38 ;
OopType oFltObj = GciFltToOop(rand);
OopType oClass = GciFetchClass(oFltObj);
const char* kind;
if (oClass == OOP_CLASS_SMALL_DOUBLE) {
kind = "SmallDouble";
} else if (oClass == OOP_CLASS_FLOAT) {
kind = "Float";
} else {
kind = "Unexpected";
}
printf("result is a %s, class oop = "FMT_OID"\n", kind, oClass);
}
See Also
GciGetFreeOop
Return Value
Returns an unused object identifier (OOP).
You cannot use the result of GciGetFreeOop to create a Symbol object.
Description
Allocates an object identifier without creating an object.
The object identifier returned from this function remains allocated to the Gci session until the session calls GciLogout or until the identifier is used as an argument to a function call.
If an object identifier returned from GciGetFreeOop is used as a value in a GciStore... call before it is used as the objId argument of a GciCreate... call, then an unresolved forward reference is created in object memory. This is a reference to an object that does not yet exist. This forward reference must be satisfied by using the identifier as the objId argument to a GciCreate... call before a GciCommit can be successfully executed.
If GciCommit is attempted prior to satisfying all unresolved forward references, an error is generated and GciCommit returns FALSE. Then GciCreate can be used to satisfy the forward references and GciCommit can be attempted again. GciAbort removes all unsatisfied forward references from the session’s object space, just as it removes any other uncommitted modifications.
As long as it remains an unresolved forward reference, the identifier returned by GciGetFreeOop can be used only as a parameter to the following function calls, under the given restrictions:
GciCreateByteObj
GciCreateOopObj
GciStoreOop
GciStoreOops
GciStoreIdxOop
GciStoreIdxOops
GciStoreNamedOop
GciStoreNamedOops
GciStoreTrav
GciAppendOops
GciAddOopToNsc
GciAddOopsToNsc
GciNewOopUsingObjRep
GciStorePaths
GciGetFreeOops
Description
Allocates object identifiers without creating objects.
If an object identifier returned from GciGetFreeOops is used as a value in a GciStore... call before it is used as the objId argument of a GciCreate... call, then an unresolved forward reference is created in object memory. This is a reference to an object that does not yet exist. This forward reference must be satisfied by using the identifier as the objId argument to a GciCreate... call before a GciCommit can be successfully executed.
If GciCommit is attempted prior to satisfying all unresolved forward references, an error is generated and GciCommit returns false. In this case, GciCreate can be used to satisfy the forward references and GciCommit can be attempted again. GciAbort removes all unsatisfied forward references from the session’s object space, just as it removes any other uncommitted modifications.
As long as it remains an unresolved forward reference, the identifier returned by GciGetFreeOops can be used only as a parameter to the following function calls, under the given restrictions:
GciCreateByteObj
GciCreateOopObj
GciStoreOop
GciStoreOops
GciStoreIdxOop
GciStoreIdxOops
GciStoreNamedOop
GciStoreNamedOops
GciStoreTrav
GciAppendOops
GciAddOopToNsc
GciAddOopsToNsc
GciNewOopUsingObjRep
GciStorePaths
GciGetFreeOopsEncoded
Arguments
|
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. |
GciGetSessionId
Find the ID number of the current user session.
Return Value
Returns the session ID currently being used for communication with GemStone. Returns GCI_INVALID_SESSION_ID if there is no session ID (that is, if the application is not logged in).
Description
This function obtains the unique session ID number that identifies the current user session to GemStone. An application can have more than one active session, but only one current session.
The ID numbers assigned to your application’s sessions are unique within your application, but bear no meaningful relationship to the session IDs assigned to other GemStone applications that may be executing at the same time or accessing the same database.
Example
void getSessionExample(const char* userId, const char* password)
{
if (GciLogin(userId, password)) {
GciSessionIdType sessId = GciGetSessionId();
printf("sessionId is %d \n", sessId);
}
GciLogout();
GciSessionIdType sessId = GciGetSessionId();
if (sessId != GCI_INVALID_SESSION_ID) {
printf("unexpected sessionId %d after logout \n", sessId);
}
}
See Also
GciHardBreak
Interrupt GemStone and abort the current transaction.
Description
GciHardBreak sends a hard break to the current user session (set by the last GciLogin or GciSetSessionId), which interrupts Smalltalk execution.
All GemBuilder functions can recognize a hard break, so the users of your application can terminate Smalltalk execution. For example, if your application sends a message to an object (via GciPerform), and for some reason the invoked Smalltalk method enters an infinite loop, the user can interrupt the application. GciHardBreak has no effect if called from within a User Action.
In order for GemBuilder functions in your program to recognize interrupts, your program will need a signal handler that can call the functions GciSoftBreak and GciHardBreak. Since GemBuilder does not relinquish control to an application until it has finished its processing, soft and hard breaks must be initiated from a signal handler.
If GemStone is executing when it receives the break, it replies with the error message RT_ERR_HARD_BREAK. Otherwise, it ignores the break.
If GemStone is executing any of the following methods of class Repository, then a hard break terminates the entire session, not just Smalltalk execution:
fullBackupTo:
restoreFromBackup(s):
markForCollection
objectAudit
auditWithLimit:
repairWithLimit:
pagesWithPercentFree
See Also
GciHiddenSetIncludesOop
Determines whether the given OOP is present in the specified hidden set.
Description
The Gem holds objects in a number of sets ordinarily hidden from the user, including the PureExportSet and the GciTrackedObjs (among others). GciHiddenSetIncludesOop allows you to pass in an index to a specified hidden set to determine if the set includes a specific object. For indexes of available hidden sets, see the GemStone Smalltalk method System Class >> HiddenSetSpecifiers.
GciI32ToOop
Convert a C 32-bit integer value to a GemStone object.
Return Value
The GciI32ToOop function returns the OOP of a GemStone object whose value is equivalent to anInt.
Description
The GciI32ToOop function translates a C 32bit integer value into the equivalent GemStone object. This function always succeeds.
See Also
GCI_I64_IS_SMALL_INT
(MACRO) Determine whether or not a 64-bit C integer is in the SmallInteger range.
Description
This macro tests to see if anInt is within the SmallInteger range.
A SmallInteger has a 61 bit 2’s complement integer and 3 tag bits. For a positive int64 argument, top 4 bits must be 2r0000 for argument to be within SmallInteger range; for a negative int64 argument, the top 4 bits must be 2r1111 for argument to be within SmallInteger range.
GciI64ToOop
Convert a C 64-bit integer value to a GemStone object.
Return Value
The GciI64ToOop function returns the OOP of a GemStone object whose value is equivalent to anInt.
Description
The GciI64ToOop function translates a C 64-bit integer (int64_t) value into the equivalent GemStone object. If the result is not a SmallInteger, the result is automatically saved to the export set as described under GciSaveObjs.
See Also
GciIncSharedCounter
Increment the value of a shared counter.
Arguments
Return Value
Returns a C Boolean value indicating if the shared counter was successfully incremented. Returns TRUE if successful, FALSE if an error occurred.
Description
This function increments the value of a particular shared counter by a specified amount. The shared counter is specified by index. The maximum value of this shared counter is INT_MAX (2147483647), attempts to increase a shared counter to higher values is not an error, but does not cause the value to increase further, it will remain set to INT_MAX.
This function is not supported for remote GCI interfaces, and will always return FALSE.
GciDecSharedCounter
GciFetchNumSharedCounters
GciFetchSharedCounterValuesNoLock
GciReadSharedCounter
GciReadSharedCounterNoLock
GciSetSharedCounter
GciInit
Return Value
The function GciInit returns TRUE or FALSE to indicate successful or unsuccessful initialization of GemBuilder.
Description
This function initializes GemBuilder. Among other things, it establishes the default GemStone login parameters.
If your C application program is linkable, you may wish to call GciInitAppName, which you must do before you call GciInit. After GciInitAppName, you must call GciInit before calling any other GemBuilder functions. Otherwise, GemBuilder behavior will be unpredictable.
(Note that when doing run-time binding, you would call GciRtlLoad before calling GciInit. For details, see Building the Application.)
When GemBuilder is initialized on UNIX platforms, it establishes its own handler for SIGIO interrupts. See Signal Handling in Your GemBuilder Application for information on GciInit’s handling of interrupts and pointers on making GemBuilder, application, and third-party handlers work together.
See Also
GciInitAppName_
Override the default application configuration file name.
Syntax
void GciInitAppName(
const char * applicationName,
BoolType logWarnings );
void GciInitAppName_(
const char * applicationName,
BoolType logWarnings,
unsigned int gemTOCOverrideKB,
int gemNativeCodeOverride );
Arguments
Description
This function affects only linkable applications. It has no effect on RPC applications. If you do not call this function before you call GciInit, it will have no effect.
A linkable GemBuilder application reads a configuration file called applicationName.conf when GciInit is called. This file can alter the behavior of the underlying GemStone session. For complete information, please see the System Administration Guide for GemStone/S 64 Bit.
A linkable GemBuilder application uses defaults until it calls this function (if it does) and reads the configuration file (which it always does). For linkable GemBuilder applications, the default application name is gci, so the default executable configuration file is gci.conf. The applicationName argument overrides the default application name with one of your choice, which causes your linkable GemBuilder application to read its own executable configuration file.
The logWarnings argument determines whether or not warnings that are generated while reading the configuration file are written to standard output. If your application does not call GciInitAppName, the default log warnings setting is FALSE. The logWarnings argument resets the default for your application, which is used in the absence of a LOG_WARNINGS entry in the configuration file, or until that entry is read.
The GciInitAppName_ variant allows you to specify additional arguments that are used by the linkable GemBuilder application: the maximum temporary object cache size, and an override for the native code configuration.
You application may not call both GciInitAppName and GciInitAppName_.
See Also
GciInstallUserAction_
Associate a C function with a Smalltalk user action.
Syntax
void GciInstallUserAction(
GciUserActionSType * userAction );
void GciInstallUserAction_(
GciUserActionSType * userAction,
BoolType errorIfDuplicate );
Arguments
Description
This function associates a user action name (declared in Smalltalk) with a user-written C function. Your application must call GciInstallUserAction before beginning any GemStone sessions with GciLogin. This function is typically called from GciUserActionInit. For more information, see Chapter 4, “Writing User Actions”
GciInstMethodForClass
Compile an instance method for a class.
Syntax
OopType GciInstMethodForClass(
OopType source,
OopType aClass,
OopType category,
OopType symbolList );
Arguments
Return Value
Returns OOP_NIL, unless there were compiler warnings (such as variables declared but not used, etc.), in which case the return will be the OOP of a string containing the warning messages.
Description
This function compiles an instance method for the given class.
Note that the Smalltalk virtual machine optimizes a small number of selectors, and you may not compile methods for any of those selectors. See the Programming Guide for a list of the optimized selectors.
To remove a class method, use GciExecuteStr to execute an expression removing the method, or GciClassRemoveAllMethods to remove all methods.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
void instanceMethodExample(void)
{
// Assumes the setup code has been executed.
OopType theClass = GciResolveSymbol("Customer", OOP_NIL);
OopType oCateg = GciNewString("Printing");
OopType oMethodSrc = GciNewString("asString ^ 'Customer named ', name asString") ;
GciInstMethodForClass(oMethodSrc, theClass, oCateg, OOP_NIL);
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
}
}
See Also
GciInUserAction
Determine whether or not the current process is executing a user action.
Return Value
This function returns TRUE if it is called from within a user action, and FALSE otherwise.
Description
This function is intended for use within signal handlers. It can be called any time after GciInit.
GciInUserAction returns FALSE if the process is currently executing within a GemBuilder call that was made from a user action. It considers the highest (most recent) call context only.
See Also
GciIsKindOf
Determine whether or not an object is some kind of a given class or class history.
Arguments
Return Value
GciIsKindOf returns TRUE when the class of anObj or any of its superclasses is in the class history of possibleClass. It returns FALSE otherwise.
Description
GciIsKindOf performs structural access that is equivalent to the isKindOf: method of the Smalltalk class Object. It compares anObj’s class and superclasses to see if any of them are in a given class history. When possibleClass is simply a class (which is typical), GciIsKindOf uses possibleClass’s class history. When possibleClass is itself a class history, GciIsKindOf uses possibleClass directly.
Since GciIsKindOf does consider class histories, it can help to support schema modification by simplifying checks on the relationship of types when they can change over time. To accomplish a similar operation without seeing the effects of class histories, use the GciIsKindOfClass function.
GciIsKindOfClass
Determine whether or not an object is some kind of a given class.
Return Value
GciIsKindOfClass returns TRUE when the class of anObject or any of its superclasses is possibleClass. It returns FALSE otherwise.
Description
GciIsKindOfClass performs structural access that is equivalent to the isKindOf: method of the Smalltalk class Object. It compares anObject’s class and superclasses to see if any of them are the possibleClass.
Since GciIsKindOfClass does not consider class histories, it cannot help to support schema modification. To accomplish a similar operation when the relationship of types can change over time, use the GciIsKindOf function.
GciIsRemote
Determine whether the application is running linked or remotely.
GciIsSubclassOf
Determine whether or not a class is a subclass of a given class or class history.
Arguments
Return Value
GciIsSubclassOf returns TRUE when testClass or any of its superclasses is in the class history of possibleClass. It returns FALSE otherwise.
Description
GciIsSubclassOf performs structural access that is equivalent to the isSubclassOf: method of the Smalltalk class Behavior. It compares testClass and testClass’s superclasses to see if any of them are in a given class history. When possibleClass is simply a class (which is typical), GciIsSubclassOf uses possibleClass’s class history. When possibleClass is itself a class history, GciIsSubclassOf uses possibleClass directly.
Since GciIsSubclassOf does consider class histories, it can help to support schema modification by simplifying checks on the relationship of types when they can change over time. To accomplish a similar operation without seeing the effects of class histories, use the GciIsSubclassOfClass function.
GciIsSubclassOfClass
Determine whether or not a class is a subclass of a given class.
Return Value
GciIsSubclassOf returns TRUE when testClass or any of its superclasses is possibleClass. It returns FALSE otherwise.
Description
GciIsSubclassOfClass performs structural access that is equivalent to the isSubclassOf: method of the Smalltalk class Behavior. It compares testClass and testClass’s superclasses to see if any of them are the possibleClass.
Since GciIsSubclassOfClass does not consider class histories, it cannot help to support schema modification. To accomplish a similar operation when the relationship of types can change over time, use the GciIsSubclassOf function.
See Also
GciIvNameToIdx
Fetch the index of an instance variable name.
Return Value
Returns the index of instVarName into the array of named instance variables for the specified class. Returns 0 if the name is not found or if an error is encountered.
Description
This function searches the array of instance variable names for the specified class (including those inherited from superclasses), and returns the index of the specified instance variable name. This index could then be used as the atIndex parameter in functions such as GciFetchNamedOop or GciStoreNamedOop.
Example
BoolType nameToIdx_example(void)
{
// Find offset for maximum in an OutOfRange exception
OopType theClass = GciResolveSymbol("OutOfRange", OOP_NIL);
int idx = GciIvNameToIdx(theClass, "maximum");
if (idx < 1) {
printf("error during GciIvNameToIdx\n");
return false;
}
return idx = 12;
}
See Also
GciLoadUserActionLibrary
Load an application user action library.
Syntax
BoolType GciLoadUserActionLibrary(
const char * uaLibraryName[ ],
BoolType mustExist,
void ** libHandlePtr,
char infoBuf[ ],
int64 infoBufSize );
Arguments
|
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. |
|
Return Value
A C Boolean value. If an error occurs, the return value is FALSE, and the error message is stored in infoBuf, unless infoBuf is NULL. Otherwise, the return value is TRUE, and the name of the user action library is stored in infoBuf.
Description
This function loads a user action shared library at run time. If uaLibraryName does not contain a path, then a standard user action library search is done. The proper prefix and suffix for the current platform are added to the basename if necessary. For more information, see Chapter 4, “Writing User Actions”
If a library is loaded, libHandlePtr is set to a value that represents the loaded library, if libHandlePtr is not NULL. If mustExist is TRUE, then an error is generated if the library can not be found. If mustExist is FALSE, then the library does not need to exist. In this case, TRUE is returned and libHandlePtr is NULL if the library does not exist and non-NULL if it exists.
GciLogin
Arguments
Description
Users must log in before any work may be performed. This function creates a user session and its corresponding transaction workspace.
This function uses the current network parameters (as specified by GciSetNet) to establish the user’s GemStone session.
Example
BoolType login_example(void)
{
// assume the netldi on machine lichen been started with -a -g
// so that host userId and host password are not required.
const char* StoneName = "gs64stone";
const char* HostUserId = "";
const char* HostPassword = "";
const char* GemService = "gemnetobject";
const char* gsUserName = "DataCurator";
const char* gsPassword = "swordfish";
// GciInit required before first login
if (!GciInit()) {
printf("GciInit failed\n");
return FALSE;
}
GciSetNet(StoneName, HostUserId, HostPassword, GemService);
BoolType success = GciLogin(gsUserName, gsPassword);
if (! success) {
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
}
}
return success;
}
See Also
GciLoginEx
Start a user session with session configuration
Syntax
BoolType GciLoginEx(
const char gemstoneUsername[ ],
const char gemstonePassword[ ] ,
unsigned int loginFlags,
int haltOnErrNum);
Arguments
|
A legacy error number; if nonzero, specifies a value for GEM_HALT_ON_ERROR config parameter. |
Description
This function creates a user session and its corresponding transaction workspace. The current network parameters , as specified by GciSetNet, are used to establish the user’s GemStone session.
Other login attributes are provided by loginFlags. The value of loginFlags should be given using the following GemBuilder mnemonics:
GCI_LOGIN_PW_ENCRYPTED indicates the gemstonePassword is encrypted. When specifying this flag, you must encrypt the password using GciEncrypt.
GCI_LOGIN_IS_SUBORDINATE 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 the login will use full compression.
GCI_LOGIN_ERRS_USE_REF_SET sets the OOPs of objects related to errors to be put into the ReferencedSet, rather than the PureExportSet.
GCI_LOGIN_QUIET suppresses printing of banner information during login.
GCI_CLIENT_DOES_SESSION_INIT 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 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).
If haltOnErrNum is set to a GemStone error number, and the session encounters the error associated with that error number, the session will halt.
Example
For an example, see GciEncrypt
See Also
GciLogout
Description
This function terminates the current user session (set by the last GciLogin or GciSetSessionId), and allows GemStone to release all uncommitted objects created by the application program in the corresponding transaction workspace. The current session ID is reset to GCI_INVALID_SESSION_ID, indicating that the application is no longer logged in. (See GciGetSessionId for more information.)
See Also
GciLongJmp
Provides equivalent functionality to the corresponding longjmp() or _longjmp() function.
GciMoreTraversal
Continue object traversal, reusing a given buffer.
Arguments
|
A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType. |
Return Value
Returns FALSE if the traversal is not yet completed, but further traversal would cause the travBuffSize to be exceeded. If the travBuffSize is reached before the traversal is complete, you can continue to call GciMoreTraversal to proceed from the point where travBuffSize was exceeded.
Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal.
Description
When the amount of information obtained in a traversal exceeds the amount of memory available to the buffer (as specified with travBuffSize), your application can call GciMoreTraversal repeatedly to break the traversal into manageable amounts of information. The information returned by this function begins with the object report following where the previous unfinished traversal left off. The level value is retained from the initial GciTraverseObjs call.
Generally speaking, an application can continue to call GciMoreTraversal until it has obtained all requested information.
Naturally, GemStone will not continue an incomplete traversal if there is any chance that changes to the database in the intervening period might have invalidated the previous report or changed the connectivity of the objects in the path of the traversal. Specifically, GemStone will refuse to continue a traversal if, in the interval before attempting to continue, you:
- Modify the objects in the database directly by calling any of the GciStore... or GciAdd... functions;
- Call one of the Smalltalk message-sending functions GciPerform, GciContinue, or any of the GciExecute... functions.
- Abort your transaction, thus invalidating any subsequent information from that traversal.
Any attempt to call GciMoreTraversal after one of these events will generate an error.
Note that this holds true across multiple GemBuilder applications sharing the same GemStone session. Suppose, for example, that you were holding on to an incomplete traversal buffer and the user moved from the current application to another, did some work that required executing Smalltalk code, and then returned to the original application. You would be unable to continue the interrupted traversal.
If you attempt to call GciMoreTraversal when no traversal is underway, this function will generate the error GCI_ERR_TRAV_COMPLETED.
During the entire sequence of GciTraverseObjs and GciMoreTraversal calls that constitute a traversal, any single object report will be returned exactly once. Regardless of the connectivity of objects in the GemStone database, only one report will be generated for any non-special object.
The section Organization of the Traversal Buffer describes the organization of traversal buffers in detail.
GciMoreTraversal provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
void moreTraversalExample(void)
{
// Assumes setup code has been run
OopType rootObj = GciResolveSymbol("AllAccounts", OOP_NIL);
GciTravBufType *buf = GciTravBufType::malloc(8000);
int totalCount = 0;
// traverse the AllAccounts collection to 4 levels deep
BoolType done = GciTraverseObjs(&rootObj, 1, buf, 4);
while (! done) {
int objCount = 0;
GciObjRepHdrSType *rpt = buf->firstReportHdr();
GciObjRepHdrSType *limit = buf->readLimitHdr();
while (rpt < limit) {
objCount++ ;
rpt = rpt->nextReport();
}
totalCount += objCount;
done = GciMoreTraversal(buf);
}
buf->free();
printf("traversal returned %d total objects\n", totalCount);
}
GciNbAbort
Abort the current transaction (nonblocking).
Description
The GciNbAbort function is equivalent in effect to GciAbort. However, GciNbAbort permits the application to proceed with non-GemStone tasks while the transaction is aborted, and GciAbort does not.
See Also
GciNbBegin
Begin a new transaction (nonblocking).
Description
The GciNbBegin function is equivalent in effect to GciBegin. However, GciNbBegin permits the application to proceed with non-GemStone tasks while a new transaction is started, and GciBegin does not.
See Also
GciNbClampedTrav
Traverse an array of objects, subject to clamps (nonblocking).
Syntax
void GciNbClampedTrav(
const OopType * theOops,
int numOops,
GciClampedTravArgsSType * travArgs );
Arguments
|
Pointer to an instance of GciClampedTravArgsSType. See GciClampedTrav for documentation on the fields in travArgs. On return, the result is in the travBuff field of the travArgs instance of GciClampedTravArgsSType. |
Return Value
The GciNbClampedTrav function, unlike GciClampedTrav, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciClampedTrav by using the argument to GciNbEnd.
Description
This function is equivalent in effect to GciClampedTrav. However, GciClampedTrav permits the application to proceed with non-GemStone tasks while a traversal is carried out, and GciClampedTrav does not.
See Also
GciNbCommit
Write the current transaction to the database (nonblocking).
Return Value
The GciNbCommit function, unlike GciCommit, does not have a return value. However, when the commit operation is complete, you can access a value identical in meaning to the return value of GciCommit by using the argument to GciNbEnd.
Description
This function is equivalent in effect to GciCommit. However, GciNbCommit permits the application to proceed with non-GemStone tasks while the transaction is committed, and GciCommit does not.
See Also
GciNbContinue
Continue code execution in GemStone after an error (nonblocking).
Arguments
|
The OOP of a GsProcess object (obtained as the value of the context field of an error report returned by GciErr). |
Return Value
The GciNbContinue function, unlike GciContinue, does not have a return value. However, when the continued operation is complete, you can access a value identical in meaning to the return value of GciContinue by using the argument to GciNbEnd.
Description
The GciNbContinue function is equivalent in effect to GciContinue. However, GciNbContinue permits the application to proceed with non-GemStone tasks while the operation continues, and GciContinue does not.
See Also
GciNbContinueWith
Continue code execution in GemStone after an error (nonblocking).
Syntax
void GciNbContinueWith (
OopType process,
OopType replaceTopOfStack,
int flags,
GciErrSType * error );
Arguments
|
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. |
Description
The GciNbContinueWith function is equivalent in effect to GciContinueWith. However, GciNbContinueWith permits the application to proceed with non-GemStone tasks while the operation continues, and GciContinueWith does not.
See Also
GciNbEnd_
Test the status of nonblocking call in progress for completion.
Arguments
Return Value
The GciNbEnd function returns an enumerated type. Its value is GCI_RESULT_READY if the outstanding nonblocking call has completed execution and its result is ready, GCI_RESULT_NOT_READY if the call is not complete and there has been no change since the last inquiry, and GCI_RESULT_PROGRESSED if the call is not complete but progress has been made towards its completion.
Description
Once an application calls a nonblocking function, it must call GciNbEnd, GciNbEnd_, or GciNbEndPoll at least once, and must continue to do so until that nonblocking function has completed execution. The intent of the return values is to give the scheduler a hint about whether it is calling one of these functions too often or not often enough.
Once an operation is complete, you are permitted to call GciNbEnd or a related function repeatedly. It returns GCI_RESULT_READY and a pointer to the same result each time, until you call a nonblocking function again. It is an error to call GciNbEnd or a related function before you call any nonblocking functions at all. Use the GciCallInProgress function to determine whether or not there is a GemBuilder call currently in progress.
Example
void nbEnd_example(void)
{
void *resultPtr;
GciNbExecuteStr("Globals size", OOP_NIL);
do {
// wait for non-blocking result
GciHostMilliSleep(1);
} while (GciNbEnd(&resultPtr) != GCI_RESULT_READY);
OopType result = *(OopType*)resultPtr;
BoolType conversionErr = FALSE;
int gSize = GciOopToI32_(result, &conversionErr);
if (conversionErr) {
printf("error in execution\n");
} else {
printf("Globals size = %d \n", gSize);
}
}
See Also
GciNbEndPoll
Test the status of nonblocking call in progress for completion, with timeout.
Arguments
Return Value
The GciNbEndPoll function returns an enumerated type. Its value is GCI_RESULT_READY if the outstanding nonblocking call has completed execution and its result is ready, GCI_RESULT_NOT_READY if the call is not complete and there has been no change since the last inquiry, and GCI_RESULT_PROGRESSED if the call is not complete but progress has been made towards its completion.
Description
Once an application calls a nonblocking function, it must call GciNbEndPoll, GciNbEnd, or GciNbEnd_ at least once, and must continue to do so until that nonblocking function has completed execution. The intent of the return values is to give the scheduler a hint about whether it is calling GciNbEndPoll too often or not often enough.
GciNbEndPoll allows you to specify a timeout, and will wait for timeoutMs milliseconds before returning status. This avoids too-frequent polling for long-running code.
Once an operation is complete, you are permitted to call GciNbEndPoll repeatedly. It returns GCI_RESULT_READY and a pointer to the same result each time, until you call a nonblocking function again. It is an error to call GciNbEndPoll before you call any nonblocking functions at all. Use the GciCallInProgress function to determine whether or not there is a GemBuilder call currently in progress.
See Also
GciNbExecute
Execute a Smalltalk expression contained in a String object (nonblocking).
Arguments
Return Value
The GciNbExecute function, unlike GciExecute, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecute by using the argument to GciNbEnd.
GciNbExecuteStr
Execute a Smalltalk expression contained in a C string (nonblocking).
Arguments
Return Value
The GciNbExecuteStr function, unlike GciExecuteStr, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecuteStr by using the argument to GciNbEnd.
GciNbExecuteStrFetchBytes
Execute a Smalltalk expression contained in a C string, returning byte-format results (nonblocking).
Syntax
void GciNbExecuteStrFetchBytes(
const char * sourceStr,
int64 sourceSize,
OopType sourceClass,
OopType contextObject,
OopType symbolList,
ByteType * result,
int64 maxResultSize );
Arguments
Return Value
The GciNbExecuteStrFetchBytes function, unlike GciExecuteStrFetchBytes, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecuteStrFetchBytes by using the argument to GciNbEnd.
GciNbExecuteStrFromContext
Execute a Smalltalk expression contained in a C string as if it were a message sent to an object (nonblocking).
Syntax
void GciNbExecuteStrFromContext(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList );
Arguments
Return Value
The GciNbExecuteStrFromContext function, unlike GciExecuteStrFromContext, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciExecuteStrFromContext by using the argument to GciNbEnd.
GciNbExecuteStrTrav
First execute a Smalltalk expression contained in a C string as if it were a message sent to an object, then traverse the result of the execution (nonblocking).
Syntax
void GciNbExecuteStrTrav(
const char sourceStr[ ],
OopType contextObject,
OopType symbolList,
GciClampedTravArgsSType * travArgs );
Arguments
|
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. |
Return Value
The GciNbExecuteStrTrav function, unlike GciExecuteStrTrav, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciExecuteStrTrav by using the argument to GciNbEnd.
Description
The GciNbExecuteStrTrav function is equivalent in effect to GciExecuteStrTrav. However, GciNbExecuteStrTrav permits the application to proceed with non-GemStone tasks while the traversal is completed, and GciExecuteStrTrav does not.
See Also
GciExecuteStrTrav includes information details on traversal.
GciNbEnd
GciNbExecute
GciPerformTraverse
GciNbLoginEx
Start a user session with session configuration (nonblocking)
Syntax
BoolType GciLoginEx(
const char gemstoneUsername[ ],
const char gemstonePassword[ ] ,
unsigned int loginFlags,
int haltOnErrNum);
Arguments
|
A legacy error number; if nonzero, specifies a value for GEM_HALT_ON_ERROR config parameter. |
Description
This function creates a user session and its corresponding transaction workspace. The current network parameters , as specified by GciSetNet, are used to establish the user’s GemStone session.
Other login attributes are provided by loginFlags. The value of loginFlags should be given using the 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 session will halt.
See Also
GciNbMoreTraversal
Continue object traversal, reusing a given buffer (nonblocking).
Arguments
|
A buffer in which the results of the traversal will be placed. For details, see Traversal Buffer - GciTravBufType. |
Return Value
The GciNbMoreTraversal function, unlike GciMoreTraversal, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciMoreTraversal by using the argument to GciNbEnd.
Description
The GciNbMoreTraversal function is equivalent in effect to GciMoreTraversal. However, GciNbMoreTraversal permits the application to proceed with non-GemStone tasks while the traversal is completed, and GciMoreTraversal does not.
GciNbMoreTraversal provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.
GciNbPerform
Send a message to a GemStone object (nonblocking).
Syntax
void GciNbPerform(
OopType receiver,
const char selectorStr[ ],
const OopType args[ ],
int numArgs );
Arguments
Return Value
The GciNbPerform function, unlike GciPerform, does not have a return value. However, when the performed operation is complete, you can access a value identical in meaning to the return value of GciPerform by using the argument to GciNbEnd.
GciNbPerformFetchBytes
Send a message to a GemStone object, returning byte results (nonblocking).
Syntax
void GciNbPerformFetchBytes(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
ByteType * result,
ssize_t maxResultSize);
Arguments
Return Value
The GciNbPerformFetchBytes function, unlike GciPerformFetchBytes, does not have a return value. However, when the executed operation is complete, you can access a value identical in meaning to the return value of GciPerformFetchBytes by using the argument to GciNbEnd.
Description
This function sends a message (that is, the selector along with any keyword arguments and their corresponding values) to the specified receiver (an object in the GemStone database), and puts the result, which should be a byte format object, in the *result buffer.
See Also
GciNbPerformNoDebug
Send a message to a GemStone object, and temporarily disable debugging (nonblocking).
Syntax
void GciNbPerformNoDebug(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
int flags );
Arguments
|
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. |
Return Value
The GciNbPerformNoDebug function, unlike GciPerformNoDebug, does not have a return value. However, when the performed operation is complete, you can access a value identical in meaning to the return value of GciPerformNoDebug by using the argument to GciNbEnd.
GciNbPerformTrav
First send a message to a GemStone object, then traverse the result of the message (nonblocking).
Syntax
void GciNbPerformTrav(
OopType receiver,
const char * selector,
const OopType * args,
int numArgs,
GciClampedTravArgsSType * travArgs );
Arguments
|
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. |
Return Value
The GciNbPerformTrav function, unlike GciPerformTrav, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciPerformTrav by using the argument to GciNbEnd.
Description
The GciNbPerformTrav function is equivalent in effect to GciPerformTrav. However, GciNbStoreTrav permits the application to proceed with non-GemStone tasks while the traversal is done, and GciPerformTrav does not.
See Also
GciNbStoreTrav
Stores multiple traversal buffer values in objects (nonblocking).
Arguments
Description
The GciNbStoreTrav function is equivalent in effect to GciStoreTrav. However, GciNbStoreTrav permits the application to proceed with non-GemStone tasks while the traversals are stored, and GciStoreTrav does not.
GciNbStoreTrav provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.
GciNbStoreTravDo_
Store multiple traversal buffer values in objects, execute the specified code, and return the resulting object (non-blocking).
Arguments
|
An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_. |
Return Value
Unlike GciStoreTravDo_, the GciNbStoreTravDo_ function does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciStoreTravDo_ by using the argument to GciNbEnd.
GciNbStoreTravDoTrav_
Combine in a single function the calls to GciNbStoreTravDo_ and GciNbClampedTrav, to store multiple traversal buffer values in objects, execute the specified code, and traverse the result object (non-blocking).
Syntax
void GciNbStoreTravDoTrav_(
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );
Arguments
|
An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_. |
|
|
An instance of GciClampedTravArgsSType. For details, refer to the discussion of GciClampedTrav. |
Return Value
The GciNbStoreTravDoTrav_ function, unlike GciStoreTravDoTrav_, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciStoreTravDoTrav_ by using the argument to GciNbEnd.
Description
This function allows the client to execute behavior on the Gem and return the traversal of the result object in a single network round-trip.
The GciNbStoreTravDoTrav_ function is equivalent in effect to GciStoreTravDoTrav_. However, GciNbStoreTravDoTrav_ permits the application to proceed with non-GemStone tasks while the traversals are stored, and GciStoreTravDoTrav_ does not.
GciNbStoreTravDoTravRefs_
Combine in a single function modifications to session sets, traversal of objects to the server, optional Smalltalk execution, and traversal to the client of changed objects and (optionally) the result object (non blocking).
Syntax
void GciNbStoreTravDoTravRefs_(
const OopType * oopsNoLongerReplicated,
int numNotReplicated,
const OopType * oopsGcedOnClient,
int numGced,
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );
Arguments
|
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. |
Return Value
The GciNbStoreTravDoTravRefs_ function, unlike GciStoreTravDoTravRefs_, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciStoreTravDoTravRefs_ by using the argument to GciNbEnd
Description
This function allows the client to modify the PureExportSet and ReferencedSet, modify or create any number of objects on the server, execute behavior on the Gem, and return the traversal of the result object, all in a single network round-trip.
The GciNbStoreTravDoTravRefs_ function is equivalent in effect to GciStoreTravDoTravRefs_. However, GciNbStoreTravDoTravRefs_ permits the application to proceed with non-GemStone tasks while the traversals are stored, and GciStoreTravDoTravRefs_ does not.
GciNbTraverseObjs
Traverse an array of GemStone objects (nonblocking).
Syntax
void GciNbTraverseObjs(
const OopType theOops[ ],
int numOops,
GciTravBufType * travBuff,
int level );
Arguments
|
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. |
Return Value
The GciNbTraverseObjs function, unlike GciTraverseObjs, does not have a return value. However, when the traversal operation is complete, you can access a value identical in meaning to the return value of GciTraverseObjs by using the argument to GciNbEnd.
Description
The GciNbTraverseObjs function is equivalent in effect to GciTraverseObjs. However, GciNbTraverseObjs permits the application to proceed with non-GemStone tasks while the traversal is completed, and GciTraverseObjs does not.
GciNbTraverseObjs provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.
GciNewByteObj
Create and initialize a new byte object.
Arguments
|
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. |
|
Description
Returns a new instance of aClass, of size valueSize, and containing a copy of the bytes located at value. Equivalent to GciNewOop followed by GciStoreBytes. aClass must be a class whose format is Bytes.
See Also
GciNewCharObj
Create and initialize a new character object.
Arguments
Description
Returns a new instance of aClass which has been initialized to contain the bytes of cString, excluding the null terminator.
See Also
GciNewDateTime
Create and initialize a new date-time object.
Description
Creates a new instance of theClass having the value that timeVal points to. For details on GciDateTimeSType, see Date/Time Structure- GciDateTimeSType.
GciNewOop
Arguments
Description
This function creates a new object of the specified class and returns the object’s OOP. It cannot be used to create instances of Symbol or DoubleByteSymbol.
GciNewOops
Create multiple new GemStone objects.
Syntax
void GciNewOops(
int numOops,
const OopType classes[ ],
const int64 idxSize[ ],
OopType result[ ] );
Arguments
Return Value
If an error is encountered, this function will stop at the first error and the contents of the result array will be undefined.
Description
This function creates multiple objects of the specified classes and sizes, and returns the OOPs of the new objects.
Each OOP in classes may be the OOP of a class that you have created, or it may be one of the Smalltalk kernel classes, such as OOP_CLASS_STRING for an object of class String. This function cannot be used to create instances of Symbol or DoubleByteSymbol. If classes contains the OOP of a class with special implementation (such as Boolean), then the corresponding element in result is OOP_NIL. See $GEMSTONE/include/gcioop.ht for the C constants that are defined for GemStone kernel classes.
GciNewOops generates an error when either of the following conditions is TRUE for any object:
Example
void newOops_example(void)
{
enum { num_objs = 3 };
OopType classes[num_objs];
classes[0] = OOP_CLASS_STRING;
classes[1] = OOP_CLASS_IDENTITY_SET;
classes[2] = OOP_CLASS_ARRAY;
int64 sizes[num_objs];
sizes[0] = 50;
sizes[1] = 0; /* ignored for NSCs anyway */
sizes[2] = 3;
OopType newObjs[num_objs];
GciNewOops(num_objs, classes, sizes, newObjs);
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
} else {
printf("objIds of new objects are "FMT_OID" "FMT_OID" "FMT_OID"\n",
newObjs[0], newObjs[1], newObjs[2]);
}
}
GciNewOopUsingObjRep
Create a new GemStone object from an existing object report.
Arguments
Description
This function allows you to submit an object report that creates a GemStone object and specifies the values of its instance variables. You can use this function to define a String, pointer, or NSC object with known OOPs.
The object report consists of two parts: a header (a GciObjRepHdrSType structure) followed by a value buffer (an array of values of the object’s instance variables). For more information on object reports, see Object Report Structure - GciObjRepSType.
GciNewOopUsingObjRep provides automatic byte swizzling for Float and SmallFloat objects. (For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.)
Error Conditions
In addition to general GemBuilder error conditions, this function generates an error if any of the following conditions exist:
- If (idxSize < 0)
- If (idxSize + namedSize) > maxSmallInt
- If firstOffset > (objSize + 1)
- For pointer objects and NSCs, if valueBuffSize is not divisible by 4
- If the specified oclass is not the OOP of a Smalltalk class object
- If the specified oclass and implementation (objImpl) do not agree
- If objId is a Float or SmallFloat, then startIndex must be one and valueBuffSize must be the actual size for the class of objId.
Note that you cannot use this function to create new special objects (instances of SmallInteger, Character, Boolean, SmallDouble, or UndefinedObject).
Example
void newOopUsingObjRep_example(void)
{
int arrSize = 100;
size_t bodySize = sizeof(OopType) * arrSize ;
size_t rptSize = GCI_ALIGN(sizeof(GciObjRepSType) + bodySize );
GciObjRepSType *rpt = (GciObjRepSType*) malloc(rptSize);
if (rpt == NULL) {
printf("malloc failure\n");
return;
}
rpt->hdr.objId = OOP_NIL; // ignored by GciNewOopUsingObjRep
rpt->hdr.oclass = OOP_CLASS_ARRAY;
rpt->hdr.setObjImpl(GC_FORMAT_OOP);
rpt->hdr.segmentId = WORLD_RW_SEGMENT_ID ;
rpt->hdr.firstOffset = 1;
rpt->hdr.namedSize = 0; // ignored by GciNewOopUsingObjRep
rpt->hdr.setIdxSize( arrSize );
rpt->hdr.valueBuffSize = bodySize ;
OopType *body = rpt->valueBufferOops();
for (int i = 0; i < arrSize; i += 1) {
body[i] = GciI32ToOop(i);
}
GciNewOopUsingObjRep(rpt);
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
}
}
GciNewUtf8String
Create a new Unicode string object from a UTF-8 encoded C character string.
Arguments
GciNscIncludesOop
Determines whether the given OOP is present in the specified unordered collection.
Description
GciNscIncludesOop searches the specified unordered collection to determine if it includes the specified object. It is equivalent to the GemStone Smalltalk method UnorderedCollection >> includesIdentical:.
GciObjRepSize_
Find the number of bytes in an object report.
Description
This function calculates the number of bytes in an object report. Before your application allocates memory for a copy of the object report, it can call this function to obtain the size of the report.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
void objRepSize_example(void)
{
OopType rootObj = GciResolveSymbol("AllAccounts", OOP_NIL);
GciTravBufType *buf = GciAllocTravBuf(8000);
GciTraverseObjs(&rootObj, 1, buf, 10);
GciObjRepHdrSType *rpt = buf->firstReportHdr();
GciObjRepHdrSType *limit = buf->readLimitHdr();
if (rpt < limit) {
size_t reportSize = GciObjRepSize_(rpt);
printf("size of first report is %ld bytes\n", reportSize);
} else {
printf("error, GciTraverseObjs returned empty buffer\n");
}
}
See Also
GCI_OOP_IS_BOOL
(MACRO) Determine whether or not a GemStone object represents a GemStone Smalltalk Boolean.
See Also
GCI_OOP_IS_CHAR
(MACRO) Determine whether or not a GemStone object represents a Character.
GCI_OOP_IS_SMALL_FRACTION
(MACRO) Determine whether or not a GemStone object represents a SmallFraction.
GCI_OOP_IS_SMALL_INT
(MACRO) Determine whether or not a GemStone object represents a SmallInteger.
GCI_OOP_IS_SPECIAL
(MACRO) Determine whether or not a GemStone object has a special representation.
Return Value
A C Boolean value. Returns TRUE if the object has a special representation, FALSE otherwise.
GciOopToBool
Convert a Boolean object to a C Boolean value.
Return Value
Returns the C Boolean value that corresponds to the GemStone object. In case of error, this function returns FALSE.
Example
BoolType oopToBoolExample(OopType anObj)
{
BoolType aBool = GciOopToBool(anObj);
GciErrSType errInfo;
if (GciErr(&errInfo)) {
// argument was not a Boolean
printf("error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
return 0;
}
return aBool;
}
See Also
GCI_OOP_TO_BOOL
(MACRO) Convert a Boolean object to a C Boolean value.
Return Value
A C Boolean value. Returns the C Boolean value that corresponds to the GemStone object. In case of error, this macro returns FALSE.
Description
This macro translates a GemStone Boolean object into the equivalent C Boolean value.
Provided for compatibility only. New code should use GciOopToBool. For the definition of GCI_OOP_TO_BOOL, see $GEMSTONE/include/gcicmn.ht
See Also
GciOopToChar16
Convert a Character object to a 16-bit C character value.
Return Value
Returns the 16-bit C character value that corresponds to the GemStone object. In case of error, this function returns zero.
Description
This function translates a GemStone Character object into the equivalent 16-bit C character value.
See Also
GciOopToChar32
Convert a Character object to a 32-bit C character value.
Return Value
Returns the 32-bit C character value that corresponds to the GemStone object. In case of error, this function returns zero.
Description
This function translates a GemStone Character object into the equivalent 32-bit C character value.
See Also
GciOopToChr
Convert a Character object to a C character value.
Return Value
Returns the C character value that corresponds to the GemStone object. In case of error, this function returns zero.
Attempting to convert a GemStone Character that is outside the range of C characters will result in an error.
Description
This function translates a GemStone Character object into the equivalent C character value.
GCI_OOP_TO_CHR
(MACRO) Convert a Character object to a C character value.
Return Value
The GCI_OOP_TO_CHR macro returns the C character value that corresponds to the GemStone object. In case of error, it returns zero.
See Also
GciOopToFlt
Convert a SmallDouble, Float, or SmallFloat object to a C double.
Return Value
Returns the C double precision value that corresponds to the GemStone object. In case of any error other than HOST_ERR_INEXACT_PRECISION, this function returns a PlusQuietNaN.
Description
This function translates a GemStone Float object into the equivalent C double precision value.
If your C compiler’s floating point package doesn’t have a representation that corresponds to one of the values listed below, GciOopToFlt may generate the following errors when converting GemStone Float objects into C values:
HOST_ERR_INEXACT_PRECISION
when called to convert a number whose precision exceeds that of the C double type
HOST_ERR_MAGNITUDE_OUT_OF_RANGE
when called to convert a number whose exponent is too large (or small) to be held in a C double precision value
HOST_ERR_NO_PLUS_INFINITY
when called to convert a value of positive infinity
HOST_ERR_NO_MINUS_INFINITY
when called to convert a value of negative infinity
HOST_ERR_NO_PLUS_QUIET_NAN
when called to convert a positive quiet NaN
HOST_ERR_NO_MINUS_QUIET_NAN
when called to convert a negative quiet NaN
HOST_ERR_NO_PLUS_SIGNALING_NAN
when called to convert a positive signaling NaN
HOST_ERR_NO_MINUS_SIGNALING_NAN
when called to convert a negative signaling NaN
Example
double oopToFlt_example(OopType arg)
{
double d = GciOopToFlt(arg);
GciErrSType errInfo;
if (GciErr(&errInfo)) {
// argument was not a Float, SmallFloat or SmallDouble
printf(“error category “FMT_OID” number %d, %s\n”,
errInfo.category, errInfo.number, errInfo.message);
return 0.0 ;
}
return d;
}
See Also
GciOopToI32_
Convert a GemStone object to a C 32-bit integer value.
Arguments
|
TRUE if theObject does not fit in the result type or is not an Integer, otherwise unchanged. |
Return Value
The GciOopToI32 and GciOopToI32_ functions return the C 32-bit integer value that is equivalent to the value of theObject.
Description
The GciOopToI32 and GciOopToI32_ functions translate a GemStone object into the equivalent C 32-bit integer value. The GemStone object must be a SmallInteger within the range of C integers.
Otherwise, GciOopToI32 generates an error; GciOopToI32_ does not generate an error, but places a boolean in the error argument.
See Also
GciOopToI64_
Convert a GemStone object to a C 64-bit integer value.
Arguments
|
TRUE if theObject does not fit in the result type or is not an Integer, otherwise unchanged. |
Return Value
The GciOopToI64 and GciOopToI64_ functions return the C int64_t value that is equivalent to the value of theObject.
Description
The GciOopToI64 and GciOopToI64_ functions translate a GemStone object into the equivalent C 64-bit integer value.
The object identified by theObject must be a SmallInteger or a LargeInteger. If the object is not one of these kinds, GciOopToI64 generates an error; GciOopToI64_ places a boolean in the argument error.
See Also
GciPerform
Send a message to a GemStone object.
Syntax
OopType GciPerform(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs );
Arguments
Return Value
Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.
Description
This function sends a message (that is, the selector along with any keyword arguments and their corresponding values) to the specified receiver (an object in the GemStone database). Because GciPerform calls the virtual machine, you can issue a soft break while this function is executing. For more information, see Interrupting GemStone Execution.
Example
BoolType perform_example()
{
GciErrSType errInfo;
OopType userGlobals = GciResolveSymbol("UserGlobals", OOP_NIL);
OopType argList[2];
argList[0] = GciNewSymbol("myNumber");
argList[1] = GciI32ToOop(55);
OopType result = GciPerform(userGlobals, "at:put:", argList, 2);
if (result == OOP_NIL) {
if (GciErr(&errInfo)) {
printf("GciPerform failed; error %d, %s\n", errInfo.number, errInfo.message);
return false;
}
}
BoolType err = false;
int64 val = GciOopToI64_(result, &err);
if (err) {
printf("GciOopToI64 failed\n");
return false;
}
return (val = 55);
}
GciPerformFetchBytes
Send a message to a GemStone object, returning byte results.
Syntax
OopType GciPerformFetchBytes(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
ByteType * result,
ssize_t maxResultSize);
Arguments
Return Value
Returns number of bytes returned in *result, or -1 if an error is available to be fetched with GciErr.
Description
This function sends a message (that is, the selector along with any keyword arguments and their corresponding values) to the specified receiver (an object in the GemStone database), and puts the result, which should be a byte format object, in the *result buffer.
Because GciPerformFetchBytes calls the virtual machine, you can issue a soft break while this function is executing.
GciPerformNoDebug
Send a message to a GemStone object, and temporarily disable debugging.
Syntax
OopType GciPerformNoDebug(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
int flags );
Arguments
Return Value
Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.
Description
This function is a variant of GciPerform that is identical to it except for just one difference. GciPerformNoDebug disables any breakpoints and single step points that currently exist in GemStone while the message is executing. This feature is typically used while implementing a Smalltalk debugger.
Values for flags are described in gcicmn.ht,and can include:
- 0 (default) disables the debugger during execution.
- GCI_PERFORM_FLAG_ENABLE_DEBUG = 1 allows debugging, making this function behave like GciPerform.
- GCI_PERFORM_FLAG_DISABLE_ASYNC_EVENTS = 2 disables asynchronous events.
- GCI_PERFORM_FLAG_SINGLE_STEP = 3 places a single-step breakpoint at the start of the method to be performed, and then executes to hit that breakpoint.
GciPerformSymDbg
Send a message to a GemStone object, using a String object as a selector.
Syntax
OopType GciPerformSymDbg(
OopType receiver,
OopType selector,
const OopType args[ ],
int numArgs,
int flags );
Arguments
Return Value
Returns the OOP of the result of Smalltalk execution. In case of error, this function returns OOP_NIL.
Description
If the isNoDebug flag is FALSE, this function is a variant of GciPerform; if the flag is TRUE, this function is a variant of GciPerformNoDebug. In either case, its operation is identical to the other function. The difference is that GciPerformSymDbg takes an OOP as its selector instead of a C string.
See Also
GciPerformTrav
First send a message to a GemStone object, then traverse the result of the message.
Syntax
BoolType GciPerformTrav(
OopType receiver,
const char * selector,
const OopType * args,
int numArgs,
GciClampedTravArgsSType * travArgs );
Arguments
|
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. |
Return Value
Returns TRUE if the result is complete and no errors occurred. Returns FALSE if the traversal is not yet completed. You can then call GciMoreTraversal to proceed, if there is no GciError.
GciPerformTraverse
First send a message to a GemStone object, then traverse the result of the message.
Syntax
BoolType GciPerformTraverse(
OopType receiver,
const char selector[ ],
const OopType args[ ],
int numArgs,
GciTravBufType * travBuff,
int level );
Arguments
Return Value
Returns FALSE if the traversal is not yet completed, but further traversal would cause the travBuffSize to be exceeded. If the travBuffSize is reached before the traversal is complete, you can then call GciMoreTraversal to proceed from the point where travBuffSize was exceeded.
Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal.
Description
This function does a perform, then traverses the result of the perform.
GciPerformTraverse provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.
Example
The following two functions are equivalent:
BoolType performTraverse_example1(void)
{
OopType receiver = GciResolveSymbol("AllUsers", OOP_NIL);
OopType arg = GciI32ToOop(1);
GciTravBufType *buf = GciAllocTravBuf(80000);
BoolType atEnd = GciPerformTraverse(receiver, "at:", &arg, 1, buf, 2);
return atEnd;
}
BoolType performTraverse_example2(void)
{
OopType receiver = GciResolveSymbol("AllUsers", OOP_NIL);
OopType arg = GciI32ToOop(1);
OopType obj = GciPerform(receiver, "at:", &arg, 1);
GciTravBufType *buf = GciAllocTravBuf(80000);
BoolType atEnd = GciTraverseObjs(&obj, 1, buf, 2);
return atEnd;
}
GciPointerToByteArray
Given a C pointer, return a SmallInteger or ByteArray containing the value of the pointer.
Return Value
Returns a GemStone SmallInteger or ByteArray containing the value of the pointer.
If the argument is a 64-bit pointer aligned on an 8-byte boundary, or is a 32-bit pointer, the result is a SmallInteger. Otherwise, the result is a ByteArray.
See Also
GciPollForSignal
Poll GemStone for signal errors without executing any Smalltalk methods.
Return Value
This function returns TRUE if a signal error or an asynchronous error exists, and FALSE otherwise.
Description
GemStone permits selective response to signal errors: RT_ERR_SIGNAL_ABORT, RT_ERR_SIGNAL_COMMIT, and RT_ERR_SIGNAL_GEMSTONE_SESSION. The default condition is to leave them all invisible. GemStone responds to each single kind of signal error only after an associated method of class System has been executed: enableSignaledAbortError, enableSignaledObjectsError, and enableSignaledGemStoneSessionError respectively.
After GciInit executes successfully, the GemBuilder default condition also leaves all signal errors invisible. The GciPollForSignal function permits GemBuilder to check signal errors manually. However, GemStone must respond to each kind of error in order for GemBuilder to respond to it. Thus, if an application calls GciPollForSignal, then GemBuilder can check exactly the same kinds of signal errors as GemStone responds to. If GemStone has not executed any of the appropriate System methods, then this call has no effect until it does.
GemBuilder treats any signal errors that it finds just like any other errors, through GciErr or the GciLongJmp mechanism, as appropriate. Instead of checking manually, these errors can be checked automatically by calling the GciEnableSignaledErrors function.
GciPollForSignal also detects any asynchronous errors whenever they occur, including but not limited to the following errors: ABORT_ERR_LOST_OT_ROOT, GS_ERR_SHRPC_CONNECTION_FAILURE, GS_ERR_STN_NET_LOST, GS_ERR_STN_SHUTDOWN, and GS_ERR_SESSION_SHUTDOWN.
See Also
GciPollSocketForRead
GciPopErrJump
Discard a previously saved error jump buffer.
Arguments
|
A pointer to a jump buffer specified in an earlier call to GciPushErrJump. |
Description
This function discards one or more jump buffers that were saved with earlier calls to GciPushErrJump. Your program must call this function when a saved execution environment is no longer useful for error handling.
GemBuilder maintains a stack of error jump buffers. After your program calls GciPopErrJump, the jump buffer at the top of the stack will be used for subsequent GemBuilder error handling. If no jump buffers remain, your program will need to call GciErr and test for errors locally.
To pop multiple jump buffers in a single call to GciPopErrJump, specify the jumpBuffer argument from an earlier call to GciPushErrJump. See the following example.
Example
void popErr_example(void)
{
GciJmpBufSType jumpBuff1, jumpBuff2, jumpBuff3, jumpBuff4;
GciPushErrJump(&jumpBuff1);
GciPushErrJump(&jumpBuff2);
GciPushErrJump(&jumpBuff3);
GciPushErrJump(&jumpBuff4);
GciPopErrJump(&jumpBuff1); /* pops buffers 1-4 */
}
See Also
GciProcessDeferredUpdates_
Process deferred updates to objects that do not allow direct structural update.
Description
This function processes updates to instances of classes that have the noStructuralUpdate bit set, including AbstractDictionary, Bag, Set, and their subclasses. After operations that modify an instance of once of these classes, either GciProcessDeferredUpdates_ must be called, or the final GciStoreTrav must have GCI_STORE_TRAV_FINISH_UPDATES set.
The following GemBuilder calls operate on instances whose classes have noStructuralUpdate set: GciCreateOopObj, GciStoreTrav, GciStore...Oops, GciAdd...Oops, GciReplace...Oops. Behavior of other GemBuilder update calls on such instances is undefined.
An attempt to commit automatically executes a deferred update.
Executing a deferred update before all forward references are resolved can produce errors that require the application to recover by doing a GciAbort or GciLogout.
An OOP buffer used to update the varying portion of an object with noStructuralUpdate must contain the OOPs to be added to the varying portion of the object, with two exceptions:
See Also
GciProduct
Return an 8-bit unsigned integer that indicates the GemStone/S product.
Return Value
Returns an 8-bit unsigned integer indicating the GemStone/S product to which the client library belongs. This will always return 3 in GemStone/S 64 Bit.
Description
GciProduct allows a GemBuilder client to determine which GemStone/S product it is talking to. Combined with GciVersion, it allows the client to adapt to differences between GemBuilder features across different products and versions.
Currently-defined integers are:
1 — 32-bit GemStone/S
2 — GemStone/S 2G (discontinued product)
3 — GemStone/S 64 Bit
Any future products in the GemStone/S line will be assigned integers beginning with 4.
The integer zero is reserved, and will never be assigned to any product.
See Also
GciPushErrJump
Associate GemBuilder error handling with a jump buffer by pushing a jump buffer onto the stack.
Arguments
|
A pointer to a jump buffer, as described below. The jumpBuffer must have been initialized by passing it as the argument to the macro Gci_SETJMP. |
Description
Associate GemBuilder error handling with a jump buffer by pushing a jump buffer onto the stack.
This function allows your application program to take advantage of the setjmp/longjmp style of error-handling mechanism from within any GemBuilder function call. However, you cannot use this mechanism to handle errors within GciPushErrJump itself, or within the related functions GciPopErrJump and GciSetErrJump.
Rather than using setjmp and longjmp directly, this style of error handling in GemBuilder requires you to use Gci_SETJMP and GciLongJmp.
When your program calls Gci_SETJMP, the context of the C environment is saved in a jump buffer that you designate. To associate subsequent GemBuilder error handling with that jump buffer, you would then call GciPushErrJump.
GemBuilder maintains a stack of up to 20 error jump buffers. A buffer is pushed onto the stack when GciPushErrJump is called, and popped when GciPopErrJump is called. When an error occurs during a GemBuilder call, the GemBuilder implementation calls GciLongJmp using the buffer currently at the top of GemBuilder’s error jump stack, and pops that buffer from the stack.
For functions with local error recovery, your program can call GciSetErrJump to temporarily disable the GciLongJmp mechanism (and to re-enable it afterwards).
Whenever the jump stack is empty, the application must use GciErr to poll for GBC errors.
Example
For an example of how GciPushErrJump is used, see GciPopErrJump.
See Also
GciRaiseException
Signal an error, synchronously, within a user action.
Description
When executed from within a user action, this function raises an exception and passes the given error to the error signaling mechanism, causing control to return to Smalltalk. In order to signal an error on the Smalltalk client, this function must be invoked.
This function has no effect when executed outside of a user action.
GciReadSharedCounter
Lock and fetch the value of a shared counter.
Return Value
Returns a C Boolean value indicating whether the value was successfully read. Returns TRUE if successful, FALSE if an error occurred.
GciReadSharedCounterNoLock
Fetch the value of a shared counter without locking it.
Return Value
Returns a C Boolean value indicating whether the value was successfully read. Returns TRUE if successful, FALSE if an error occurred.
GciReleaseAllGlobalOops
Remove all OOPS from the PureExportSet, making these objects eligible for garbage collection.
Description
The GciReleaseAllGlobalOops function removes all OOPs from the PureExportSet, thus permitting GemStone to consider removing them as a result of garbage collection. Objects that are referenced from persistent objects are not removed during garbage collection, even if they are not in PureExportSet. If invoked from a user action, this function does not affect the user action’s export set.
GciReleaseAllGlobalOops is similar to GciReleaseAllOops, with the exception that OOPs are removed from the PureExportSet regardless of whether it is called from within a user action or not.
The GciSaveGlobalObjs or GciSaveGlobalObjs functions may be used to make objects ineligible for garbage collection. Note that results of the GciNew..., GciCreate..., GciPerform..., and GciExecute... functions are automatically added to the PureExportSet. You must release those objects explicitly if they are to be eligible for garbage collection.
CAUTION
Before releasing all objects, be sure that you will not need any of them again.
GciReleaseAllOops
Remove all OOPS from the PureExportSet, or if in a user action, from the user action’s export set, making these objects eligible for garbage collection.
Description
The GciReleaseAllOops function removes all OOPs from the applicable export set, thus permitting GemStone to consider removing them as a result of garbage collection. If called from within a user action, GciReleaseAllOops releases only those objects that have been saved since the beginning of the user action and are therefore in the user action’s export set. If not called from within a user action, GciReleaseAllOops removes all OOPs from the PureExportSet. To remove all objects from the PureExportSet, regardless of user action context, use GciReleaseAllGlobalOops.
Objects that are referenced by persistent objects are not removed during garbage collection, even if they are not in an export set. It is typical usage to call GciReleaseAllOops after successfully committing a transaction.
The GciSaveObjs or GciSaveGlobalObjs functions may be used to make objects ineligible for garbage collection. Note that results of the GciNew..., GciCreate..., GciPerform..., and GciExecute... functions are automatically ineligible. You must release those objects explicitly if they are to be eligible.
CAUTION
Before releasing all objects, be sure that you will not need any of them again.
GciReleaseAllTrackedOops
Clear the GciTrackedObjs set, making all tracked OOPs eligible for garbage collection.
Description
The GciReleaseAllTrackedOops function removes all OOPs from the user session’s GciTrackedObjs set, thus making them eligible to be garbage collected. This function does not affect the export sets; objects that are also in an export set will remain protected from garbage collection.
CAUTION
Before releasing any of your objects, be sure that you will not need them again.
GciReleaseGlobalOops
Remove an array of GemStone OOPs from the PureExportSet, making them eligible for garbage collection.
Description
The GciReleaseGlobalOops function removes the specified OOPs from the PureExportSet, thus making them eligible to be garbage collected.
This function differs from GciReleaseOops in that it operates the same if invoked from within a user action or not.
The GciSaveObjs or GciSaveGlobalObjs functions may be used to make objects ineligible for garbage collection. Note that results of the GciNew..., GciCreate..., GciPerform..., and GciExecute... functions are automatically ineligible. You must release those objects explicitly if they are to be eligible.
CAUTION
Before releasing any of your objects, be sure that you will not need them again.
GciReleaseOops
Remove an array of GemStone OOPs from the PureExportSet, or if in a user action, remove them from the user action’s export set, making them eligible for garbage collection.
Description
The GciReleaseOops function removes the specified OOPs from the applicable export set, thus making them eligible to be garbage collected. If invoked from within a user action, the specified OOPs are removed from the user action’s export set, otherwise the OOPs are removed from the PureExportSet.
To remove OOPs from the PureExportSet, regardless of user action context, use GciReleaseGlobalOops.
The GciSaveObjs or GciSaveGlobalObjs functions may be used to make objects ineligible for garbage collection. Note that results of the GciNew..., GciCreate..., GciPerform..., and GciExecute... functions are automatically ineligible. You must release those objects explicitly if they are to be eligible.
CAUTION
Before releasing any of your objects, be sure that you have other references, or will not need them again.
Example
void releaseOops_example(void)
{
OopType oArray = GciExecuteStr("UserGlobals at: #myArray put: (Array new: 5)", OOP_NIL);
OopType ivs[3];
ivs[0] = GciNewString("This is a string");
ivs[1] = GciI32ToOop(5699); // a SmallInteger; don't need to release
ivs[2] = GciFltToOop(9.0e6); // a Float or SmallDouble
GciStoreOops(oArray, 1, ivs, 3);
// release newly created objects,so that if oArray is removed from
// UserGlobals by other application code, these new objects can
// be garbage collected.
OopType releaseBuf[3];
releaseBuf[0] = ivs[0]; // a String
releaseBuf[1] = ivs[2]; // might be a Float
releaseBuf[2] = oArray; // the array instance
GciReleaseOops(releaseBuf, 3);
GciErrSType err;
if (GciErr(&err)) {
printf("Error %d, %s\n", err.number, err.message); }
}
GciReleaseTrackedOops
Remove an array of OOPs from the GciTrackedObjs set, making them eligible for garbage collection.
Description
The GciReleaseTrackedOops function removes the specified OOPs from the user session’s GciTrackedObjs set, thus making them eligible to be garbage collected. This function does not affect the export sets; objects that also appear in an export set will remain protected from garbage collection.
CAUTION
Before releasing any of your objects, be sure that you will not need them again.
GciRemoveOopFromNsc
Arguments
Return Value
Returns FALSE if theOop was not present in the NSC. Returns TRUE if theOop was present.
Description
This function removes an OOP from the unordered variables of an NSC, using structural access.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
BoolType removeOopFromNsc_example(void)
{
OopType anAccount = GciExecuteStr("AllAccounts detect: [:ea | ea id=1073", OOP_NIL);
OopType aColl = GciResolveSymbol("AllAccounts", OOP_NIL);
BoolType wasPresent = GciRemoveOopFromNsc(aColl, anAccount);
/* release because it is the result from an execute */
GciReleaseOops(&anAccount, 1);
return wasPresent;
}
GciRemoveOopsFromNsc
Remove one or more OOPs from an NSC.
Arguments
Return Value
Returns FALSE if any element of theOops was not present in the NSC. Returns TRUE if all elements of theOops were present in the NSC.
Description
This function removes multiple OOPs from the unordered variables of an NSC, using structural access. If any individual OOP is not present in the NSC, this function returns FALSE, but it still removes all OOPs that it finds in the NSC.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
BoolType removeOopsFromNsc_example(void)
{
OopType subColl = GciExecuteStr(
"AllAccounts select:[ea|ea id > 2000 ]", OOP_NIL);
OopType buf[10];
int numRet = GciFetchVaryingOops(subColl, 1, buf, 10);
/* buf contains at most 10 accounts with ids > 2000 */
OopType aColl = GciResolveSymbol("AllAccounts", OOP_NIL);
BoolType allPresent = GciRemoveOopsFromNsc(aColl, buf, numRet);
/* release because it is the result from an execute */
GciReleaseOops(&subColl, 1);
return allPresent;
}
GciReplaceOops
Replace all instance variables in a GemStone object.
Arguments
Description
GciReplaceOops uses structural access to replace all the instance variables in the object. However, it does so in a context that is external to the object. Hence, it completely ignores private named instance variables in its operation.
If theObj is of fixed size, then it is an error for numOops to be of a different size. If theObj is of a variable size, then it is an error for numOops to be of a size smaller than the number of named instance variables (namedSize) of the object. For variable-sized objects, GciReplaceOops resets the number of unnamed variables to numOops - namedSize.
GciReplaceOops is not recommended for use with variable-sized objects unless they are indexable or are NSCs. Other variable-sized objects, such as KeyValue dictionaries, do not store values at fixed offsets.
GciReplaceVaryingOops
GciResolveSymbol
Find the OOP of the object to which a symbol name refers, in the context of the current session’s user profile.
Arguments
|
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). |
Description
Attempts to resolve the symbol name cString using symbol list symbolList. If symbolList is OOP_NIL, this function searches the symbol list in the user’s UserProfile. If the symbol is not found or an error is generated, the result is OOP_ILLEGAL. If result is OOP_ILLEGAL and GciErr reports no error, then the symbol could not be resolved using the given symbolList. If an error such as an authorization error occurs, the result is OOP_ILLEGAL and the error is accessible by GciErr.
This function is similar to GciResolveSymbolObj, except that the symbol argument is a C string instead of an object identifier.
See Also
GciResolveSymbolObj
Find the OOP of the Symbol to which a String object refers, in the context of the current session’s user profile.
Arguments
|
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). |
Description
Attempts to resolve aStringObj using symbol list symbolList. If symbolList is OOP_NIL, this function searches the symbol list in the user’s UserProfile. If the symbol is not found or an error is generated, the result is OOP_ILLEGAL. If the result is OOP_ILLEGAL and GciErr reports no error, then the symbol could not be resolved using the given symbolList. If an error such as an authorization error occurs, the result is OOP_ILLEGAL and the error is accessible by GciErr.
This function is similar to GciResolveSymbol, except that the symbol argument is an object identifier for a String instead of a C string.
See Also
GciRtlIsLoaded
Report whether a GemBuilder library is loaded.
Description
The GciRtlIsLoaded function reports whether an executable has loaded one of the versions of GemBuilder. The GemBuilder library files are dynamically loaded at run time. See The GemBuilder for C Shared Libraries for more information.
See Also
GciRtlLoad
Return Value
Returns TRUE if a GemBuilder library loads successfully. If the load fails, the return value is FALSE, and a null-terminated error message is stored in errBuf, unless errBuf is NULL.
Description
The GciRtlLoad function attempts to load one of the GemBuilder libraries. If useRpc is TRUE, the RPC version of GemBuilder is loaded. If useRpc is FALSE, the linked version of GemBuilder is loaded. See The GemBuilder for C Shared Libraries for more information.
If path is not NULL, it must point to a list of directories to search for the library to load. If path is NULL, then a default path is searched: the appropriate subdirectory of $GEMSTONE, depending on the platform and if it is 32-bit or 64-bit.
Example
void load_library(void)
{
char errBuf[1024];
BoolType result = GciRtlLoad(true, "$GEMSTONE/lib", errBuf, sizeof(errBuf));
if (result == FALSE)
printf("Library load failed, %s\n", errBuf);
}
See Also
GciRtlUnload
Description
The GciRtlUnload function causes the library loaded by GciRtlLoad to be unloaded. Once the current library is unloaded, GciRtlLoad can be called again to load a different GemBuilder library. See The GemBuilder for C Shared Libraries for more information.
See Also
GciSaveAndTrackObjs
Add objects to GemStone’s internal GciTrackedObjs set to prevent them from being garbage collected.
Description
The GciSaveAndTrackOops function adds the specified OOPS to GemStone’s GciTrackedObjs set. This prevents the GemStone garbage collector from causing the objects to disappear during a session if they become unreferenced, and enables changes to these objects to show up in the TrackedDirtyObjs set.
This function does not cause the objects to be referenced from a permanent object; there is no guarantee that they will be saved to disk at commit.
The results of GciNew..., GciCreate..., GciSend..., GciPerform..., and GciExecute... calls are automatically added to the export set, which also prevents them from being garbage collected.
This function may only be called after GciTrackedObjsInit has been executed.
You can use GciReleaseTrackedOops or GciReleaseAllTrackedOops calls to cancel the effect of a GciSaveAndTrackOops call, thereby making objects eligible for garbage collection. Objects that have been added to the GciTrackedObjs set and have been modified can be retrieved using GciTrackedDirtyObjs, GciDirtySaveObjs, or GciTrackedObjsFetchAllDirty.
GciSaveGlobalObjs
Add an array of OOPs to the PureExportSet, making them ineligible for garbage collection.
Description
The GciSaveGlobalObjs function places the specified OOPs in the PureExportSet, thus preventing GemStone from removing them as a result of garbage collection. GciSaveGlobalObjs can add any OOP to the PureExportSet. It differs from GciSaveObjs in that OOPs are placed in the PureExportSet regardless of user action context.
The GciSaveGlobalObjs function does not itself make objects persistent, and it does not create a reference to them from a persistent object so that the next commit operation will try to do so either. It only protects them from garbage collection.
Note that results of the GciNew..., GciCreate..., GciPerform..., GciExecute..., and GciResolve... functions are automatically added to the export set. The GciRelease... functions may be used to make objects eligible for garbage collection.
GciSaveObjs
Add an array of OOPs to the PureExportSet, or if in a user action to the user action’s export set, making them ineligible for garbage collection.
Description
The GciSaveObjs function places the specified OOPs in the applicable export set, thus preventing GemStone from removing them as a result of garbage collection. If invoked from within a user action, the OOPs are added to the user action’s export set; otherwise the OOPs are added to the PureExportSet. To add OOPS to the PureExportSet, regardless of the user action context, use GciSaveGlobalObjs. GciSaveObjs can add any OOP to the export set.
The GciSaveObjs function does not itself make objects persistent, and it does not create a reference to them from a persistent object so that the next commit operation will try to do so either. It only protects them from garbage collection.
Note that results of the GciNew..., GciCreate..., GciPerform..., GciExecute..., and GciResolve... functions are automatically added to the export set. The GciRelease... functions may be used to make objects eligible for garbage collection.
GciServerIsBigEndian
GciSessionIsRemote
Determine whether or not the current session is using a Gem on another machine.
Return Value
Returns TRUE if the current GemBuilder session is connected to a remote Gem. It returns FALSE if the current GemBuilder session is connected to a linked Gem.
GciSessionIsRemote raises an error if the current session is invalid.
GciSetErrJump
Enable or disable the current error handler.
Arguments
|
TRUE enables error jumps to the execution environment saved by the most recent GciPushErrJump; FALSE disables error jumps. |
Return Value
Returns TRUE if error handling was previously enabled for the jump buffer at the top of the error jump stack. Returns FALSE if error handling was previously disabled. If your program has no buffers saved in its error jump stack, this function returns FALSE. (This function cannot generate an error.)
For most GemBuilder functions, calling GciErr after a successful function call will return zero (that is, false). In such cases, the GciErrSType error report structure will contain some default values. (See GciErr for details.) However, a successful call to GciSetErrJump does not alter any previously existing error report information. That is, calling GciErr after a successful call to GciSetErrJump will return the same error information that was present before this function was called.
Description
This function enables or disables the error handler at the top of GemBuilder’s error jump stack.
Example
void setErrJump_example(void)
{
GciJmpBufSType jumpBuf1;
GciPushErrJump(&jumpBuf1);
if (Gci_SETJMP(&jumpBuf1)) {
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("LONGJMP, error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
} else {
printf("GCI longjmp, but no error found\n"); // should not happen
}
GciPopErrJump(&jumpBuf1);
return;
}
BoolType prevVal = GciSetErrJump(FALSE); // disable error jumps
printf("error jumps previously %s\n", prevVal ? "enabled" : "disabled");
OopType oRcvr = GciI32ToOop(3);
GciPerform(oRcvr, "frob", NULL, 0); // expect does-not-understand error
GciErrSType errInfo;
if (GciErr(&errInfo)) {
printf("error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
} else {
printf("expected error but found none\n");
}
GciSetErrJump(TRUE);
GciPerform(oRcvr, "frob", NULL, 0); // expect a longjmp
printf("GCI longjmp did not happen\n"); // should not reach here
}
GciSetHaltOnError
Halt the current session when a specified error occurs.
Description
The GciSetHaltOnError function causes the current session to halt for internal debugging when the specified GemBuilder error occurs.
To unset after a previous call to GciSetHaltOnError, invoke this function with an errNum of zero.
See Also
Gci_SETJMP
(MACRO) Save a jump buffer in GemBuilder’s error jump stack.
GciSetNet
Set network parameters for connecting the user to the Gem and Stone processes.
Syntax
void GciSetNet(
const char stoneNameNrs[ ],
const char HostUserId[ ],
const char HostPassword[ ],
const char gemServiceNrs[ ] );
Arguments
Description
Your application, your GemStone session (Gem), and the database monitor (Stone) can all run in separate processes, on separate machines in your network. GciSetNet specifies the network parameters that are used to connect the current user to GemStone on the host, whenever GciLogin is called. Network resource strings specify the information needed to establish communications between these processes . See the System Administration Guide for GemStone/S 64 Bit for complete information on NRS Syntax and the network environment.
stoneNameNrs identifies the name and network location of the database monitor process (Stone), which is the final arbiter of all sessions that access a specific database.
A Stone process called “gs64stone” on node “lichen” could be described in a network resource string as:
!@lichen!gs64stone
A Stone of the same name that is running on the same machine as the application could be described in shortened form simply as:
gs64stone
gemServiceNrs identifies the name and network location of the GemStone service that creates a session process (Gem), which then arbitrates data access between the database and the application. Every GemStone session requires a Gem. In linked applications, one Gem is present within the same process as the application; in remote applications the Gem is a separate process specific to that login session. Each time an application user logs in to GemStone (after the first time in linked applications), the GemStone service must create a new Gem. gemServiceNrs is required except in the special case of a linked application that limits itself to one GemStone login per application process. In this special case, specify gemServiceNrs as an empty string.
For most installations, the GemStone service name is gemnetobject. Specify, for example:
!@lichen!gemnetobject
HostUserId and HostPassword are your login name and password, respectively, on the machines that host the Gem and Stone processes. Do not confuse these values with your GemStone username and password - the GemStone username and password will be provided as arguments to GciLogin. HostUserId and HostPassword provide authentication for such tasks as creating a Gem and establishing communications with a Stone, and are optional in some configuration. When such authentication is required, an application user cannot login to GemStone until the host login is verified for the machine running the Stone or Gem, in addition to the GemStone login itself.
Authentication is always required if the NetLDI process that is related to the Stone is running in secure mode. In this case, it makes no difference whether the application is linked or remote. Authentication is also required to create a remote Gem, unless the NetLDI process is running in guest mode.
If the HostUserId argument is set to an empty C string or a NULL pointer, GemBuilder will try to find a username and password for authentication on a host machine in your network initialization file. To prevent GemBuilder from looking for authentication information in the network initialization file, supply a valid non-empty C string for the HostUserId argument, and a non-empty string for the HostPassword argument to provide a password. An empty string and a NULL pointer both mean that no password will be used for authentication.
Example
For an example of how GciSetNet is used, see the example for GciLogin.
See Also
GciSetNetEx_
Set network parameters for connecting the user to the Gem and Stone processes, allowing encryption.
Syntax
void GciSetNetEx(
const char stoneNameNrs[ ],
const char hostUserId[ ],
const char hostPassword[ ],
const char gemServiceNrs[ ] ,
BoolType hostPasswordIsEncrypted);
BoolType GciSetNetEx_(
const char StoneNameNrs[ ],
const char hostUserId[ ],
const char hostPassword[ ],
const char gemServiceNrs[ ] ,
BoolType hostPasswordIsEncrypted,
char * errString,
size_t maxErrSize);
Arguments
Return Value
GciSetNetEx has no return value. GciSetNetEx_ returns TRUE if the network parameters were set correctly, FALSE if there was a syntax error in stoneNameNrs or gemServiceNrs.
Description
This function is similar to GciSetNet, but allows specifying additional behavior. For details on how to specify the StoneName and GemService using NRS, and the requirements for HostUserId, HostPassword, see GciSetNet.
GciSetNetEx allows you to specify that the host password you send is encrypted. The host password may be encrypted using GciEncrypt. To encrypt the GemStone password, use GciLoginEx and specify the associated login flag.
Example
For an example of how GciSetNet is used, see GciLogin.
See Also
GciSetSessionId
Set an active session to be the current one.
Description
This function can be used to switch between multiple GemStone sessions in an application program with multiple logins.
See Also
GciSetSharedCounter
Set the value of a shared counter.
Arguments
|
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. |
Return Value
Returns a C Boolean value indicating whether the value was successfully changed. Returns TRUE if the modification succeeded, FALSE if it failed.
GciSetTraversalBufSwizzling
Control swizzling of the traversal buffers.
Arguments
Return Value
Returns the previous value of swizzling of traversal buffers. When called on a linkable session, returns FALSE and has no effect. If the current session is invalid, generates an error and returns FALSE.
Description
GciSetTraversalBufSwizzling controls swizzling of the traversal buffers used by these calls in an RPC session:
GciStoreTrav, GciNbStoreTrav
GciStoreTravDo_, GciNbStoreTravDo_
GciStoreTravDoTrav_, GciNbStoreTravDoTrav_
GciClampedTrav, GciNbClampedTrav
GciMoreTraversal, GciNbMoreTraversal
GciPerformTrav, GciNbPerformTrav
GciExecuteStrTrav, GciNbExecuteStrTrav
For more information on swizzling, see Byte-Swizzling of Binary Floating-Point Values.
GciSetVaryingSize
Arguments
Description
GciSetVaryingSize changes the size of a collection, adding nils to grow it, or truncating it, as necessary. It is equivalent to the Smalltalk method Object >> size:. It does not change the number of any named instance variables.
Example
void setVaryingSize_example(void)
{
OopType oArr = GciNewOop(OOP_CLASS_ARRAY); // create new Array of size 0
GciSetVaryingSize(oArr, 1000000);
// logical size now 1 million
GciStoreOop(oArr, 500000, GciI32ToOop(5678));
}
See Also
GciShutdown
Logout from all sessions and deactivate GemBuilder.
Description
This function is intended to be called by image exit routines, such as the on_exit system call. In the linkable GemBuilder, GciShutdown calls GciLogout. In the RPC version, it logs out all sessions connected to the Gem process and shuts down the networking layer, thus releasing all memory allocated by GemBuilder.
It is especially important to call this function explicitly on any computer whose operating system does not automatically deallocate resources when a process quits. This effect is found on certain small, single-user systems.
GciSoftBreak
Interrupt the execution of Smalltalk code, but permit it to be restarted.
Description
This function sends a soft break to the current user session (set by the last GciLogin or GciSetSessionId).
GemBuilder allows users of your application to terminate Smalltalk execution. This is useful, for example, if the a Smalltalk method is invoked that enters an infinite loop.
GciSoftBreak interrupts only the Smalltalk virtual machine (if it is running), and does so in such a way that the it can be restarted. The only GemBuilder functions that can recognize a soft break include GciSendMessage, GciPerform, and GciContinue, and the GciExecute... functions.
GciHardBreak has no effect if called from within a User Action.
In order for GemBuilder functions in your program to recognize interrupts, your program will need a signal handler that can call the functions GciSoftBreak and GciHardBreak. Since GemBuilder does not relinquish control to an application until it has finished its processing, soft and hard breaks must be initiated from another thread.
If GemStone is executing when it receives the break, it replies with the error message RT_ERR_SOFT_BREAK. Otherwise, it ignores the break.
Example
#include "signal.h"
extern "C" {
static void doSoftBreak(int sigNum, siginfo_t* info, void* ucArg)
{
GciSoftBreak();
}
}
void softBreakExample(void)
{
// save previous SIGINT handler and install ours
struct sigaction oldHandler;
struct sigaction newHandler;
newHandler.sa_handler = SIG_DFL;
newHandler.sa_sigaction = doSoftBreak;
newHandler.sa_flags = SA_SIGINFO | SA_RESTART ;
sigaction(SIGINT, &newHandler, &oldHandler);
// execute a loop that will take 120 seconds to execute and
// return the SmallInteger with value 11 .
OopType result = GciExecuteStr(
"| a | a := 1 . 10 timesRepeat:[ System sleep:10. a := a + 1]. ^ a",
OOP_NIL/*use default symbolList for execution*/);
BoolType done = FALSE;
int breakCount = 0;
do {
// assume the user may type ctl-C or issue kill -INT from
// another shell process during the 120 seconds .
GciErrSType errInfo;
if ( GciErr(&errInfo)) {
if (errInfo.number == RT_ERR_SOFT_BREAK) {
// GciExecuteStr was interrupted by a GciSoftBreak .
breakCount++ ;
// now continue the execution to finish the computation
result = GciContinue(errInfo.context);
} else {
// FMT_OID format string is defined in gci.ht
printf("unexpected error category "FMT_OID" number %d, %s\n",
errInfo.category, errInfo.number, errInfo.message);
// terminate the execution
GciClearStack(errInfo.context);
done = TRUE;
}
} else {
// GciExecuteStr or GciContinue completed without error
done = TRUE;
BoolType conversionErr = FALSE;
int val = GciOopToI32_(result, &conversionErr);
if (conversionErr) {
printf("Error converting result to C int\n");
} else {
printf("Got %d interrupts, result = %d\n", breakCount, val);
}
}
} while (! done);
// restore previous SIGINT handler
sigaction(SIGINT, &oldHandler, NULL);
}
See Also
GciStep_
Continue code execution in GemStone with specified single-step semantics.
Syntax
OopType GciStep(
OopType gsProcess,
int level );
OopType GciStep_(
OopType gsProcess,
int level
BoolType through);
Arguments
Return Value
Returns the OOP of the result of the Smalltalk execution. Returns OOP_ILLEGAL in case of error.
Description
This function continues code execution in GemStone using the specified single-step semantics. This function is intended for use by debuggers.
If you specify a level that is either less than zero or greater than the value represented by GciPerform(gsProcess, "stackDepth", NULL, 0), this function generates an error.
GciStoreByte
Store one byte in a byte object.
Description
This function stores a single element in a byte object at a specified index, using structural access.
GciStoreByte raises an error if theObject is a Float or SmallFloat. You must store all the bytes of a Float or SmallFloat if you store any.
Example
void storeByte_example(void)
{
OopType oString = GciNewOop(OOP_CLASS_STRING);
for (int j = 0; j < 200; j++) {
ByteType val = j;
GciStoreByte(oString, j + 1 , val );
}
}
See Also
GciStoreBytes
(MACRO) Store multiple bytes in a byte object.
Syntax
void GciStoreBytes(
OopType theObject,
int64 startIndex,
const ByteType theBytes[ ],
int64 numBytes );
Description
This macro uses structural access to store multiple elements from a C array in a byte object, beginning at a specified index. A common application of GciStoreBytes would be to store a text string. For an object with multiple bytes per character or digit, theBytes is expected to be in client native byte order, and will be swizzled if needed by the server.
Error Conditions
GciStoreBytes raises an error if theObject is a Float or SmallFloat. Use GciStoreBytesInstanceOf instead for Float or SmallFloat objects.
GciStoreBytesInstanceOf
Store multiple bytes in a byte object.
Syntax
void GciStoreBytesInstanceOf(
OopType theClass,
OopType theObject,
int64 startIndex,
const ByteType theBytes[ ],
int64 numBytes );
Description
This function uses structural access to store multiple elements from a C array into a byte object, beginning at a specified index. A common application of GciStoreBytesInstanceOf would be to store a Float or LargeInteger object.
GciStoreBytesInstanceOf provides automatic byte swizzling for objects such as Float, LargeInteger, and DoubleByteString that use multiple bytes per digit or character. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values. For these objects, theBytes is assumed to be in client native byte order. For DoubleByteStrings, startIndex must be aligned on character boundaries and numBytes must be a multiple of the number of bytes per character; for numeric objects startIndex must be one and the numBytes the size of the numeric class.
The presence of the argument theClass enables the swizzling to be implemented more efficiently. If theObject is a Float or SmallFloat, then theClass must match the actual class of theObject, startIndex must be one, and numBytes must be the actual size for theClass. If any of these conditions are not met, then GciStoreBytesInstanceOf raises an error as a safety check.
If theObject is not a Float or SmallFloat, then theClass is ignored. Hence, you must supply the correct class for theClass if theObject is a Float or SmallFloat, but you can use OOP_NIL otherwise.
GciStoreChars
Store multiple ASCII characters in a byte object.
Description
This function uses structural access to store a C string in a byte object, beginning at a specified index.
GciStoreChars raises an error if theObject is a Float or SmallFloat. ASCII characters have no meaning as bytes in a Float or SmallFloat object.
Example
void storeChars_example(void)
{
OopType oString = GciNewOop(OOP_CLASS_STRING);
GciStoreChars(oString, 1, "some string data");
}
See Also
GciStoreDynamicIv
Create or change the value of an object’s dynamic instance variable.
Arguments
Return Value
Creates or changes the value of the dynamic instance variable specified by aSymbol within theObject.
Description
This function stores a value into the dynamic instance variable specified by aSymbol.
Dynamic instance variables are not allowed in instances of ExecBlock, Behavior, GsNMethod, or special objects.
To delete a dynamic instance variable, pass OOP_REMOTE_NIL as the value.
See Also
GciStoreIdxOop
Store one OOP in an indexable pointer object’s unnamed instance variable.
Description
This function stores a single OOP into an indexed variable of a pointer object at the specified index, using structural access. Note that this function cannot be used for NSCs. (To add an OOP to an NSC, use GciAddOopToNsc.)
Example
void storeIdxOop_example(void)
{
GciErrSType err;
OopType oArray = GciExecuteStr("Array new: 5", OOP_NIL);
OopType oSet = GciExecuteStr("Set with: 'GBS/VA' with: 'GBS/VW'", OOP_NIL);
// store the Set into the 3rd slot of the Array
GciStoreIdxOop(oArray, 3, oSet);
// release results of execution
GciReleaseOops(&oArray, 1);
GciReleaseOops(&oSet, 1);
}
GciStoreIdxOops
Store one or more OOPs in an indexable pointer object’s unnamed instance variables.
Syntax
void GciStoreIdxOops(
OopType theObject,
int64 startIndex,
const OopType theOops[ ],
int numOops );
Description
This function uses structural access to store multiple OOPs from a C array into the indexed variables of a pointer object, beginning at the specified index. Note that this call cannot be used with NSCs. (To add multiple OOPs to an NSC, use GciAddOopsToNsc.)
Example
This example creates a new Array containing the first 10 elements of Globals.
BoolType storeIdxOops_example(void)
{
GciErrSType err;
OopType oArray = GciExecuteStr("Array new: 10", OOP_NIL);
OopType oGlobals = GciExecuteStr("Globals", OOP_NIL);
int buf_size = 10;
OopType oBuffer[buf_size];
// Fetch first 10 elements in Globals
int numRet = GciFetchVaryingOops(oGlobals, 1, oBuffer, buf_size);
// and put these in oArray
GciStoreIdxOops(oArray, 1, oBuffer, numRet);
if (GciErr(&err)) {
printf("Error %d, %s\n", err.number, err.message);
return false; }
// release results of execution
GciReleaseOops(&oArray, 1);
return true;
}
GciStoreNamedOop
Store one OOP into an object’s named instance variable.
Description
This function stores a single OOP into an object’s named instance variable at the specified index, using structural access.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
void storeNamedOop_example(OopType anAccount)
{
OopType newName = GciNewString("Josiah Chang");
// assign new value to instvar at a hardcoded offset
int indexOfSalesRep = 3;
GciStoreNamedOop(anAccount, indexOfSalesRep, newName);
// assign new value to instvar without knowing offset
GciStoreNamedOop(anAccount,
GciIvNameToIdx(GciFetchClass(anAccount), "salesRep"),
newName);
}
GciStoreNamedOops
Store one or more OOPs into an object’s named instance variables.
Syntax
void GciStoreNamedOops(
OopType theObject,
int64 startIndex,
const OopType theOops[ ],
int numOops );
Arguments
Description
This function uses structural access to store multiple OOPs from a C array into an object’s named instance variables, beginning at the specified index.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
void storeNamedOops_example(OopType anAddress)
{
// allocation buffer for unknown number of instvars
int namedSize = GciFetchNamedSize(anAddress);
if (namedSize == 0) { return ; }
OopType *oBuffer = (OopType*) malloc( sizeof(OopType) * namedSize );
if (oBuffer == NULL) { return; }
// fetch existing values
int numRet = GciFetchNamedOops(anAddress, 1, oBuffer, namedSize);
if (numRet != namedSize) {
printf("error during fetch\n");
return;
}
// update street and city, but not state
OopType newValue = GciNewString("4545 45th Str");
int ivOffset = GciIvNameToIdx(GciFetchClass(anAddress), "street");
oBuffer[ivOffset - 1 ] = newValue;
newValue = GciNewString("Tualatin");
ivOffset = GciIvNameToIdx(GciFetchClass(anAddress), "city");
oBuffer[ivOffset - 1 ] = newValue;
// store changes
GciStoreNamedOops(anAddress, 1, oBuffer, namedSize);
}
GciStoreOop
Store one OOP into an object’s instance variable.
Arguments
Description
This function stores a single OOP into an object at the specified index, using structural access. Note that this function cannot be used for NSCs. To add an object to an NSC, use GciAddOopToNsc.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
void storeOop_example(OopType anAccount)
{
// Two ways to assign new value to a named instance variable of anAccount
OopType newName = GciNewString("Jeni Johnson-Klien");
int indexOfSalesRep = 3;
GciStoreOop(anAccount, indexOfSalesRep, newName);
GciStoreNamedOop(anAccount, indexOfSalesRep, newName);
// Two ways to assign a product string to the first indexed instance variable
OopType newProduct = GciNewString("GemConnect");
GciStoreOop(anAccount, GciFetchNamedSize(anAccount) + 1, newProduct);
GciStoreIdxOop(anAccount, 1, newProduct);
}
GciStoreOops
Store one or more OOPs into an object’s instance variables.
Syntax
void GciStoreOops(
OopType theObject,
int64 startIndex,
const OopType theOops[ ],
int numOops );
Arguments
Description
This function uses structural access to store multiple OOPs from a C array into a pointer object, beginning at the specified index. Note that this call cannot be used with NSCs. To add multiple OOPs to an NSC, use GciAddOopsToNsc.
Example
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
void storeOops_example(OopType anAccount)
{
int namedSize = GciFetchNamedSize(anAccount);
int64 instSize = GciFetchSize_(anAccount);
// allow space in buffer for storing into first varying instVar plus
// appending a new varying instVar
int64 bufVaryingSize = instSize - namedSize + 1;
int64 bufSize = namedSize + bufVaryingSize;
OopType *buf = (OopType*) malloc(sizeof(OopType) * bufSize);
if (buf == NULL) {
printf("malloc failure");
return;
}
GciFetchOops(anAccount, 1, buf, instSize);
OopType newName = GciNewString("Josiah Chang");
int indexOfSalesRep = GciIvNameToIdx(GciFetchClass(anAccount), "salesRep");
buf[indexOfSalesRep - 1] = newName;
OopType firstProduct = GciNewString("GS64");
OopType newProduct = GciNewString("GemConnect");
// assign first element
buf[namedSize] = firstProduct;
// append new product
int64 newSize = instSize + 1;
buf[newSize - 1] = newProduct;
// now store all the instVars back to the repository
GciStoreOops(anAccount, 1, buf, newSize);
}
GciStorePaths
Store selected multiple OOPs into an object tree.
Syntax
BoolType GciStorePaths(
const OopType theOops[ ],
int numOops,
const int paths[ ],
const int pathSizes[ ],
int numPaths,
const OopType newValues[ ],
int * failCount );
Arguments
Return Value
Returns TRUE if all values were successfully stored. Returns FALSE if the store on any path fails for any reason.
Description
This function allows you to store multiple objects at selected positions in an object tree with a single GemBuilder call, exporting only the desired information to the database.
Each path in the paths array is itself an array of longs. Those longs are offsets that specify a path along which to store objects. In each path, a positive integer x refers to an offset within an object’s named instance variables, while a negative integer -x refers to an offset within an object’s indexed instance variables.
The newValues array contains (numOops * numPaths) elements, stored in the following order:
[0,0]..[0,numPaths-1]..[1,0]..[1,numPaths-1]..[numOops-1,0]..[numOops-1,numPaths-1]
The first element of this newValues array is stored along the first path into the first element of theOops. New values are then stored into the first element of theOops along each remaining element of the paths array. Similarly, new values are stored into each subsequent element of theOops, until all paths have been applied to all its elements.
The new value to be stored into object i along path j is thus represented as:
newValues[ ((i-1) * numPaths) + (j-1) ]
The expressions i-1 and j-1 are used because C has zero-based arrays.
If the store on any path fails for any reason, this function stops and generates a GemBuilder error. Any objects that were successfully stored before the error occurred will remain stored.
Example of a single object and a single path
See Executing the examples for the Smalltalk code that defines the classes and objects that support the examples.
This example updates the street address along one path for a single account.
BoolType storePaths_example1(OopType anAccount)
{
GciErrSType errInfo;
int path_size = 3;
int aPath[path_size];
aPath[0] = 2; //customer
aPath[1] = 2; //address
aPath[2] = 1; //street
// update anAccount.customer.address.street with the newValue
OopType newValue = GciNewString("312 North Rd");
int failCount;
GciStorePaths(&anAccount, 1, aPath, &path_size, 1, &newValue, &failCount);
if (failCount != 0) {
printf("GciStorePaths fail count is %d\n", failCount);
return false;
}
if (GciErr(&errInfo)) {
printf("GciStorePaths error %d, %s\n", errInfo.number, errInfo.message);
return false;
}
return true;
}
Example with multiple objects and multiple paths
This example updates several values along two paths for two Accounts.
BoolType storePaths_example2(int numOfAccounts, OopType* resultAccounts)
{
GciErrSType errInfo;
OopType myAccts;
myAccts = GciExecuteStr("AllAccounts", OOP_NIL);
if (myAccts == OOP_NIL) { return false; }
int numRet = GciFetchVaryingOops(myAccts, 1, resultAccounts, numOfAccounts);
if (numRet != numOfAccounts) { return false; }
int path_segments[2];
path_segments[0] = 2;
path_segments[1] = 3;
int serialPath[6]; // size is sum of path_segments
serialPath[0] = 2; //customer
serialPath[1] = 1; //name
serialPath[2] = 2; //customer
serialPath[3] = 2; //address
serialPath[4] = 2; //city
OopType newValues[2 * numOfAccounts];
// size of path_segments * number of accounts
newValues[0] = GciNewString("Samual B. Houston");
newValues[1] = GciNewString("Paisley");
newValues[2] = GciNewString("Maya J. Johnson");
newValues[3] = GciNewString("Bend");
int failCount;
GciStorePaths(resultAccounts, numOfAccounts, serialPath,
path_segments, 2, newValues, &failCount);
if (failCount != 0) {
printf("GciStorePaths fail count is %d\n", failCount);
return false;
}
if (GciErr(&errInfo)) {
printf("GciStorePaths error %d, %s\n", errInfo.number, errInfo.message);
return false;
}
return true;
}
See Also
GciStoreTrav
Store multiple traversal buffer values in objects.
Arguments
Description
This function stores data from the traversal buffer travBuff into multiple GemStone objects. A traversal buffer is a specialized C structure that optimizes transfer of data. GciStoreTrav, by providing a way to modify and create a number of new object in one command, allows you to reduce the number of GemBuilder calls that are required for your application program to store complex objects in the database.
The first element in the traversal buffer is an integer that indicates how many bytes are stored in the buffer. The remainder of the traversal buffer consists of a series of object reports. Each object report is a C structure of type GciObjRepSType. A GciObjRepSType includes a header with the OOP and class of the object, and a variable-length data area. GciStoreTrav stores data object by object, using one object report at a time.
GciStoreTrav can create new objects and store data into them, or it can modify existing objects with the data in their object reports, or a combination of the two. By default (GCI_STORE_TRAV_DEFAULT), it only modifies existing objects, and it raises an error if an object does not already exist. When GCI_STORE_TRAV_CREATE is used, it modifies any object that already exists and creates a new object when an object does not exist. The new object is initialized with the data in its object report.
To create a new object based on an object report, you need to provide the OOP of the object, using GciGetFreeOops.
When GciStoreTrav modifies an existing object of byte or pointer format, it replaces that object’s data with the data in its object report, regardless of behaviorFlag. All instance variables, named (if any) or indexed (if any), receive new values. Named instance variables for which values are not given in the object report are initialized to nil or to zero. Indexable objects may change in size; the object report determines the new number of indexed variables.
When an existing NSC is modified, it replaces all named instance variables of the NSC (if any), but adds further data in its object report to the unordered variables, increasing its size. If behaviorFlag includes GCI_STORE_TRAV_NSC_REP, then it removes all existing unordered variables and adds new unordered variables with values from the object report.
GciStoreTrav provides automatic byte swizzling. See Byte-Swizzling of Binary Floating-Point Values.
This function raises an error if the traversal buffer contains a report for any object of special implementation format; special objects cannot be modified.
Use of Object Reports
GciStoreTrav stores values in GemStone objects according to the object reports contained in travBuff. Each object report is an instance of the C++ class GciObjRepSType (described in Object Report Header - GciObjRepHdrSType). GciStoreTrav uses the fields in each object report as follows:
report->header.valueBuffSize
The size (in bytes) of the value buffer, where object data is stored. If objId is a Float or SmallFloat and valueBuffSize differs from the actual size for objects of objId’s class, then GciStoreTrav raises an error.
report->header.setIdxSize()
Only needs to be called if the object is indexable. The number of indexed variables in the object stored by GciStoreTrav is never less than this quantity. It may be more if the value buffer contains enough data. GciStoreTrav stores all the indexed variables that it finds in the value buffer. If an existing object has more indexed variables, then it also retains the extras, up to a total of idxSize, and removes any beyond idxSize. If idxSize is larger than the number of indexed variables in both the current object and the value buffer, then GciStoreTrav creates slots for elements in the stored object up to index idxSize and initializes any added elements to nil.
report->header.firstOffset
Ignored for NSC objects. The absolute offset into the target object at which to begin storing values from the value buffer. The absolute offset of the object’s first named instance variable (if any) is one; the offset of its first indexed variable (if any) is one more than the number of its named instance variables. Values are stored into the object in the order that they appear in the value buffer, ignoring the boundary between named and indexed variables. Variables whose offset is less than firstOffset (if any) are initialized to nil or zero. For nonindexable objects, GciStoreTrav raises an error if valueBuffSize and firstOffset imply a size that exceeds the actual size of the object. If objId is a Float or SmallFloat and firstOffset is not one, then GciStoreTrav raises an error.
report->header.objId
The OOP of the object to be stored.
report->header.oclass
Used only when creating a new object, to identify its intended class.
report->header.objectSecurityPolicyId
The ID of the object’s security policy.
report->header.clearBits()
Must be called before any of the following:
report->header.setObjImpl()
You must call rpt->hdr.setObjImpl to set this field to be consistent with the object’s implementation. Formats usable here are GC_FORMAT_OOP, GC_FORMAT_BYTE, and GC_FORMAT_NSC.
report->header.setInvariant()
Boolean value. Call rpt->hdr.setInvariant(TRUE) if you want this object to be made invariant after the store specified by report* is completed.
report->valueBufferBytes()
The value buffer of an object of byte format.
report->valueBufferOops()
The value buffer of an object of pointer or NSC format.
GciStoreTravDo_
Store multiple traversal buffer values in objects, execute the specified code, and return the resulting object.
Return Value
Returns the OOP of the result of executing the specified code. In case of error, this function returns OOP_NIL.
Description
GciStoreTravDo_, like GciStoreTrav, stores data from a traversal buffer into multiple GemStone objects, and also executes supplied code, all in the same network round-trip.
For details of the fields in the instance of GciStoreTravDoArgsSType, see Store Traversal Arguments - GciStoreTravDoArgsSType. The fields of this structure include the traversal buffer and flags as described under GciStoreTrav.
GciStoreTravDoArgsSType includes the doPerform field to indicate different perform options.
- If doPerform is 0, this function executes a string using args->u.executestr, with the semantics of GciExecuteFromContext.
-
If doPerform is any other value, then executes a perform using
args->u.perform, with the semantics of GciPerformNoDebug.
The remaining fields supply needed output after the function has completed. Read alteredTheOops to get the OOPs of the objects that were modified and read alteredCompleted to determine if the array as originally allocated was large enough to hold all the modified objects. If the value is false, the array was too small and holds only some of the modified objects; in this case, call GciAlteredObjs for the rest.
Similarly to GciStoreTrav, GciStoreTravDo_ provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.
Handling Error Conditions
If you get a run time error while executing GciStoreTravDo_, we recommend that you abort the current transaction.
GciStoreTravDoTrav_
Combine in a single function the calls to GciStoreTravDo_ and GciClampedTrav, to store multiple traversal buffer values in objects, execute specified code, and traverse the result object.
Syntax
BoolType GciStoreTravDoTrav_(
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );
Arguments
|
An instance of GciStoreTravDoArgsSType. For details, refer to the discussion of GciStoreTravDo_. |
|
|
An instance of GciClampedTravArgsSType. For details, refer to the discussion of GciClampedTrav. |
Return Value
Returns FALSE if the traversal is not yet completed. Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal (that is, an object report was constructed for each object, minus the special objects).
Description
This function allows the client to execute behavior on the Gem and return the traversal of the result object in a single network round-trip. See the descriptions for GciStoreTravDo_ on GciStoreTravDo_ and GciClampedTrav on GciClampedTrav for details.
See Also
GciStoreTravDoTravRefs_
Combine in a single function modifications to session sets, traversal of objects to the server, optional Smalltalk execution, and traversal to the client of changed objects and (optionally) the result object.
Syntax
int GciStoreTravDoTravRefs_(
const OopType * oopsNoLongerReplicated,
int numNotReplicated,
const OopType * oopsGcedOnClient,
int numGced,
GciStoreTravDoArgsSType * storeTravArgs,
GciClampedTravArgsSType * clampedTravArgs );
Argumentsv
|
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, as described under Store Traversal Arguments - GciStoreTravDoArgsSType. |
|
|
An instance of GciClampedTravArgsSType. For details, see Clamped Traversal Arguments - GciClampedTravArgsSType, and the discussion of GciStoreTrav. There is one exception: in this function, retrievalFlags GCI_RETRIEVE_EXPORT and GCI_CLEAR_EXPORT are ignored. |
Return Value
Returns an int with the following meaning:
0 — traversal of both altered objects and execution result completed.
1 — traversal buffer became full. You must call GciMoreTraversal to finish traversal of the altered and result objects.
Description
This function allows the client to modify the PureExportSet and ReferencedSet, modify or create any number of objects on the server, execute behavior on the Gem, and return the traversal of the changed objects and the result object, all in a single network round-trip.
The elements in oopsGcedOnClient are removed from both PureExportSet and ReferencedSet, and the elements in oopsNoLongerReplicated are removed from the PureExportSet and added to the ReferencedSet.
GciStoreTravDoArgsSType includes the doPerform field to indicate different perform options. The doPerform, which also determines which nested structure is used in the union field.
- If doPerform is 0, this function executes a string using args->u.executestr, with the semantics of GciExecute.
-
If doPerform is 1, then executes a perform using
args->u.perform, with the semantics of GciPerform. - If doPerform is 2, execute a string that is the source code for a Smalltalk block using stdArgs->u.executestr, passing the block arguments in execBlock_args.
-
If doPerform is 3, perform no server Smalltalk execution, but traverse the object specified in
stdArgs->u.perform.receiver as if it was the results of execution. - If doPerform is 4, resume execution of a suspended Smalltalk Process using stdArgs->u.continueArgs, with the semantics of GciContinueWith.
Objects in the ReferencedSet are protected from garbage collection, but may be faulted out of memory. Dirty tracking is not done on objects in the ReferencedSet.
Then per the stdArgs, a GciStoreTrav is done, which may modify or create any number of objects on the server. Newly created objects are added to the PureExportSet.
Then, if specified, Smalltalk execution is performed as in GciPerformNoDebug, GciExecuteStrFromContext, or executing the block code with the given arguments.
Finally, this function does a special GciClampedTrav starting with altered objects, followed by the execution result from the previous step. If no execution was specified, the specified object is traversed as if it was an execution result. Altered objects are those that would be returned from a GciAlteredObjs after the code execution step. This traversal both relies on the contents of the PureExportSet and ReferencedSet does not, and also modifies those sets in ways that GciClampedTrav does not. For details, see the comments in gci.hf.
GciStoreTravDoTravRefs_ is not intended for use within a user action.
GciStringToInteger
Convert a C string to a GemStone SmallInteger or LargeInteger object.
GciStrKeyValueDictAt
Find the value in a symbol KeyValue dictionary at the corresponding string key.
Description
Returns the value in symbol KeyValue dictionary theDict that corresponds to key keyString. If an error occurs or keyString is not found, value is OOP_ILLEGAL. KeyValue dictionaries do not have associations, so no association is returned. GciStrKeyValueDictAt is equivalent to GciStrKeyValueDictAtObj except that the key is a character string, not an object.
GciStrKeyValueDictAtObj
Find the value in a symbol KeyValue dictionary at the corresponding object key.
Description
Returns the value in symbol KeyValue dictionary theDict that corresponds to key keyObj. If an error occurs or keyObj is not found, value is OOP_ILLEGAL. KeyValue dictionaries do not have associations, so no association is returned. Equivalent to the GemStone Smalltalk expression:
^ { theDict at:keyObj }
GciStrKeyValueDictAtObjPut
Store a value into a symbol KeyValue dictionary at the corresponding object key.
Arguments
|
The OOP of a SymbolKeyValueDictionary into which the object is to be stored. |
|
|
The OOP of the object to be stored in the SymbolKeyValueDictionary. |
GciStrKeyValueDictAtPut
Store a value into a symbol KeyValue dictionary at the corresponding string key.
Arguments
|
The OOP of a SymbolKeyValueDictionary into which the object is to be stored. |
|
|
The OOP of the object to be stored in the SymbolKeyValueDictionary. |
GciSymDictAt
Find the value in a symbol dictionary at the corresponding string key.
Syntax
void GciSymDictAt(
OopType theDict,
const char * keyString,
OopType * value,
OopType * association );
Arguments
|
A pointer to the variable that is to receive the OOP of the returned value. |
|
|
A pointer to the variable that is to receive the OOP of the association. |
Description
Returns the value in symbol dictionary theDict that corresponds to key keyString. If an error occurs or keyString is not found, value is OOP_ILLEGAL. If association is not NULL and an error does not occur, stores the OOP of the association for keyString at *association, or stores OOP_ILLEGAL if keyString was not found. Equivalent to GciSymDictAtObj except that the key is a character string, not an object.
To operate on kinds of Dictionary other than SymbolDictionary, such as KeyValueDictionary, use GciPerform, since the KeyValueDictionary class is implemented in Smalltalk. If your dictionary will be large (greater than 20 elements) a KeyValueDictionary is more efficient than a SymbolDictionary.
GciSymDictAtObj
Find the value in a symbol dictionary corresponding to the key object.
Syntax
void GciSymDictAtObj(
OopType theDict,
OopType keyObj,
OopType * value,
OopType * association );
Arguments
|
A pointer to the variable that is to receive the OOP of the returned value. |
|
|
A pointer to the variable that is to receive the OOP of the association. |
Description
Fetches the value in symbol dictionary theDict that corresponds to key keyObj. If an error occurs or keyObj is not found, value is OOP_ILLEGAL. If association is not NULL and an error does not occur, stores the OOP of the association for keyObj at *association, or stores OOP_ILLEGAL if keyObj was not found. Similar to the GemStone Smalltalk expression:
^ { theDict at: keyObj . theDict associationAt: keyObj }
GciSymDictAtObjPut
Store a value into a symbol dictionary at the corresponding object key.
GciSymDictAtPut
Store a value into a symbol dictionary at the corresponding string key.
GciTrackedObjsFetchAllDirty
Find all exported or tracked objects that have changed and are therefore in the ExportedDirtyObjs or TrackedDirtyObjs sets.
Syntax
void GciTrackedObjsFetchAllDirty(
OopType exportedDirty,
int64 * numExportedDirty,
OopType trackedDirty,
int64 * numTrackedDirty );
Arguments
Description
GciTrackedObjsFetchAllDirty fetches all dirty objects and sorts them into two categories:
- Objects in the ExportedDirtyObjs set - objects in the PureExportSet that have been changed since the ExportedDirtyObjs set was initialized or cleared.
- Objects in the TrackedDirtyObjs set - objects in the GciTrackedObjs set that have been changed since the TrackedDirtyObjs set was initialized or cleared.
The ExportedDirtyObjs set is initialized by GciDirtyObjsInit; it is cleared by calls to GciDirtyAlteredObjs, GciDirtyExportedObjs, GciDirtySaveObjs, or GciTrackedObjsFetchAllDirty (this function).
The TrackedDirtyObjs set is initialized by GciTrackedObjsInit and cleared by calls to GciDirtyAlteredObjs, GciDirtySaveObjs, GciDirtyTrackedObjs, or GciTrackedObjsFetchAllDirty (this function).
An object is considered dirty (changed) under one or more of the following conditions:
- The object was changed by Smalltalk execution.
- The object was changed by a call to any GemBuilder function from within a user action.
- The object was changed by a call to one or more of the following functions: GciStorePaths, GciSymDictAtObjPut, GciSymDictAtPut, GciStrKeyValueDictAtObjPut, or GciStrKeyValueDictAtPut.
- A change to the object was committed by another transaction since it was read by this one.
- The object is persistent, but was modified in the current session before the session aborted the transaction. (When the transaction is aborted, the modifications are destroyed, thus changing the state of the object in memory).
You must call both GciDirtyObjsInit and GciTrackedObjsInit once after GciLogin before calling GciTrackedObjsFetchAllDirty.
Note that the ExportedDirtyObjs and TrackedDirtyObjs sets are cleared when this function is executed.
GciTrackedObjsInit
Reinitialize the set of tracked objects maintained by GemStone.
Description
The GciTrackedObjsInit function permits an application to request GemStone to maintain a set of tracked objects. GciTrackedObjsInit must be called once after GciLogin before other tracked objects functions in order for those functions to operate properly, because they depend upon GemStone’s set of tracked objects.
GciTraverseObjs
Traverse an array of GemStone objects.
Syntax
BoolType GciTraverseObjs(
const OopType theOops[ ],
int numOops,
GciTravBufType * travBuff,
int level );
Arguments
|
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. |
Return Value
Returns FALSE if the traversal is not yet completed. Returns TRUE if there are no more objects to be returned by subsequent calls to GciMoreTraversal.
Description
This function allows you to reduce the number of GemBuilder calls that are required for your application program to obtain information about complex objects in the database.
There are no built-in limits on how much information can be obtained in the traversal. You can use the level argument to restrict the size of the traversal.
GciTraverseObjs provides automatic byte swizzling, unless GciSetTraversalBufSwizzling is used to disable swizzling. For more about byte swizzling, see Byte-Swizzling of Binary Floating-Point Values.
Organization of the Traversal Buffer
The first element placed in a traversal buffer is an integer that indicates how many bytes were actually stored in the buffer by this function. The remainder of the traversal buffer consists of a series of object reports, each of which is of type GciObjRepSType, as described under Use of Object Reports.
To create a traversal buffer, use GciAllocTravBuf. This function takes an argument of the size of traversal buffer to allocate. Multiple the number of object m by the object size to determine the size buffer you require. If the traversal buffer is not large enough, you will need to perform GciMoreTraversal.
The Value Buffer
The object report’s value buffer begins at the first byte following the object report header. For byte objects, the value buffer rpt->valueBufferBytes() is an array of type ByteType; for pointer objects and NSCs, the buffer rpt->valueBufferOops() is an array of type OopType. The size of the report’s value buffer (rpt->hdr.valueBuffSize) is the number of bytes of the object’s value returned by this traversal. That number is no greater than the size of the object.
How This Function Works
This section explains how GciTraverseObjs stores object reports in the traversal buffer and values in the value buffer.
1. First, GciTraverseObjs verifies that the traversal buffer is large enough to accommodate at least one object report header (GciObjRepHdrSType). If the buffer is too small, GemBuilder returns an error.
2. For each object in the traversal, GciTraverseObjs discovers if there is enough space left in the traversal buffer to store both the object report header and the object’s values. If there isn’t enough space remaining, the function returns FALSE, and your program can call GciMoreTraversal to continue the traversal. Otherwise (if there is enough space), the object’s values are stored in the traversal buffer.
3. When there are no more objects left to traverse, GciTraverseObjs returns TRUE to indicate that the traversal is complete.
Special Objects
For each occurrence of an object with a special implementation (that is, an instance of SmallInteger, Character, Boolean, or UndefinedObject) contained in theOops, this function will return an accurate object report. For any special object encountered at some deeper point in the traversal, no object report will be generated.
Authorization Violations
If the user is not authorized to read some object encountered during the traversal, the traversal will continue. No value will be placed in the object report’s value buffer, but the report for the forbidden object will contain the following values:
Incomplete Object Reports
It is possible for an object report to not contain all the instance variables of an object, due to traversal specifications or buffer size limitations. The value buffer is incomplete when hdr.isPartial() returns non-zero.
Continuing the Traversal
When the amount of information obtained in a traversal exceeds the amount of available memory, your application can break the traversal into manageable amounts of information by issuing repeated calls to GciMoreTraversal. Generally speaking, an application can continue to call GciMoreTraversal until it has obtained all requested information.
During the entire sequence of GciTraverseObjs and GciMoreTraversal calls that constitute a traversal, any single object report will be returned exactly once. Regardless of the connectivity of objects in the GemStone database, only one report will be generated for any non-special object.
When Traversal Can’t Be Continued
Naturally, GemStone will not continue an incomplete traversal if there is any chance that changes to the database in the intervening period might have invalidated the previous report or changed the connectivity of the objects in the path of the traversal. Specifically, GemStone will refuse to continue a traversal if, in the interval before attempting to continue, you:
- Modify the objects in the database directly, by calling any of the GciStore... or GciAdd... functions;
- Call one of the Smalltalk message-sending functions GciPerform, GciContinue, or any of the GciExecute... functions;
- Abort your transaction, thus invalidating any subsequent information from that traversal.
Any attempt to call GciMoreTraversal after one of these actions will generate an error.
Note that this holds true across multiple GemBuilder applications sharing the same GemStone session. Suppose, for example, that you were holding on to an incomplete traversal buffer and the user moved from the current application to another, did some work that required executing Smalltalk code, and then returned to the original application. You would be unable to continue the interrupted traversal.
Example
For an example of how GciTraverseObjs is used, see GciMoreTraversal.
GciUncompress
Uncompress the supplied data, assumed to have been compressed with GciCompress.
Arguments
|
Pointer to the buffer to hold the resulting uncompressed data. |
|
|
Length, in bytes, of the buffer intended to hold the uncompressed data. |
|
Return Value
GciUncompress returns Z_OK (equal to 0) if the decompression succeeded, or various error values if it failed; see the documentation for the uncompress function in the GNU zlib library at http://www.gzip.org.
Description
GciUncompress passes the supplied inputs unchanged to the uncompress function in the GNU zlib library Version, and returns the result exactly as the GNU uncompress function returns it.
See Also
GciUserActionInit
GciUserActionShutdown
GciUtf8To8Bit
GciVersion
Return a string that describes the GemBuilder version.
Return Value
A null-terminated string, containing period-separated fields that describe the specific release of GemBuilder.
Description
GciVersion gets version information from the shared libraries. The string returned describes the GCI version (that is, the version of the shared libraries, not the version of a GemStone repository).
The version number is provided as a series of period-delimited fields within the string, with the first field being the major version number, the second field the minor version number, and so on. There may be any number of additional fields for a particular version of the GCI. Following this is the build information.
More detailed version information, including Stone version information, can be retrieved using System class methods such as System class >> stoneVersionReport and System class >> gemVersionReport.
Example
BoolType version_example(void)
{
const char* buf;
buf = GciVersion();
printf("Version is %s\n", buf);
return ( buf[0] == '3' );
}