Using the Callin Functions
This section provides a quick summary of the Callin functions, with links to the full description of each function. The following categories are discussed:
-
These functions start and stop a Callin session, and control various settings associated with the session.
-
These functions execute function or routine calls. Stack functions are provided for pushing function or routine references.
-
These functions execute the standard Caché transaction commands (TSTART, TCOMMIT, and TROLLBACK) and the LOCK command.
-
These functions manipulate the Oref counter, perform method calls, and get or set property values. Stack functions are also included for Orefs, method references, and property names.
-
These functions call into Caché to manipulate globals. Functions are provided to push globals onto the argument stack.
-
These functions translate strings from one form to another, and push or pop string arguments.
-
These stack functions are used to push and pop arguments that have int, double, $list, or pointer values.
The following sections discuss the individual functions in more detail.
Process Control
These functions start and stop a Callin session, control various settings associated with the session, and provide a high-level interface for executing ObjectScript commands and expressions.
Session Control
These functions start and stop a Callin session, and control various settings associated with the session.
| CacheAbort | Tells Caché to terminate the current request. |
| CacheChangePasswordA[W][H] | Changes the user's password if Caché authentication is used. Must be called before a Callin session is initialized. |
| CacheContext | Returns an integer indicating whether you are in a $ZF callback session, in the Caché side of a Callin call, or in the user program side. |
| CacheCtrl | Determines whether or not Caché ignores CTRL-C. |
| CacheEnd | Terminates a Caché session and, if necessary, cleans up a broken connection. (Calls into Caché). |
| CacheEndAll | Disconnects all Callin threads and waits until they terminate. |
| CacheOflush | Flushes any pending output. |
| CachePromptA[W][H] |
Returns a string that would be the programmer prompt. |
| CacheSetDir | Dynamically sets the name of the manager's directory (CacheSys\Mgr) at runtime. On Windows, the shared library version of Caché requires this function. |
| CacheSignal | Reports a signal detected by the user program to Caché for handling. |
| CacheSecureStartA[W][H] |
Initiates a Caché process. |
| CacheStartA[W][H] | (Deprecated. Use CacheSecureStart instead) Initiates a Caché process. |
Running ObjectScript
These functions provide a high-level interface for executing ObjectScript commands and expressions.
| CacheExecuteA[W][H] |
Executes an ObjectScript command. (Calls into Caché). |
| CacheEvalA[W][H] |
Evaluates an ObjectScript expression. (Calls into Caché). |
| CacheConvert | Returns the value of the Caché expression returned by CacheEval. |
| CacheType | Returns the datatype of an item returned by CacheEval. |
| CacheErrorA[W][H] |
Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred. |
| CacheErrxlateA[W][H] |
Returns the Caché error string associated with error number returned from a Callin function. |
Functions and Routines
These functions call into Caché to perform function or routine calls. Functions are provided to push function or routine references onto the argument stack.
| CacheDoFun | Perform a routine call (special case). (Calls into Caché). |
| CacheDoRtn | Perform a routine call. (Calls into Caché). |
| CacheExtFun | Perform an extrinsic function call. (Calls into Caché). |
| CachePop | Pops a value off argument stack. |
| CacheUnPop | Restores the stack entry from CachePop |
| CachePushFunc[W][H] | Pushes an extrinsic function reference onto the argument stack. |
| CachePushFuncX[W][H] | Push an extended function reference onto argument stack |
| CachePushRtn[W][H] | Push a routine reference onto argument stack |
| CachePushRtnX[W][H] | Push an extended routine reference onto argument stack |
Transactions and Locking
These functions execute the standard Caché transaction commands (TSTART, TCOMMIT, and TROLLBACK) and the LOCK command.
Transactions
The following functions execute the standard Caché transaction commands.
| CacheTCommit | Executes a Caché TCommit command. |
| CacheTLevel | Returns the current nesting level ($TLEVEL) for transaction processing. |
| CacheTRollback | Executes a Caché TRollback command. |
| CacheTStart | Executes a Caché TStart command. |
Locking
These functions execute various forms of the Cache LOCK command. Functions are provided to push lock names onto the argument stack for use by the CacheAcquireLock function.
| CacheAcquireLock | Executes a Caché LOCK command. |
| CacheReleaseAllLocks | Performs an argumentless Cache LOCK command to remove all locks currently held by the process. |
| CacheReleaseLock | Executes a Cache LOCK — command to decrement the lock count for the specified lock name. |
| CachePushLock[W][H] | Initializes a CacheAcquireLock command by pushing the lock name on the argument stack. |
| CachePushLockX[W][H] | Initializes a CacheAcquireLock command by pushing the lock name and an environment string on the argument stack. |
Managing Objects
These functions call into Caché to manipulate the Oref counter, perform method calls, and get or set property values. Stack functions are also included for Orefs, method references, and property names.
Orefs
| CacheCloseOref | Decrement the reference counter for an OREF. (Calls into Caché). |
| CacheIncrementCountOref | Increment the reference counter for an OREF |
| CachePopOref | Pop an OREF off argument stack |
| CachePushOref | Push an OREF onto argument stack |
Methods
| CacheInvokeMethod | Perform an instance method call. (Calls into Caché). |
| CachePushMethod[W][H] | Push an instance method reference onto argument stack |
| CacheInvokeClassMethod | Perform a class method call. (Calls into Caché). |
| CachePushClassMethod[W][H] | Push a class method reference onto argument stack |
Properties
| CacheGetProperty | Obtain the value for a property. (Calls into Caché). |
| CacheSetProperty | Store the value for a property. (Calls into Caché). |
| CachePushProperty[W][H] | Push a property name onto argument stack |
Managing Globals
These functions call into Caché to manipulate globals. Functions are provided to push globals onto the argument stack.
| CacheGlobalGet | Obtains the value of the global reference defined by CachePushGlobal[W][H] and any subscripts. The node value is pushed onto the argument stack. |
| CacheGlobalGetBinary | Obtains the value of the global reference like CacheGlobalGet, and also tests to make sure that the result is a binary string that will fit in the provided buffer. |
| CacheGlobalSet | Stores the value of the global reference. The node value must be pushed onto the argument stack before this call. |
| CacheGlobalData | Performs a $Data on the specified global. |
| CacheGlobalIncrement | Performs a $Increment and returns the result on top of the stack. |
| CacheGlobalKill | Performs a ZKILL on a global node or tree. |
| CacheGlobalOrder | Performs a $Order on the specified global. |
| CacheGlobalQuery | Performs a $Query on the specified global. |
| CacheGlobalRelease | Releases ownership of a retained global buffer, if one exists. |
| CachePushGlobal[W][H] | Pushes a global name onto argument stack |
| CachePushGlobalX[W][H] | Pushes an extended global name onto argument stack |
Managing Strings
These functions translate strings from one form to another, and push or pop string arguments.
Long String Functions
Caché long string functions may be used for both long strings and standard strings. Functions are provided for local 8-bit encoding, 2–byte Unicode, and 4–byte Unicode.
| CacheCvtExStrInA[W][H] | Translates a string with specified external character set encoding to the character string encoding used internally by Caché. |
| CacheCvtExStrOutA[W][H] | Translates a string from the character string encoding used internally in Caché to a string with the specified external character set encoding. |
| CacheExStrKill | Releases the storage associated with a long string. |
| CacheExStrNew[W][H] | Allocates the requested amount of storage for a long string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure. |
| CachePopExStrCvtW[H] | Pops a string off the argument stack and translates it to a Unicode string. |
| CachePushExStrCvtW[H] | Converts a Unicode string to local 8–bit encoding and pushes it onto the argument stack. |
| CachePopExStr[W][H] | Pops a value off argument stack and converts it to a string of the desired type. |
| CachePushExStr[W][H] | Pushes a string onto the argument stack |
Standard String Functions
The following functions deal with standard Caché strings (limited to 32K). Functions are provided for local 8-bit encoding, 2–byte Unicode, and 4–byte Unicode.
| CacheCvtInA[W][H] | Translates a string with the specified external character set encoding to the character string encoding used internally in Caché. |
| CacheCvtOutA[W][H] | Translates a string from the character string encoding used internally in Caché to a string with the specified external character set encoding. |
| CachePopStr[W][H] | Pops a value off argument stack and converts it to a string of the desired type. |
| CachePushStr[W][H] | Pushes a string onto argument stack |
| CachePushCvtW[H] | Translates a Unicode string to local and pushes it onto argument stack |
| CachePopCvtW[H] | Pops a value off argument stack and translates it into the desired string type. |
Managing Other Datatypes
These functions are used to push and pop argument values with datatypes such as int, double, $list, or pointer, and to return the position of specified bit values within a bitstring.
| CachePushInt | Push an integer onto argument stack |
| CachePopInt | Pop a value off argument stack and convert it to an integer |
| CachePushInt64 | Push a 64–bit (long long) value onto argument stack |
| CachePopInt64 | Pop a value off argument stack and convert it to a 64–bit (long long) value |
| CachePushDbl | Push a Caché double onto argument stack |
| CachePushIEEEDbl | Push an IEEE double onto argument stack. |
| CachePopDbl | Pops value off argument stack and converts it to a double |
| CachePushList | Translates and pushes a $LIST object onto argument stack |
| CachePopList | Pops a $LIST object off argument stack and translates it |
| CachePushPtr | Pushes a pointer value onto argument stack |
| CachePopPtr | Pops a pointer value off argument stack |
| CachePushUndef | Pushes an Undefined value that is interpreted as an omitted function argument. |
| CacheBitFind[B] | Returns the position of specified bit values within a bitstring. Similar to Caché $BITFIND. |
