Skip to main content

Callin Function Reference

This reference chapter contains detailed descriptions of all Caché Callin functions, arranged in alphabetical order. For an introduction to the Callin functions organized by function, see Using the Callin Functions.

Note:

Caché Callin functions that operate on strings have both 8-bit and Unicode versions. These functions use a suffix character to indicate the type of string that they handle:

  • Names with an “A” suffix or no suffix at all (for example,CacheEvalA or CachePopStr) are versions for 8-bit character strings.

  • Names with a “W” suffix (for example,CacheEvalW or CachePopStrW) are versions for Unicode character strings on platforms that use 2–byte Unicode characters.

  • Names with an “H” suffix (for example,CacheEvalH or CachePopStrH) are versions for Unicode character strings on platforms that use 4–byte Unicode characters.

For convenience, the different versions of each function are listed together here. For example, CacheEvalA[W][H] or CachePopStr[W][H].

Alphabetical Function List

This section contains an alphabetical list of all Callin functions with a brief description of each function and links to detailed descriptions.

  • CacheAbort — Tells Caché to cancel the current request being processed on the Caché side, when it is convenient to do so.

  • CacheAcquireLock — Executes a Cache LOCK command. The lock reference should already be set up with CachePushLockX[W][H].

  • CacheChangePasswordA[W][H] — Changes the user's password if Caché authentication is used (not valid for other forms of authentication).

  • CacheBitFind[B] — Returns the position of specified bit values within a bitstring (similar to Caché $BITFIND).

  • CacheCloseOref — Decrements the system reference counter for an OREF.

  • CacheContext — Returns true if there is a request currently being processed on the Caché side of the connection when using an external Callin program.

  • CacheConvert — Converts the value returned by CacheEvalA[W][H] into proper format and places in address specified in its return value.

  • CacheCtrl — Determines whether or not Caché ignores CTRL-C.

  • CacheCvtExStrInA[W][H] — Translates a string with specified external character set encoding to the local 8-bit character string encoding used internally only in 8-bit versions of Caché.

  • CacheCvtExStrOutA[W][H] — Translates a string from the local 8-bit character string encoding used internally in the Caché 8-bit product to a string with the specified external character set encoding. (This is only available with 8-bit versions of Caché.)

  • CacheCvtInA[W][H] — Translates string with specified external character set encoding to the local 8-bit character string encoding (used internally only in 8-bit versions of Caché) or the Unicode character string encoding (used internally in Unicode versions of Caché).

  • CacheCvtOutA[W][H] — Translates a string from the local 8-bit character string encoding used internally in the Caché 8-bit product to a string with the specified external character set encoding. (This is only available with 8-bit versions of Caché.)

  • CacheDoFun — Performs a routine call (special case).

  • CacheDoRtn — Performs a routine call.

  • CacheEnd — Terminates a Caché process. If there is a broken connection, it also performs clean-up operations.

  • CacheEndAll — Disconnects all Callin threads and waits until they terminate.

  • 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] — Translates an integer error code into a Cache error string.

  • CacheEvalA[W][H] — Evaluates a string as if it were a Caché expression and places the return value in memory for further processing by CacheType and CacheConvert.

  • CacheExecuteA[W][H] — Executes a command string as if it were typed at the Caché programmer prompt.

  • CacheExStrKill — Releases the storage associated with an EXSTR string.

  • CacheExStrNew[W][H] — Allocates the requested amount of storage for a string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure.

  • CacheExtFun — Performs an extrinsic function call where the return value is pushed onto the argument stack.

  • CacheGetProperty — Obtains the value of the property defined by CachePushProperty[W][H]. The value is pushed onto the argument stack.

  • CacheGlobalData — Performs a $Data on the specified global.

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

  • 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 — Release ownership of a retained global buffer, if one exists.

  • CacheGlobalSet — Stores the value of the global reference defined by CachePushGlobal[W][H] and any subscripts. The node value must be pushed onto the argument stack before this call.

  • CacheIncrementCountOref — Increments the system reference counter for an OREF.

  • CacheInvokeClassMethod — Executes the class method call defined by CachePushClassMethod[W][H] and any arguments. The return value is pushed onto the argument stack.

  • CacheInvokeMethod — Executes the instance method call defined by CachePushMethod[W][H] and any arguments pushed onto the argument stack.

  • CacheOflush — Flushes any pending output.

  • CachePop — Pops a value off argument stack.

  • CachePopCvtW[H] — Pops a local 8-bit string off argument stack and translates it to Unicode. Identical to CachePopStr[W][H] for Unicode versions.

  • CachePopDbl — Pops a value off argument stack and converts it to a double.

  • CachePopExStr[W][H] — Pops a value off argument stack and converts it to a long string.

  • CachePopExStrCvtW[H] — Pops a value off argument stack and converts it to a long Unicode string.

  • CachePopInt — Pops a value off argument stack and converts it to an integer.

  • CachePopInt64 — Pops a value off argument stack and converts it to a 64-bit (long long) number.

  • CachePopList — Pops a $LIST object off argument stack and converts it. String elements are copied or translated as appropriate depending on whether this is a Unicode or 8-bit version.

  • CachePopOref — Pops an OREF off argument stack.

  • CachePopPtr — Pops a pointer off argument stack in internal format.

  • CachePopStr[W][H] — Pops a value off argument stack and converts it to a string.

  • CachePromptA[W][H] — Returns a string that would be the programmer prompt.

  • CachePushClassMethod[W][H] — Pushes a class method reference onto the argument stack.

  • CachePushCvtW[H] — Translates a Unicode string to local 8-bit and pushes it onto the argument stack. Identical to CachePushStr[W][H] for Unicode versions.

  • CachePushDbl — Pushes a Caché double onto the argument stack.

  • CachePushExStr[W][H] — Pushes a long string onto the argument stack.

  • CachePushExStrCvtW[H] — Translates a Unicode string to local 8-bit and pushes it onto the argument stack.

  • CachePushFunc[W][H] — Pushes an extrinsic function reference onto the argument stack.

  • CachePushFuncX[W][H] — Pushes an extended extrinsic function reference onto the argument stack.

  • CachePushGlobal[W][H] — Pushes a global reference onto the argument stack.

  • CachePushGlobalX[W][H] — Pushes an extended global reference onto the argument stack.

  • CachePushIEEEDbl — Pushes an IEEE double onto the argument stack.

  • CachePushInt — Pushes an integer onto the argument stack.

  • CachePushInt64 — Pushes a 64-bit (long long) number onto the argument stack.

  • CachePushList — Converts a $LIST object and pushes it onto the argument stack.

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

  • CachePushMethod[W][H] — Pushes an instance method reference onto the argument stack.

  • CachePushOref — Pushes an OREF onto the argument stack.

  • CachePushProperty[W][H] — Pushes a property reference onto the argument stack.

  • CachePushPtr — Pushes a pointer onto the argument stack in internal format.

  • CachePushRtn[W][H] — Pushes a routine reference onto the argument stack.

  • CachePushRtnX[W][H] — Pushes an extended routine reference onto the argument stack.

  • CachePushStr[W][H] — Pushes a byte string onto the argument stack.

  • CachePushExStrCvtW[H] — Converts a Unicode string to local 8–bit encoding and pushes it onto the argument stack.

  • CachePushUndef — pushes an Undefined value that is interpreted as an omitted function argument.

  • 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. This command will only release one incremental lock at a time.

  • CacheSecureStartA[W][H] — Calls into Cache to set up a Cache process.

  • CacheSetDir — Dynamically sets the name of the manager's directory at runtime.

  • CacheSetProperty — Stores the value of the property defined by CachePushProperty[W][H].

  • CacheSignal — Passes on signals caught by user's program to Caché.

  • CacheSPCReceive — Receive single-process-communication message.

  • CacheSPCSend — Send a single-process-communication message.

  • CacheStartA[W][H] — Calls into Caché to set up a Caché process.

  • CacheTCommit — Executes a Cache TCommit command.

  • CacheTLevel — Returns the current nesting level ($TLEVEL) for transaction processing.

  • CacheTRollback — Executes a Cache TRollback command.

  • CacheTStart — Executes a Cache TStart command.

  • CacheType — Returns the native type of the item returned by CacheEvalA[W][H], as the function value.

  • CacheUnPop — Restores the stack entry from CachePop.

CacheAbort

int CacheAbort(unsigned long type)
Arguments

type Either of the following predefined values that specify how the termination occurs:
  • CACHE_CTRLC — Interrupts the Caché processing as if a CTRL-C had been processed (regardless of whether CTRL-C has been enabled with CacheCtrl). A connection to Caché remains.

  • CACHE_RESJOB — Terminates the Callin connection. You must then call CacheEnd and then CacheStart to reconnect to Caché.

Description

Tells Caché to cancel the current request being processed on the Caché side, when it is convenient to do so. This function is for use if you detect some critical event in an AST (asynchronous trap) or thread running on the Callin side. (You can use CacheContext to determine if there is a Caché request currently being processed.) Note that this only applies to Callin programs that use an AST or separate thread.

Return Values for CacheAbort

CACHE_BADARG The termination type is invalid.
CACHE_CONBROKEN Connection has been broken.
CACHE_NOCON No connection has been established.
CACHE_NOTINCACHE The Callin partner is not in Caché at this time.
CACHE_SUCCESS Connection formed.
Example

rc = CacheAbort(CACHE_CTRLC);

CacheAcquireLock

int CacheAcquireLock(int nsub, int flg, int tout, int * rval)
Arguments

nsub Number of subscripts in the lock reference.
flg Modifiers to the lock command. Valid values are one or both of CACHE_INCREMENTAL_LOCK and CACHE_SHARED_LOCK.
tout Number of seconds to wait for the lock command to complete. Negative for no timeout. 0 means return immediately if the lock is not available, although a minimum timeout may be applied if the lock is mapped to a remote system.
rval Optional pointer to an int return value: success = 1, failure = 0.
Description

Executes a Cache LOCK command. The lock reference should already be set up with CachePushLock.

Return Values for CacheAcquireLock

CACHE_FAILURE An unexpected error has occurred.
CACHE_SUCCESS Successfully called the LOCK command (but the rval parameter must be examined to determine if the lock succeeded).
CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERARGSTACK Argument stack overflow.

CacheBitFind

int CacheBitFind(int strlen, unsigned short *bitstr, int newlen, int srch, int revflg)
Arguments

strlen Data length of the bitstring.
bitstr Pointer to a Unicode bitstring.
newlen 0 to start at the beginning, otherwise 1–based starting position
srch The bit value (0 or 1) to search for within the bitstring.
revflg Specifies the search direction:

1 — Search forward (left to right) from the position indicated by newlen.

0 — Search backward from the position indicated by newlen.

Description

Returns the bit position (1-based) of the next bit within bitstring bitstr that has the value specified by srch. The direction of the search is indicated by revflg. Returns 0 if there are no more bits of the specified value in the specified direction.

This function is similar to Caché $BITFIND (also see “General Information on Bitstring Functions”).

Return Values for CacheBitFind

CACHE_SUCCESS The operation was successful.

CacheBitFindB

int CacheBitFindB(int strlen, unsigned char *bitstr, int newlen, int srch, int revflg)
Arguments

strlen Data length of the bitstring.
bitstr Pointer to a bitstring.
newlen 0 to start at the beginning, otherwise 1–based starting position.
srch The bit value (0 or 1) to search for within the bitstring.
revflg Specifies the search direction:

1 — Search forward (left to right) from the position indicated by newlen.

0 — Search backward from the position indicated by newlen.

Description

Returns the bit position (1-based) of the next bit within bitstring bitstr that has the value specified by srch. The direction of the search is indicated by revflg. Returns 0 if there are no more bits of the specified value in the specified direction.

This function is similar to Caché $BITFIND (also see “General Information on Bitstring Functions”).

Return Values for CacheBitFindB

CACHE_SUCCESS The operation was successful.

CacheChangePasswordA

Variants: CacheChangePasswordW, CacheChangePasswordH

int CacheChangePasswordA(CACHE_ASTRP username, CACHE_ASTRP oldpassword, CACHE_ASTRP newpassword)
Arguments

username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description

This function can change the user's password if Caché authentication or delegated authentication is used. It is not valid for LDAP, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a CACHE_CHANGEPASSWORD error from CacheSecureStart. In such a case CacheChangePassword would be called to change the password, then CacheSecureStart would be called again.

Return Values for CacheChangePasswordA

CACHE_FAILURE An unexpected error has occurred.
CACHE_SUCCESS Password changed.

CacheChangePasswordH

Variants: CacheChangePasswordA, CacheChangePasswordW

int CacheChangePasswordH(CACHEHSTRP username, CACHEHSTRP oldpassword, CACHEHSTRP newpassword)
Arguments

username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description

This function can change the user's password if Caché authentication or delegated authentication is used. It is not valid for LDAP, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a CACHE_CHANGEPASSWORD error from CacheSecureStart. In such a case CacheChangePassword would be called to change the password, then CacheSecureStart would be called again.

Return Values for CacheChangePasswordH

CACHE_FAILURE An unexpected error has occurred.
CACHE_SUCCESS Password changed.

CacheChangePasswordW

Variants: CacheChangePasswordA, CacheChangePasswordH

int CacheChangePasswordW(CACHEWSTRP username, CACHEWSTRP oldpassword, CACHEWSTRP newpassword)
Arguments

username Username of the user whose password must be changed.
oldpassword User's old password.
newpassword New password.
Description

This function can change the user's password if Caché authentication or delegated authentication is used. It is not valid for LDAP, Kerberos, or other forms of authentication. It must be called before a Callin session is initialized. A typical use would be to handle a CACHE_CHANGEPASSWORD error from CacheSecureStart. In such a case CacheChangePassword would be called to change the password, then CacheSecureStart would be called again.

Return Values for CacheChangePasswordW

CACHE_FAILURE An unexpected error has occurred.
CACHE_SUCCESS Password changed.

CacheCloseOref

int CacheCloseOref(unsigned int oref)
Arguments

oref Object reference.
Description

Decrements the system reference counter for an OREF.

Return Values for CacheCloseOref

CACHE_ERBADOREF Invalid OREF.
CACHE_SUCCESS The operation was successful.

CacheContext

int CacheContext()
Description

Returns an integer as the function value.

If you are using an external Callin program (as opposed to a module that was called from a $ZF function) and your program employs an AST or separate thread, then CacheContext tells you if there is a request currently being processed on the Caché side of the connection. This information is needed to decide if you must return to Caché to allow processing to complete.

Return Values for CacheContext

-1 Created in Caché via a $ZF callback.
0 No connection or not in Caché at the moment.
1 In Caché via an external (i.e., not $ZF) connection. An asynchronous trap (AST), such as an exit-handler, would need to return to Caché to allow Caché to complete processing.
Note:

The information about whether you are in a $ZF function from a program or an AST is needed because, if you are in an AST, then you need to return to Caché to allow processing to complete.

Example

rc = CacheContext();

CacheConvert

int CacheConvert(unsigned long type, void * rbuf)
Arguments

type The #define'd type, with valid values listed below.
rbuf Address of a data area of the proper size for the data type. If the type is CACHE_ASTRING, rbuf should be the address of a CACHE_ASTR structure that will contain the result, and the len element in the structure should be filled in to represent the maximum size of the string to be returned (in characters). Similarly, if the type is CACHE_WSTRING, rbuf should be the address of a CACHEWSTR structure whose len element has been filled in to represent the maximum size (in characters).
Description

Converts the value returned by CacheEval into proper format and places in address specified in its return value (listed below as rbuf).

Valid values of type are:

  • CACHE_ASTRING — 8-bit character string.

  • CACHE_CHAR — 8-bit signed integer.

  • CACHE_DOUBLE — 64-bit floating point.

  • CACHE_FLOAT — 32-bit floating point.

  • CACHE_INT — 32-bit signed integer.

  • CACHE_INT2 — 16-bit signed integer.

  • CACHE_INT4 — 32-bit signed integer.

  • CACHE_INT8 — 64-bit signed integer.

  • CACHE_UCHAR — 8-bit unsigned integer.

  • CACHE_UINT — 32-bit unsigned integer.

  • CACHE_UINT2 — 16-bit unsigned integer.

  • CACHE_UINT4 — 32-bit unsigned integer.

  • CACHE_UINT8 — 64-bit unsigned integer.

  • CACHE_WSTRING — Unicode character string.

Return Values for CacheConvert

CACHE_BADARG Type is invalid.
CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_FAILURE An unexpected error has occurred.
CACHE_NOCON No connection has been established.
CACHE_NORES No result whose type can be returned (no call to CacheEvalA preceded this call).
CACHE_RETTRUNC Success, but the type CACHE_ASTRING, CACHE_INT8, CACHE_UINT8 and CACHE_WSTRING resulted in a value that would not fit in the space allocated in retval. For CACHE_INT8 and CACHE_UINT8, this means that the expression resulted in a floating point number that could not be normalized to fit within 64 bits.
CACHE_STRTOOLONG String is too long.
CACHE_SUCCESS Value returned by last CacheEval converted successfully.
Note:

Caché may perform division when calculating the return value for floating point types, CACHE_FLOAT and CACHE_DOUBLE, which have decimal parts (including negative exponents), as well as the 64-bit integer types (CACHE_INT8 and CACHE_UINT8). Therefore, the returned result may not be identical in value to the original. CACHE_ASTRING, CACHE_INT8, CACHE_UINT8 and CACHE_WSTRING can return the status CACHE_RETTRUNC.

Example

CACHE_ASTR retval; 
/* define variable retval */

retval.len = 20; 
/* maximum return length of string */

rc = CacheConvert(CACHE_ASTRING,&retval);

CacheCtrl

int CacheCtrl(unsigned long flags)
Arguments

flags Either of two #define'd values specifying how Caché handles certain keystrokes.
Description

Determines whether or not Caché ignores CTRL-C. flags can have bit state values of

  • CACHE_DISACTRLC — Caché ignores CTRL-C.

  • CACHE_ENABCTRLC — Default if function is not called, unless overridden by a BREAK or an OPEN command. In Caché, CTRL-C generates an <INTERRUPT>.

Return Values for CacheCtrl

CACHE_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
CACHE_SUCCESS Control function performed.
Example

rc = CacheCtrl(CACHE_ENABCTRLC);

CacheCvtExStrInA

Variants: CacheCvtExStrInW, CacheCvtExStrInH

int CacheCvtExStrInA(CACHE_EXSTRP src, CACHE_ASTRP tbl, CACHE_EXSTRP res)
Arguments

src Address of a CACHE_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_EXSTRP variable that will contain the result.
Description

Translates a string with specified external character set encoding to the local 8-bit character string encoding used internally only in 8-bit versions of Caché.

Return Values for CacheCvtExStrInA

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for Unicode.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtExStrInW

Variants: CacheCvtExStrInA, CacheCvtExStrInH

int CacheCvtExStrInW(CACHE_EXSTRP src, CACHEWSTRP tbl, CACHE_EXSTRP res)
Arguments

src Address of a CACHE_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_EXSTRP variable that will contain the result.
Description

Translates a string with specified external character set encoding to the 2–byte Unicode character string encoding used internally in Unicode versions of Caché.

Return Values for CacheCvtExStrInW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for 8–bit systems.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtExStrInH

Variants: CacheCvtExStrInA, CacheCvtExStrInW

int CacheCvtExStrInH(CACHE_EXSTRP src, CACHEWSTRP tbl, CACHE_EXSTRP res)
Arguments

src Address of a CACHE_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_EXSTRP variable that will contain the result.
Description

Translates a string with specified external character set encoding to the 4–byte Unicode character string encoding used internally in Unicode versions of Caché.

Return Values for CacheCvtExStrInH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for 8–bit systems.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtExStrOutA

Variants: CacheCvtExStrOutW, CacheCvtExStrOutH

int CacheCvtExStrOutA(CACHE_EXSTRP src, CACHE_ASTRP tbl, CACHE_EXSTRP res)
Arguments

src Address of a CACHE_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_EXSTRP variable that will contain the result.
Description

Translates a string from the local 8-bit character string encoding used internally in the Caché 8-bit product to a string with the specified external character set encoding. (This is only available with 8-bit versions of Caché.)

Return Values for CacheCvtExStrOutA

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for Unicode.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtExStrOutW

Variants: CacheCvtExStrOutA, CacheCvtExStrOutH

int CacheCvtExStrOutW(CACHE_EXSTRP src, CACHEWSTRP tbl, CACHE_EXSTRP res)
Arguments

src Address of a CACHE_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_EXSTRP variable that will contain the result.
Description

Translates a string from the 2–byte Unicode character string encoding used internally in Unicode versions of Caché to a string with the specified external character set encoding. (This is only available with Unicode versions of Caché.)

Return Values for CacheCvtExStrOutW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for 8–bit systems.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtExStrOutH

Variants: CacheCvtExStrOutA, CacheCvtExStrOutW

int CacheCvtExStrOutH(CACHE_EXSTRP src, CACHEWSTRP tbl, CACHE_EXSTRP res)
Arguments

src Address of a CACHE_EXSTRP variable that contains the string to be converted.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_EXSTRP variable that will contain the result.
Description

Translates a string from the 4–byte Unicode character string encoding used internally in Unicode versions of Caché to a string with the specified external character set encoding. (This is only available with Unicode versions of Caché.)

Return Values for CacheCvtExStrOutH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for 8–bit systems.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtInA

Variants: CacheCvtInW, CacheCvtInH

int CacheCvtInA(CACHE_ASTRP src, CACHE_ASTRP tbl, CACHE_ASTRP res)
Arguments

src The string in an external character set encoding to be translated (described using a counted character string buffer). The string should be initialized, for example, by setting the value to the number of blanks representing the maximum number of characters expected as output.
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_ASTR variable that will contain the counted 8-bit string result.
Description

Translates string with specified external character set encoding to the local 8-bit character string encoding used internally only in 8-bit versions of Caché.

Return Values for CacheCvtInA

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for Unicode.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtInH

Variants: CacheCvtInA, CacheCvtInW

int CacheCvtInH(CACHE_ASTRP src, CACHEHSTRP tbl, CACHEHSTRP res)
Arguments

src The string in an external character set encoding to be translated (described using the number of bytes required to hold the Unicode string).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHEHSTRP variable that will contain the counted Unicode string result.
Description

Translates string with specified external character set encoding to the Unicode character string encoding used internally in Unicode versions of Caché.

Return Values for CacheCvtInH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for 8–bit systems.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtInW

Variants: CacheCvtInA, CacheCvtInH

int CacheCvtInW(CACHE_ASTRP src, CACHEWSTRP tbl, CACHEWSTRP res)
Arguments

src The string in an external character set encoding to be translated (described using the number of bytes required to hold the Unicode string).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHEWSTR variable that will contain the counted Unicode string result.
Description

Translates string with specified external character set encoding to the Unicode character string encoding used internally in Unicode versions of Caché.

Return Values for CacheCvtInW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for 8–bit systems.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtOutA

Variants: CacheCvtOutW, CacheCvtOutH

int CacheCvtOutA(CACHE_ASTRP src, CACHE_ASTRP tbl, CACHE_ASTRP res)
Arguments

src The string in the local 8-bit character string encoding used internally in the Caché 8-bit product (if a NULL pointer is passed, Caché will use the result from the last call to CacheEvalA or CacheEvalW).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_ASTR variable that will contain the result in the target external character set encoding (described using a counted 8-bit character string buffer).
Description

Translates a string from the local 8-bit character string encoding used internally in the Caché 8-bit product to a string with the specified external character set encoding. (This is only available with 8-bit versions of Caché.)

Return Values for CacheCvtOutA

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for Unicode.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtOutH

Variants: CacheCvtOutA, CacheCvtOutW

int CacheCvtOutH(CACHEHSTRP src, CACHEHSTRP tbl, CACHE_ASTRP res)
Arguments

src The string in the Unicode character string encoding used internally in the Caché Unicode product (if a NULL pointer is passed, Caché will use the result from the last call to CacheEvalA or CacheEvalW).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_ASTR variable that will contain the result in the target external character set encoding (described using a counted 8-bit character string buffer).
Description

Translates a string from the Unicode character string encoding used internally in Unicode versions of Caché to a string with the specified external character set encoding. (This is only available with Unicode versions of Caché.)

Return Values for CacheCvtOutH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for 8–bit systems.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheCvtOutW

Variants: CacheCvtOutA, CacheCvtOutH

int CacheCvtOutW(CACHEWSTRP src, CACHEWSTRP tbl, CACHE_ASTRP res)
Arguments

src The string in the Unicode character string encoding used internally in the Caché Unicode product (if a NULL pointer is passed, Caché will use the result from the last call to CacheEvalA or CacheEvalW).
tbl The name of the I/O translation table to use to perform the translation (a null string indicates that the default process I/O translation table name should be used).
res Address of a CACHE_ASTR variable that will contain the result in the target external character set encoding (described using a counted 8-bit character string buffer).
Description

Translates a string from the Unicode character string encoding used internally in Unicode versions of Caché to a string with the specified external character set encoding. (This is only available with Unicode versions of Caché.)

Return Values for CacheCvtOutW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_ERRUNIMPLEMENTED Not available for 8–bit systems.
CACHE_ERVALUE The specified I/O translation table name was undefined or did not have an input component.
CACHE_ERXLATE Input string could not be translated using the specified I/O translation table.
CACHE_NOCON No connection has been established.
CACHE_RETTRUNC Result was truncated because result buffer was too small.
CACHE_FAILURE Error encountered while trying to build translation data structures (probably not enough partition memory).
CACHE_SUCCESS Translation completed successfully.

CacheDoFun

int CacheDoFun(unsigned int flags, int narg)
Arguments

flags Routine flags from CachePushRtn[XW]
narg Number of call arguments pushed onto the argument stack. Target must have a (possibly empty) formal parameter list.
Description

Performs a routine call (special case).

Return Values for CacheDoFun

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_FAILURE Internal consistency error.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheDoRtn

int CacheDoRtn(unsigned int flags, int narg)
Arguments

flags Routine flags from CachePushRtn[XW]
narg Number of call arguments pushed onto the argument stack. If zero, target must not have a formal parameter list.
Description

Performs a routine call.

Return Values for CacheDoRtn

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_FAILURE Internal consistency error.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheEnd

int CacheEnd()
Description

Terminates a Caché process. If there is a broken connection, it also performs clean-up operations.

Return Values for CacheEnd

CACHE_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
CACHE_NOCON No connection has been established.
CACHE_SUCCESS Caché session terminated/cleaned up.

CacheEnd can also return any of the Caché error codes.

Example

rc = CacheEnd();

CacheEndAll

int CacheEndAll()
Description

Disconnects all threads in a threaded Callin environment, then schedules the threads for termination and waits until they are done.

Return Values for CacheEndAll

CACHE_SUCCESS Caché session terminated/cleaned up.
Example

rc = CacheEndAll();

CacheErrorA

Variants: CacheErrorW, CacheErrorH

int CacheErrorA(CACHE_ASTRP msg, CACHE_ASTRP src, int * offp)
Arguments

msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp An integer that specifies the offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description

Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.

Return Values for CacheErrorA

CACHE_CONBROKEN Connection has been broken.
CACHE_NOCON No connection has been established.
CACHE_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
CACHE_SUCCESS Connection formed.
Example

CACHE_ASTR errmsg;
CACHE_ASTR srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = CacheErrorA(&errmsg, &srcline, &offset)) != CACHE_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);

CacheErrorH

Variants: CacheErrorA, CacheErrorW

int CacheErrorH(CACHEHSTRP msg, CACHEHSTRP src, int * offp)
Arguments

msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp The offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description

Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.

Return Values for CacheErrorH

CACHE_CONBROKEN Connection has been broken.
CACHE_NOCON No connection has been established.
CACHE_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
CACHE_SUCCESS Connection formed.
Example

CACHEHSTRP errmsg;
CACHEHSTRP srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = CacheErrorH(&errmsg, &srcline, &offset)) != CACHE_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);

CacheErrorW

Variants: CacheErrorA, CacheErrorH

int CacheErrorW(CACHEWSTRP msg, CACHEWSTRP src, int * offp)
Arguments

msg The error message or the address of a variable to receive the error message.
src The source string for the error or the address of a variable to receive the source string the error message.
offp The offset to location in errsrc or the address of an integer to receive the offset to the source string the error message.
Description

Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.

Return Values for CacheErrorW

CACHE_CONBROKEN Connection has been broken.
CACHE_NOCON No connection has been established.
CACHE_RETTOOSMALL The length of the return value for either errmsg or errsrc was not of the valid size.
CACHE_SUCCESS Connection formed.
Example

CACHEWSTRP errmsg;
CACHEWSTRP srcline;
int offset;
errmsg.len = 50;
srcline.len = 100;
if ((rc = CacheErrorW(&errmsg, &srcline, &offset)) != CACHE_SUCCESS)
printf("\r\nfailed to display error - rc = %d",rc);

CacheErrxlateA

Variants: CacheErrxlateW, CacheErrxlateH

int CacheErrxlateA(int code, CACHE_ASTRP rbuf)
Arguments

code The error code.
rbuf Address of a CACHE_ASTR variable to contain the Caché error string. The len field should be loaded with the maximum string size that can be returned.
Description

Translates error code code into a Cache error string, and writes that string into the structure pointed to by rbuf

Return Values for CacheErrxlateA

CACHE_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest Caché error number.
CACHE_RETTRUNC The associated error string was truncated to fit in the allocated area.
CACHE_SUCCESS Connection formed.
Example

CACHE_ASTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = CacheErrxlateA(CACHE_ERSTORE,&retval);

CacheErrxlateH

Variants: CacheErrxlateA, CacheErrxlateW

int CacheErrxlateH(int code, CACHEHSTRP rbuf)
Arguments

code The error code.
rbuf Address of a CACHEHSTRP variable to contain the Caché error string. The len field should be loaded with the maximum string size that can be returned.
Description

Translates error code code into a Cache error string, and writes that string into the structure pointed to by rbuf

Return Values for CacheErrxlateH

CACHE_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest Caché error number.
CACHE_RETTRUNC The associated error string was truncated to fit in the allocated area.
CACHE_SUCCESS Connection formed.
Example

CACHEHSTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = CacheErrxlateH(CACHE_ERSTORE,&retval);

CacheErrxlateW

Variants: CacheErrxlateA, CacheErrxlateH

int CacheErrxlateW(int code, CACHEWSTRP rbuf)
Arguments

code The error code.
rbuf Address of a CACHEWSTR variable to contain the Caché error string. The len field should be loaded with the maximum string size that can be returned.
Description

Translates error code code into a Cache error string, and writes that string into the structure pointed to by rbuf

Return Values for CacheErrxlateW

CACHE_ERUNKNOWN The specified code is less than 1 (in the range of the Callin interface errors) or is above the largest Caché error number.
CACHE_RETTRUNC The associated error string was truncated to fit in the allocated area.
CACHE_SUCCESS Connection formed.
Example

CACHEWSTR retval; /* define variable retval */
retval.len = 30; /* maximum return length of string */
rc = CacheErrxlateW(CACHE_ERSTORE,&retval);

CacheEvalA

Variants: CacheEvalW, CacheEvalH

int CacheEvalA(CACHE_ASTRP volatile expr)
Arguments

expr The address of a CACHE_ASTR variable.
Description

Evaluates a string as if it were a Caché expression and places the return value in memory for further processing by CacheType and CacheConvert.

If CacheEvalA completes successfully, it sets a flag that allows calls to CacheType and CacheConvert to complete. These functions are used to process the item returned from CacheEvalA.

Caution:

The next call to CacheEvalA, CacheExecuteA, or CacheEnd will overwrite the existing return value.

Return Values for CacheEvalA

CACHE_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
CACHE_ERSYSTEM Either Caché generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_NOCON No connection has been established.
CACHE_STRTOOLONG String is too long.
CACHE_SUCCESS String evaluated successfully.

CacheEvalA can also return any of the Caché error codes.

Example

int rc;
CACHE_ASTR retval;
CACHE_ASTR expr;

strcpy(expr.str, "\"Record\"_^Recnum_\" = \"_$$^GetRec(^Recnum)");
expr.len = strlen(expr.str);
rc = CacheEvalA(&expr);
if (rc == CACHE_SUCCESS) 
    rc = CacheConvert(CACHE_ASTRING,&retval);

CacheEvalH

Variants: CacheEvalA, CacheEvalW

int CacheEvalH(CACHEHSTRP volatile expr)
Arguments

expr The address of a CACHEHSTRP variable.
Description

Evaluates a string as if it were a Caché expression and places the return value in memory for further processing by CacheType and CacheConvert.

If CacheEvalH completes successfully, it sets a flag that allows calls to CacheType and CacheConvert to complete. These functions are used to process the item returned from CacheEvalA.

Caution:

The next call to CacheEvalH, CacheExecuteH, or CacheEnd will overwrite the existing return value.

Return Values for CacheEvalH

CACHE_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
CACHW_ERSYSTEM Either Caché generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_NOCON No connection has been established.
CACHE_STRTOOLONG String is too long.
CACHE_SUCCESS String evaluated successfully.

CacheEvalH can also return any of the Caché error codes.

Example

int rc;
CACHEHSTRP retval; 
CACHEHSTRP expr;

strcpy(expr.str, "\"Record\"_^Recnum_\" = \"_$$^GetRec(^Recnum)");
expr.len = strlen(expr.str);
rc = CacheEvalH(&expr);
if (rc == CACHE_SUCCESS) 
    rc = CacheConvert(ING,&retval);

CacheEvalW

Variants: CacheEvalA, CacheEvalH

int CacheEvalW(CACHEWSTRP volatile expr)
Arguments

expr The address of a CACHEWSTR variable.
Description

Evaluates a string as if it were a Caché expression and places the return value in memory for further processing by CacheType and CacheConvert.

If CacheEvalW completes successfully, it sets a flag that allows calls to CacheType and CacheConvert to complete. These functions are used to process the item returned from CacheEvalA.

Caution:

The next call to CacheEvalW, CacheExecuteW, or CacheEnd will overwrite the existing return value.

Return Values for CacheEvalW

CACHE_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
CACHW_ERSYSTEM Either Caché generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_NOCON No connection has been established.
CACHE_STRTOOLONG String is too long.
CACHE_SUCCESS String evaluated successfully.

CacheEvalW can also return any of the Caché error codes.

Example

int rc;
CACHEWSTR retval; 
CACHEWSTR expr;

strcpy(expr.str, "\"Record\"_^Recnum_\" = \"_$$^GetRec(^Recnum)");
expr.len = strlen(expr.str);
rc = CacheEvalW(&expr);
if (rc == CACHE_SUCCESS) 
    rc = CacheConvert(ING,&retval);

CacheExecuteA

Variants: CacheExecuteW, CacheExecuteH

int CacheExecuteA(CACHE_ASTRP volatile cmd)
Arguments

cmd The address of a CACHE_ASTR variable.
Description

Executes the command string as if it were typed at the Caché programmer prompt.

Caution:

The next call to CacheEvalA, CacheExecuteA, or CacheEnd will overwrite the existing return value.

Return Values for CacheExecuteA

CACHE_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
CACHE_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_NOCON No connection has been established.
CACHE_STRTOOLONG String is too long.
CACHE_SUCCESS String executed successfully.

CacheExecuteA can also return any of the Caché error codes.

Example

int rc;
CACHE_ASTR command;
sprintf(command.str,"ZN \"USER\""); /* changes namespace */
command.len = strlen(command.str);
rc = CacheExecuteA(&command);

CacheExecuteH

Variants: CacheExecuteA, CacheExecuteW

int CacheExecuteH(CACHEHSTRP volatile cmd)
Arguments

cmd The address of a CACHE_ASTR variable.
Description

Executes the command string as if it were typed at the Caché programmer prompt.

If CacheExecuteH completes successfully, it sets a flag that allows calls to CacheType and CacheConvert to complete. These functions are used to process the item returned from CacheEvalH.

Caution:

The next call to CacheEvalH, CacheExecuteH, or CacheEnd will overwrite the existing return value.

Return Values for CacheExecuteH

CACHE_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
CACHE_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_NOCON No connection has been established.
CACHE_STRTOOLONG String is too long.
CACHE_SUCCESS String executed successfully.

CacheExecuteH can also return any of the Caché error codes.

Example

int rc;
unsigned short zname[] = {'Z','N',' ','"','U','S','E','R','"'};
CACHEHSTRP pcommand;
pcommand.str = zname;
pcommand.len = sizeof(zname) / sizeof(unsigned short);
rc = CacheExecuteH(pcommand);

CacheExecuteW

Variants: CacheExecuteA, CacheExecuteH

int CacheExecuteW(CACHEWSTRP volatile cmd)
Arguments

cmd The address of a CACHE_ASTR variable.
Description

Executes the command string as if it were typed at the Caché programmer prompt.

If CacheExecuteW completes successfully, it sets a flag that allows calls to CacheType and CacheConvert to complete. These functions are used to process the item returned from CacheEvalW.

Caution:

The next call to CacheEvalW, CacheExecuteW, or CacheEnd will overwrite the existing return value.

Return Values for CacheExecuteW

CACHE_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
CACHE_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_NOCON No connection has been established.
CACHE_STRTOOLONG String is too long.
CACHE_SUCCESS String executed successfully.

CacheExecuteW can also return any of the Caché error codes.

Example

int rc;
unsigned short zname[] = {'Z','N',' ','"','U','S','E','R','"'};
CACHEWSTRP pcommand;
pcommand.str = zname;
pcommand.len = sizeof(zname) / sizeof(unsigned short);
rc = CacheExecuteW(pcommand);

CacheExStrKill

int CacheExStrKill(CACHE_EXSTRP obj)
Arguments

obj Pointer to the string.
Description

Releases the storage associated with an EXSTR string.

Return Values for CacheExStrKill

CACHE_ERUNIMPLEMENTED String is undefined.
CACHE_SUCCESS String storage has been released.

CacheExStrNew

Variants: CacheExStrNewW, CacheExStrNewH

unsigned char * CacheExStrNew(CACHE_EXSTRP zstr, int size)
Arguments

zstr Pointer to a CACHE_EXSTR string descriptor.
size Number of 8–bit characters to allocate.
Description

Allocates the requested amount of storage for a string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure.

Return Values for CacheExStrNew

Returns a pointer to the allocated string, or NULL if no string was allocated.

CacheExStrNewW

Variants: CacheExStrNew, CacheExStrNewH

unsigned short * CacheExStrNewW(CACHE_EXSTRP zstr, int size)
Arguments

zstr Pointer to a CACHE_EXSTR string descriptor.
size Number of 2–byte characters to allocate.
Description

Allocates the requested amount of storage for a string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure.

Return Values for CacheExStrNewW

Returns a pointer to the allocated string, or NULL if no string was allocated.

CacheExStrNewH

Variants: CacheExStrNew, CacheExStrNewW

unsigned short * CacheExStrNewH(CACHE_EXSTRP zstr, int size)
Arguments

zstr Pointer to a CACHE_EXSTR string descriptor.
size Number of 4–byte characters to allocate.
Description

Allocates the requested amount of storage for a string, and fills in the EXSTR structure with the length and a pointer to the value field of the structure.

Return Values for CacheExStrNewH

Returns a pointer to the allocated string, or NULL if no string was allocated.

CacheExtFun

int CacheExtFun(unsigned int flags, int narg)
Arguments

flags Routine flags from CachePushFunc[XW].
narg Number of call arguments pushed onto the argument stack.
Description

Performs an extrinsic function call where the return value is pushed onto the argument stack.

Return Values for CacheExtFun

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_FAILURE Internal consistency error.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGetProperty

int CacheGetProperty()
Description

Obtains the value of the property defined by CachePushProperty. The value is pushed onto the argument stack.

Return Values for CacheGetProperty

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGlobalData

int CacheGlobalData(int narg, int valueflag)
Arguments

narg Number of call arguments pushed onto the argument stack.
valueflag Indicates whether the data value, if there is one, should be returned.
Description

Performs a $Data on the specified global.

Return Values for CacheGlobalData

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_ERPROTECT Protection violation.
CACHE_ERUNDEF Node has no associated value.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGlobalGet

int CacheGlobalGet(int narg, int flag)
Arguments

narg Number of subscript expressions pushed onto the argument stack.
flag Indicates behavior when global reference is undefined:
  • 0 — returns CACHE_ERUNDEF

  • 1 — returns CACHE_SUCCESS but the return value is an empty string.

Description

Obtains the value of the global reference defined by CachePushGlobal and any subscripts. The node value is pushed onto the argument stack.

Return Values for CacheGlobalGet

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_ERPROTECT Protection violation.
CACHE_ERUNDEF Node has no associated value.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGlobalGetBinary

int CacheGlobalGetBinary(int numsub, int flag, int *plen, Callin_char_t **pbuf)
Arguments

numsub Number of subscript expressions pushed onto the argument stack.
flag Indicates behavior when global reference is undefined:
  • 0 — returns CACHE_ERUNDEF

  • 1 — returns CACHE_SUCCESS but the return value is an empty string.

plen Pointer to length of buffer.
pbuf Pointer to buffer pointer.
Description

Obtains the value of the global reference defined by CachePushGlobal[W][H] and any subscripts, and also tests to make sure that the result is a binary string that will fit in the provided buffer. The node value is pushed onto the argument stack.

Return Values for CacheGlobalGetBinary

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_ERPROTECT Protection violation.
CACHE_ERUNDEF Node has no associated value.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGlobalIncrement

int CacheGlobalIncrement(int narg)
Arguments

narg Number of call arguments pushed onto the argument stack.
Description

Performs a $INCREMENT and returns the result on top of the stack.

Return Values for CacheGlobalIncrement

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_ERPROTECT Protection violation.
CACHE_ERUNDEF Node has no associated value.
CACHE_ERMAXINCR MAXINCREMENT system error
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGlobalKill

int CacheGlobalKill(int narg, int nodeonly)
Arguments

narg Number of call arguments pushed onto the argument stack.
nodeonly A value of 1 indicates that only the specified node should be killed. When the value is 0, the entire specified global tree is killed.
Description

Performs a ZKILL on a global node or tree.

Return Values for CacheGlobalKill

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_ERPROTECT Protection violation.
CACHE_ERUNDEF Node has no associated value.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGlobalOrder

int CacheGlobalOrder(int narg, int dir, int valueflag)
Arguments

narg Number of call arguments pushed onto the argument stack.
dir Direction for the $Order is 1 for forward, -1 for reverse.
valueflag Indicates whether the data value, if there is one, should be returned.
Description

Performs a $Order on the specified global.

Return Values for CacheGlobalOrder

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_ERPROTECT Protection violation.
CACHE_ERUNDEF Node has no associated value.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGlobalQuery

int CacheGlobalQuery(int narg, int dir, int valueflag)
Arguments

narg Number of call arguments pushed onto the argument stack.
dir Direction for the $Query is 1 for forward, -1 for reverse.
valueflag Indicates whether the data value, if there is one, should be returned.
Description

Performs a $Query on the specified global.

Return Values for CacheGlobalQuery

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_ERPROTECT Protection violation.
CACHE_ERUNDEF Node has no associated value.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheGlobalRelease

int CacheGlobalRelease( )
Description

Release ownership of a retained global buffer, if one exists.

Return Values for CacheGlobalRelease

CACHE_SUCCESS The operation was successful.

CacheGlobalSet

int CacheGlobalSet(int narg)
Arguments

narg Number of subscript expressions pushed onto the argument stack.
Description

Stores the value of the global reference defined by CachePushGlobal and any subscripts. The node value must be pushed onto the argument stack before this call.

Return Values for CacheGlobalSet

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheIncrementCountOref

int CacheIncrementCountOref(unsigned int oref)
Arguments

oref Object reference.
Description

Increments the system reference counter for an OREF.

Return Values for CacheIncrementCountOref

CACHE_ERBADOREF Invalid OREF.
CACHE_SUCCESS The operation was successful.

CacheInvokeClassMethod

int CacheInvokeClassMethod(int narg)
Arguments

narg Number of call arguments pushed onto the argument stack.
Description

Executes the class method call defined by CachePushClassMethod[W] and any arguments. The return value is pushed onto the argument stack.

Return Values for CacheInvokeClassMethod

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheInvokeMethod

int CacheInvokeMethod(int narg)
Arguments

narg Number of call arguments pushed onto the argument stack.
Description

Executes the instance method call defined by CachePushMethod[W] and any arguments pushed onto the argument stack.

Return Values for CacheInvokeMethod

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheOflush

int CacheOflush()
Description

Flushes any pending output.

Return Values for CacheOflush

CACHE_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
CACHE_SUCCESS Control function performed.

CachePop

int CachePop(void ** arg)
Arguments

arg Pointer to argument stack entry.
Description

Pops a value off argument stack.

Return Values for CachePop

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_SUCCESS The operation was successful.

CachePopCvtH

Variants: CachePopCvtW

int CachePopCvtH(int * lenp, wchar_t ** strp)
Arguments

lenp Pointer to length of string.
strp Pointer to string pointer.
Description

Pops a local 8-bit string off argument stack and translates it to 4–byte Unicode. Identical to CachePopStrH in Unicode environments.

Return Values for CachePopCvtH

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePopCvtW

Variants: CachePopCvtH

int CachePopCvtW(int * lenp, unsigned short ** strp)
Arguments

lenp Pointer to length of string.
strp Pointer to string pointer.
Description

Deprecated: The long string function CachePopExStrCvtW should be used for all strings.

Pops a local 8-bit string off argument stack and translates it to 2–byte Unicode. Identical to CachePopStrW in Unicode environments.

Return Values for CachePopCvtW

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePopDbl

int CachePopDbl(double * nump)
Arguments

nump Pointer to double value.
Description

Pops a value off argument stack and converts it to a double.

Return Values for CachePopDbl

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_SUCCESS The operation was successful.

CachePopExStr

Variants: CachePopExStrW, CachePopExStrH

int CachePopExStr(CACHE_EXSTRP sstrp)
Arguments

sstrp Pointer to long string pointer.
Description

Pops a value off argument stack and converts it to a string in local 8–bit encoding.

Return Values for CachePopExStr

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_SUCCESS The operation was successful.
CACHE_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.

CachePopExStrCvtW

Variants: CachePopExStrCvtH

int CachePopExStrCvtW(CACHE_EXSTRP sstr)
Arguments

sstr Pointer to long string pointer.
Description

Pops a local 8-bit string off the argument stack and translates it to a 2–byte Unicode string. On Unicode systems, this is the same as CachePopExStrW.

Return Values for CachePopExStrCvtW

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePopExStrCvtH

Variants: CachePopExStrCvtW

int CachePopExStrCvtW(CACHE_EXSTRP sstr)
Arguments

sstr Pointer to long string pointer.
Description

Pops a local 8-bit string off argument stack and translates it to a 4–byte Unicode string. On Unicode systems, this is the same as CachePopExStrH.

Return Values for CachePopExStrCvtH

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePopExStrW

Variants: CachePopExStr, CachePopExStrH

int CachePopExStrW(CACHE_EXSTRP sstrp)
Arguments

sstrp Pointer to long string pointer.
Description

Pops a value off argument stack and converts it to a 2–byte Unicode string.

Return Values for CachePopExStrW

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
CACHE_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.

CachePopExStrH

Variants: CachePopExStr, CachePopExStrW

int CachePopExStrH(CACHE_EXSTRP sstrp)
Arguments

sstrp Pointer to long string pointer.
Description

Pops a value off argument stack and converts it to a 4–byte Unicode string.

Return Values for CachePopExStrH

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
CACHE_EXSTR_INUSE Returned if sstrp has not been initialized to NULL.

CachePopInt

int CachePopInt(int* nump)
Arguments

nump Pointer to integer value.
Description

Pops a value off argument stack and converts it to an integer.

Return Values for CachePopInt

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_SUCCESS The operation was successful.

CachePopInt64

int CachePopInt64(long long * nump)
Arguments

nump Pointer to long long value.
Description

Pops a value off argument stack and converts it to a 64–bit (long long) value.

Return Values for CachePopInt64

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_SUCCESS The operation was successful.

CachePopList

int CachePopList(int * lenp, Callin_char_t ** strp)
Arguments

lenp Pointer to length of string.
strp Pointer to string pointer.
Description

Pops a $LIST object off argument stack and converts it. String elements are copied or translated as appropriate depending on whether this is a Unicode or 8-bit version.

Return Values for CachePopList

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePopOref

int CachePopOref(unsigned int * orefp)
Arguments

orefp Pointer to OREF value.
Description

Pops an OREF off argument stack.

Return Values for CachePopOref

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERNOOREF Result is not an OREF.
CACHE_SUCCESS The operation was successful.

CachePopPtr

int CachePopPtr(void ** ptrp)
Arguments

ptrp Pointer to generic pointer.
Description

Pops a pointer off argument stack in internal format.

Return Values for CachePopPtr

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_BADARG The entry is not a valid pointer.
CACHE_SUCCESS The operation was successful.

CachePopStr

Variants: CachePopStrW, CachePopStrH

int CachePopStr(int * lenp, Callin_char_t ** strp)
Arguments

lenp Pointer to length of string.
strp Pointer to string pointer.
Description

Pops a value off argument stack and converts it to a string.

Return Values for CachePopStr

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_SUCCESS The operation was successful.

CachePopStrH

Variants: CachePopStr, CachePopStrW

int CachePopStrH(int * lenp, wchar_t ** strp)
Arguments

lenp Pointer to length of string.
strp Pointer to string pointer.
Description

Pops a value off argument stack and converts it to a 4-byte Unicode string.

Return Values for CachePopStrH

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePopStrW

Variants: CachePopStr, CachePopStrH

int CachePopStrW(int * lenp, unsigned short ** strp)
Arguments

lenp Pointer to length of string.
strp Pointer to string pointer.
Description

Pops a value off argument stack and converts it to a 2-byte Unicode string.

Return Values for CachePopStrW

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePromptA

Variants: CachePromptW, CachePromptH

int CachePromptA(CACHE_ASTRP rbuf)
Arguments

rbuf The prompt string. The minimum length of the returned string is five characters.
Description

Returns a string that would be the programmer prompt (without the “>”).

Return Values for CachePromptA

CACHE_CONBROKEN Connection has been broken.
CACHE_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_FAILURE An unexpected error has occurred.
CACHE_NOCON No connection has been established.
CACHE_RETTOOSMALL rbuf must have a length of at least five.
CACHE_SUCCESS Connection formed.
Example

CACHE_ASTR retval;      /* define variable retval */
retval.len = 5;         /* maximum return length of string */
rc = CachePromptA(&retval);

CachePromptH

Variants: CachePromptA, CachePromptW

int CachePromptH(CACHEHSTRP rbuf)
Arguments

rbuf The prompt string. The minimum length of the returned string is five characters.
Description

Returns a string that would be the programmer prompt (without the “>”).

Return Values for CachePromptH

CACHE_CONBROKEN Connection has been broken.
CACHE_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_FAILURE Request failed.
CACHE_NOCON No connection has been established.
CACHE_RETTOOSMALL rbuf must have a length of at least five.
CACHE_SUCCESS Connection formed.
Example

CACHEHSTRP retval; /* define variable retval */
retval.len = 5; /* maximum return length of string */
rc = CachePromptH( &retval);

CachePromptW

Variants: CachePromptA, CachePromptH

int CachePromptW(CACHEWSTRP rbuf)
Arguments

rbuf The prompt string. The minimum length of the returned string is five characters.
Description

Returns a string that would be the programmer prompt (without the “>”).

Return Values for CachePromptW

CACHE_CONBROKEN Connection has been broken.
CACHE_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_FAILURE Request failed.
CACHE_NOCON No connection has been established.
CACHE_RETTOOSMALL rbuf must have a length of at least five.
CACHE_SUCCESS Connection formed.
Example

CACHEWSTR retval; /* define variable retval */
retval.len = 5; /* maximum return length of string */
rc = CacheConvertW( &retval);

CachePushClassMethod

Variants: CachePushClassMethodW, CachePushClassMethodH

int CachePushClassMethod(int clen, const Callin_char_t * cptr, 
                         int mlen, const Callin_char_t * mptr, int flg)
Arguments

clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg

Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.

Description

Pushes a class method reference onto the argument stack.

Return Values for CachePushClassMethod

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.

CachePushClassMethodH

Variants: CachePushClassMethod, CachePushClassMethodW

int CachePushClassMethodH(int clen, const wchar_t * cptr, 
                          int mlen, const wchar_t * mptr, int flg)
Arguments

clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description

Pushes a 4-byte Unicode class method reference onto the argument stack.

Return Values for CachePushClassMethodH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushClassMethodW

Variants: CachePushClassMethod, CachePushClassMethodH

int CachePushClassMethodW(int clen, const unsigned short * cptr, 
                          int mlen, const unsigned short * mptr, int flg)
Arguments

clen Class name length (characters).
cptr Pointer to class name.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description

Pushes a 2-byte Unicode class method reference onto the argument stack.

Return Values for CachePushClassMethodW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushCvtH

Variants: CachePushCvtW

int CachePushCvtH(int len, const wchar_t * ptr)
Arguments

len Number of characters in string.
ptr Pointer to string.
Description

Translates a Unicode string to local 8-bit and pushes it onto the argument stack. Identical to CachePushStrH for Unicode versions.

Return Values for CachePushCvtH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating the string.

CachePushCvtW

Variants: CachePushCvtH

int CachePushCvtW(int len, const unsigned short * ptr)
Arguments

len Number of characters in string.
ptr Pointer to string.
Description

Deprecated: The long string function CachePushExStrCvtW should be used for all strings.

Translates a Unicode string to local 8-bit and pushes it onto the argument stack. Identical to CachePushStrW for Unicode versions.

Return Values for CachePushCvtW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating the string.

CachePushDbl

int CachePushDbl(double num)
Arguments

num Double value.
Description

Pushes a Caché double onto the argument stack.

Return Values for CachePushDbl

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushExStr

Variants: CachePushExStrW, CachePushExStrH

int CachePushExStr(CACHE_EXSTRP sptr)
Arguments

sptr Pointer to the argument value.
Description

Pushes a string onto the argument stack.

Return Values for CachePushExStr

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushExStrCvtW

Variants: CachePushExStrCvtH

int CachePushExStrCvtW(CACHE_EXSTRP sptr)
Arguments

sptr Pointer to the argument value.
Description

Translates a Unicode string to local 8-bit and pushes it onto the argument stack.

Return Values for CachePushExStrCvtW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating the string.

CachePushExStrCvtH

Variants: CachePushExStrCvtW

int CachePushExStrCvtH(CACHE_EXSTRP sptr)
Arguments

sptr Pointer to the argument value.
Description

Translates a 4–byte Unicode string to local 8-bit and pushes it onto the argument stack.

Return Values for CachePushExStrCvtH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating the string.

CachePushExStrW

Variants: CachePushExStr, CachePushExStrH

int CachePushExStrW(CACHE_EXSTRP sptr)
Arguments

sptr Pointer to the argument value.
Description

Pushes a long Unicode string onto the argument stack.

Return Values for CachePushExStrW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushExStrH

Variants: CachePushExStr, CachePushExStrW

int CachePushExStrH(CACHE_EXSTRP sptr)
Arguments

sptr Pointer to the argument value.
Description

Pushes a 4–byte Unicode string onto the argument stack.

Return Values for CachePushExStrH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushFunc

Variants: CachePushFuncW, CachePushFuncH

int CachePushFunc(unsigned int * rflag, int tlen, const Callin_char_t * tptr, 
                  int nlen, const Callin_char_t * nptr)
Arguments

rflag Routine flags for use by CacheExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tagptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes an extrinsic function reference onto the argument stack.

Return Values for CachePushFunc

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushFuncH

Variants: CachePushFunc, CachePushFuncW

int CachePushFuncH(unsigned int * rflag, int tlen, const wchar_t * tptr, 
                   int nlen, const wchar_t * nptr)
Arguments

rflag Routine flags for use by CacheExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 4-byte Unicode extrinsic function reference onto the argument stack.

Return Values for CachePushFuncH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushFuncW

Variants: CachePushFunc, CachePushFuncH

int CachePushFuncW(unsigned int * rflag, int tlen, const unsigned short * tptr, 
                   int nlen, const unsigned short * nptr)
Arguments

rflag Routine flags for use by CacheExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 2-byte Unicode extrinsic function reference onto the argument stack.

Return Values for CachePushFuncW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushFuncX

Variants: CachePushFuncXW, CachePushFuncXH

int CachePushFuncX(unsigned int * rflag, int tlen, const Callin_char_t * tptr, int off, 
                   int elen, const Callin_char_t * eptr, 
                   int nlen, const Callin_char_t * nptr)
Arguments

rflag Routine flags for use by CacheExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes an extended extrinsic function reference onto the argument stack.

Return Values for CachePushFuncX

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushFuncXH

Variants: CachePushFuncX, CachePushFuncXW

int CachePushFuncXH(unsigned int * rflag, int tlen, const wchar_t * tptr, int off, 
                    int elen, const wchar_t * eptr, int nlen, const wchar_t * nptr)
Arguments

rflag Routine flags for use by CacheExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 4-byte Unicode extended function routine reference onto the argument stack.

Return Values for CachePushFuncXH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushFuncXW

Variants: CachePushFuncX, CachePushFuncXH

int CachePushFuncXW(unsigned int * rflag, int tlen, const unsigned short * tptr, int off, 
                    int elen, const unsigned short * eptr, 
                    int nlen, const unsigned short * nptr)
Arguments

rflag Routine flags for use by CacheExtFun.
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 2-byte Unicode extended function routine reference onto the argument stack.

Return Values for CachePushFuncXW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushGlobal

Variants: CachePushGlobalW, CachePushGlobalH

int CachePushGlobal(int nlen, const Callin_char_t * nptr)
Arguments

nlen Global name length (characters).
nptr Pointer to global name.
Description

Pushes a global reference onto the argument stack.

Return Values for CachePushGlobal

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushGlobalH

Variants: CachePushGlobal, CachePushGlobalW

intCachePushGlobalH(int nlen, const wchar_t * nptr)
Arguments

nlen Global name length (characters).
nptr Pointer to global name.
Description

Pushes a 4-byte Unicode global reference onto the argument stack.

Return Values for CachePushGlobalH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushGlobalW

Variants: CachePushGlobal, CachePushGlobalH

int CachePushGlobalW(int nlen, const unsigned short * nptr)
Arguments

nlen Global name length (characters).
nptr Pointer to global name.
Description

Pushes a 2-byte Unicode global reference onto the argument stack.

Return Values for CachePushGlobalW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushGlobalX

Variants: CachePushGlobalXW, CachePushGlobalXH

int CachePushGlobalX(int nlen, const Callin_char_t * nptr, 
                     int elen, const Callin_char_t * eptr)
Arguments

nlen Global name length (characters).
nptr Pointer to global name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes an extended global reference onto the argument stack.

Return Values for CachePushGlobalX

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushGlobalXH

Variants: CachePushGlobalX, CachePushGlobalXW

int CachePushGlobalXH(int nlen, const wchar_t * nptr, int elen, const wchar_t * eptr)
Arguments

nlen Global name length (characters).
nptr Pointer to global name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 4-byte Unicode extended global reference onto the argument stack.

Return Values for CachePushGlobalXH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTAC String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushGlobalXW

Variants: CachePushGlobalX, CachePushGlobalXH

int CachePushGlobalXW(int nlen, const unsigned short * nptr, 
                      int elen, const unsigned short * eptr)
Arguments

nlen Global name length (characters).
nptr Pointer to global name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 2-byte Unicode extended global reference onto the argument stack.

Return Values for CachePushGlobalXW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTAC String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushIEEEDbl

int CachePushIEEEDbl(double num)
Arguments

num Double value.
Description

Pushes an IEEE double onto the argument stack.

Return Values for CachePushIEEEDbl

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushInt

int CachePushInt(int num)
Arguments

num Integer value.
Description

Pushes an integer onto the argument stack.

Return Values for CachePushInt

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushInt64

int CachePushInt64(long long num)
Arguments

num long long value.
Description

Pushes a 64–bit (long long) value onto the argument stack.

Return Values for CachePushInt64

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushList

int CachePushList(int len, const Callin_char_t * ptr)
Arguments

len Number of characters in string.
ptr Pointer to string.
Description

Converts a $LIST object and pushes it onto the argument stack. String elements are copied or translated as appropriate depending on whether this is a Unicode or 8-bit version.

Return Values for CachePushList

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a string element.

CachePushLock

Variants: CachePushLockW, CachePushLockH

int CachePushLock(int nlen, const Callin_char_t * nptr)
Arguments

nlen Length (in bytes) of lock name.
nptr Pointer to lock name.
Description

Initializes a CacheAcquireLock command by pushing the lock name on the argument stack.

Return Values for CachePushLock

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushLockH

Variants: CachePushLock, CachePushLockW

int CachePushLockH(int nlen, const wchar_t * nptr)
Arguments

nlen Length (number of 2–byte or 4–byte characters) of lock name.
nptr Pointer to lock name.
Description

Initializes a CacheAcquireLock command by pushing the lock name on the argument stack.

Return Values for CachePushLockH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushLockW

Variants: CachePushLock, CachePushLockH

int CachePushLockW(int nlen, const unsigned short * nptr)
Arguments

nlen Length (number of 2–byte characters) of lock name.
nptr Pointer to lock name.
Description

Initializes a CacheAcquireLock command by pushing the lock name on the argument stack.

Return Values for CachePushLockW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushLockX

Variants: CachePushLockXW, CachePushLockXH

int CachePushLockX(int nlen, const Callin_char_t * nptr, int elen, const Callin_char_t * eptr)
Arguments

nlen Length (number of 8–bit characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description

Initializes a CacheAcquireLock command by pushing the lock name and an environment string on the argument stack.

Return Values for CachePushLockX

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushLockXH

Variants: CachePushLockX, CachePushLockXW

int CachePushLockXH(int nlen, const wchar_t * nptr, int elen, const wchar_t * eptr)
Arguments

nlen Length (number of 2–byte or 4–byte characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description

Initializes a CacheAcquireLock command by pushing the lock name and an environment string on the argument stack.

Return Values for CachePushLockXH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushLockXW

Variants: CachePushLockX, CachePushLockXH

int CachePushLockXW(int nlen, const unsigned short * nptr, int elen, const unsigned short * eptr)
Arguments

nlen Length (number of 2–byte characters) of lock name.
nptr Pointer to lock name.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment. Name must be of the form <Namespace>^[<system>]^<directory>
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
Description

Initializes a CacheAcquireLock command by pushing the lock name and an environment string on the argument stack.

Return Values for CachePushLockXW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushMethod

Variants: CachePushMethodW, CachePushMethodH

int CachePushMethod(unsigned int oref, int mlen, const Callin_char_t * mptr, int flg)
Arguments

oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description

Pushes an instance method reference onto the argument stack.

Return Values for CachePushMethod

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.

CachePushMethodH

Variants: CachePushMethod, CachePushMethodW

int CachePushMethodH(unsigned int oref, int mlen, const wchar_t * mptr, int flg)
Arguments

oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description

Pushes a 4-byte Unicode instance method reference onto the argument stack.

Return Values for CachePushMethodH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushMethodW

Variants: CachePushMethod, CachePushMethodH

int CachePushMethodW(unsigned int oref, int mlen, const unsigned short * mptr, int flg)
Arguments

oref Object reference.
mlen Method name length (characters).
mptr Pointer to method name.
flg Specifies whether the method will return a value. If the method returns a value, this flag must be set to 1 in order to retrieve it. The method must return a value via Quit with an argument. Set this parameter to 0 if no value will be returned.
Description

Pushes a 2-byte Unicode instance method reference onto the argument stack.

Return Values for CachePushMethodW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushOref

int CachePushOref(unsigned int oref)
Arguments

oref Object reference.
Description

Pushes an OREF onto the argument stack.

Return Values for CachePushOref

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERBADOREF Invalid OREF.
CACHE_SUCCESS The operation was successful.

CachePushProperty

Variants: CachePushPropertyW, CachePushPropertyH

int CachePushProperty(unsigned int oref, int plen, const Callin_char_t * pptr)
Arguments

oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description

Pushes a property reference onto the argument stack.

Return Values for CachePushProperty

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.

CachePushPropertyH

Variants: CachePushProperty, CachePushPropertyW

int CachePushPropertyH(unsigned int oref, int plen, const wchar_t * pptr)
Arguments

oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description

Pushes a 4-byte Unicode property reference onto the argument stack.

Return Values for CachePushPropertyH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushPropertyW

Variants: CachePushProperty, CachePushPropertyH

int CachePushPropertyW(unsigned int oref, int plen, const unsigned short * pptr)
Arguments

oref Object reference.
plen Property name length (characters).
pptr Pointer to property name.
Description

Pushes a 2-byte Unicode property reference onto the argument stack.

Return Values for CachePushPropertyW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_BADARG Invalid call argument.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushPtr

int CachePushPtr(void * ptr)
Arguments

ptr Generic pointer.
Description

Pushes a pointer onto the argument stack in internal format.

Return Values for CachePushPtr

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushRtn

Variants: CachePushRtnW, CachePushRtnH

int CachePushRtn(unsigned int * rflag, int tlen, const Callin_char_t * tptr, 
                 int nlen, const Callin_char_t * nptr)
Arguments

rflag Routine flags for use by CacheDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a routine reference onto the argument stack. See CachePushRtnX for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.

Return Values for CachePushRtn

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushRtnH

Variants: CachePushRtn, CachePushRtnW

int CachePushRtnH(unsigned int * rflag, int tlen, const wchar_t * tptr, 
                  int nlen, const wchar_t * nptr)
Arguments

rflag Routine flags for use by CacheDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 4–byte Unicode routine reference onto the argument stack. See CachePushRtnXH for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.

Return Values for CachePushRtnH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushRtnW

Variants: CachePushRtn, CachePushRtnH

int CachePushRtnW(unsigned int * rflag, int tlen, const unsigned short * tptr, 
                  int nlen, const unsigned short * nptr)
Arguments

rflag Routine flags for use by CacheDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 2–byte Unicode routine reference onto the argument stack. See CachePushRtnXW for a version that takes all arguments. This is a short form that only takes a tag name and a routine name.

Return Values for CachePushRtnW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushRtnX

Variants: CachePushRtnXW, CachePushRtnXH

int CachePushRtnX(unsigned int * rflag, int tlen, const Callin_char_t * tptr, 
                  int off, int elen, const Callin_char_t * eptr, 
                  int nlen, const Callin_char_t * nptr)
Arguments

rflag Routine flags for use by CacheDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes an extended routine reference onto the argument stack. See CachePushRtn for a short form that only takes a tag name and a routine name.

Return Values for CachePushRtnX

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushRtnXH

Variants: CachePushRtnX, CachePushRtnXW

int CachePushRtnXH(unsigned int * rflag, int tlen, const wchar_t * tptr, 
                   int off, int elen, const wchar_t * eptr, 
                   int nlen, const wchar_t * nptr)
Arguments

rflag Routine flags for use by CacheDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 4–byte Unicode extended routine reference onto the argument stack. See CachePushRtnH for a short form that only takes a tag name and a routine name.

Return Values for CachePushRtnXH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushRtnXW

Variants: CachePushRtnX, CachePushRtnXH

int CachePushRtnXW(unsigned int * rflag, int tlen, const unsigned short * tptr, 
                   int off, int elen, const unsigned short * eptr, 
                   int nlen, const unsigned short * nptr)
Arguments

rflag Routine flags for use by CacheDoRtn
tlen Tag name length (characters), where 0 means that the tag name is null ("").
tptr Pointer to a tag name. If tlen == 0, then tptr is unused and (void *) 0 may be used as the pointer value.
off Line offset from specified tag, where 0 means that there is no offset.
elen Environment name length (characters), where 0 means that there is no environment specified and that the function uses the current environment.
eptr Pointer to environment name. If elen == 0, then eptr is unused and (void *) 0 may be used as the pointer value.
nlen Routine name length (characters), where 0 means that the routine name is null ("") and the current routine name is used.
nptr Pointer to routine name. If nlen == 0, then nptr is unused and (void *) 0 may be used as the pointer value.
Description

Pushes a 2–byte Unicode extended routine reference onto the argument stack. See CachePushRtnW for a short form that only takes a tag name and a routine name.

Return Values for CachePushRtnXW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CachePushStr

Variants: CachePushStrW, CachePushStrH

int CachePushStr(int len, const Callin_char_t * ptr)
Arguments

len Number of characters in string.
ptr Pointer to string.
Description

Pushes a byte string onto the argument stack.

Return Values for CachePushStr

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushStrH

Variants: CachePushStr, CachePushStrW

int CachePushStrH(int len, const wchar_t * ptr)
Arguments

len Number of characters in string.
ptr Pointer to string.
Description

Pushes a 4-byte Unicode string onto the argument stack.

Return Values for CachePushStrH

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushStrW

Variants: CachePushStr, CachePushStrH

int CachePushStrW(int len, const unsigned short * ptr)
Arguments

len Number of characters in string.
ptr Pointer to string.
Description

Pushes a 2-byte Unicode string onto the argument stack.

Return Values for CachePushStrW

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.

CachePushUndef

int CachePushUndef()
Description

Pushes an Undefined value on the argument stack. The value is interpreted as an omitted function argument.

Return Values for CachePushUndef

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_SUCCESS The operation was successful.

CacheReleaseAllLocks

int CacheReleaseAllLocks( )
Description

Performs an argumentless Cache LOCK command to remove all locks currently held by the process.

Return Values for CacheReleaseAllLocks

CACHE_SUCCESS The operation was successful.

CacheReleaseLock

int CacheReleaseLock(int nsub, int flg)
Arguments

nsub Number of subscripts in the lock reference.
flg Modifiers to the lock command. Valid values are one or both of CACHE_IMMEDIATE_RELEASE and CACHE_SHARED_LOCK.
Description

Executes a Cache LOCK command to decrement the lock count for the specified lock name. This command will only release one incremental lock at a time.

Return Values for CacheReleaseLock

CACHE_FAILURE An unexpected error has occurred.
CACHE_SUCCESS Successful lock.

CacheSecureStartA

Variants: CacheSecureStartW, CacheSecureStartH

int CacheSecureStartA(CACHE_ASTRP username, CACHE_ASTRP password, CACHE_ASTRP exename, 
                      unsigned long flags, int tout, CACHE_ASTRP prinp, CACHE_ASTRP prout)
Arguments

username Username to authenticate. Use NULL to authenticate as UnknownUseror OS authentication or kerberos credentials cache.
password Password to authenticate with. Use NULL to authenticate as UnknownUser or OS authentication or kerberos credentials cache.
exename Callin executable name (or other process identifier). This user-defined string will show up in JOBEXAM and in audit records. NULL is a valid value.
flags One or more of the terminal settings listed below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for Caché. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for Caché. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description

Calls into Cache to set up a Cache process..

The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a Caché connection with the cache command, Caché does not open the principal input or output device until it is first used.

Valid values for the flags variable are:

  • CACHE_PROGMODE — Caché should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by Caché results in closing the connection and returning error CACHE_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)

  • CACHE_TTALL — Default. Caché should initialize the terminal's settings and restore them across each call into, and return from, the interface.

  • CACHE_TTCALLIN — Caché should initialize the terminal each time it is called but should restore it only when CacheEnd is called or the connection is broken.

  • CACHE_TTSTART — Caché should initialize the terminal when the connection is formed and reset it when the connection is terminated.

  • CACHE_TTNEVER — Caché should not alter the terminal's settings.

  • CACHE_TTNONE — Caché should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.

  • CACHE_TTNOUSE — This flag is allowed with CACHE_TTALL, CACHE_TTCALLIN, and CACHE_TTSTART. It is implicitly set by the flags CACHE_TTNEVER and CACHE_TTNONE. It indicates that Caché Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.

Return Values for CacheSecureStartA

CACHE_ACCESSDENIED Authentication has failed. Check the audit log for the real authentication error.
CACHE_ALREADYCON Connection already existed. Returned if you call CacheSecureStartH from a $ZF function.
CACHE_CHANGEPASSWORD Password change required. This return value is only returned if you are using Caché authentication.
CACHE_CONBROKEN Connection was formed and then broken, and CacheEnd has not been called to clean up.
CACHE_FAILURE An unexpected error has occurred.
CACHE_STRTOOLONG prinp or prout is too long.
CACHE_SUCCESS Connection formed.

The flags parameter(s) convey information about how your C program will behave and how you want Caché to set terminal characteristics. The safest, but slowest, route is to have Caché set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter CACHE_TTNEVER requires the least overhead.

CacheSecureStartH

Variants: CacheSecureStartA, CacheSecureStartW

int CacheSecureStartH(CACHEHSTRP username, CACHEHSTRP password, CACHEHSTRP exename, 
                      unsigned long flags, int tout, CACHEHSTRP prinp, CACHEHSTRP prout)
Arguments

username Username to authenticate. Use NULL to authenticate as UnknownUseror OS authentication or kerberos credentials cache.
password Password to authenticate with. Use NULL to authenticate as UnknownUser or OS authentication or kerberos credentials cache.
exename Callin executable name (or other process identifier). This user-defined string will show up in JOBEXAM and in audit records. NULL is a valid value.
flags One or more of the terminal settings listed below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for Caché. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for Caché. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description

Calls into Cache to set up a Cache process..

The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a Caché connection with the cache command, Caché does not open the principal input or output device until it is first used.

Valid values for the flags variable are:

  • CACHE_PROGMODE — Caché should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by Caché results in closing the connection and returning error CACHE_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)

  • CACHE_TTALL — Default. Caché should initialize the terminal's settings and restore them across each call into, and return from, the interface.

  • CACHE_TTCALLIN — Caché should initialize the terminal each time it is called but should restore it only when CacheEnd is called or the connection is broken.

  • CACHE_TTSTART — Caché should initialize the terminal when the connection is formed and reset it when the connection is terminated.

  • CACHE_TTNEVER — Caché should not alter the terminal's settings.

  • CACHE_TTNONE — Caché should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.

  • CACHE_TTNOUSE — This flag is allowed with CACHE_TTALL, CACHE_TTCALLIN, and CACHE_TTSTART. It is implicitly set by the flags CACHE_TTNEVER and CACHE_TTNONE. It indicates that Caché Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.

Return Values for CacheSecureStartH

CACHE_ACCESSDENIED Authentication has failed. Check the audit log for the real authentication error.
CACHE_ALREADYCON Connection already existed. Returned if you call CacheSecureStartH from a $ZF function.
CACHE_CHANGEPASSWORD Password change required. This return value is only returned if you are using Caché authentication.
CACHE_CONBROKEN Connection was formed and then broken, and CacheEnd has not been called to clean up.
CACHE_FAILURE An unexpected error has occurred.
CACHE_STRTOOLONG prinp or prout is too long.
CACHE_SUCCESS Connection formed.

The flags parameter(s) convey information about how your C program will behave and how you want Caché to set terminal characteristics. The safest, but slowest, route is to have Caché set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter CACHE_TTNEVER requires the least overhead.

CacheSecureStartW

Variants: CacheSecureStartA, CacheSecureStartH

int CacheSecureStartW(CACHEWSTRP username, CACHEWSTRP password, CACHEWSTRP exename, 
                      unsigned long flags, int tout, CACHEWSTRP prinp, CACHEWSTRP prout)
Arguments

username Username to authenticate. Use NULL to authenticate as UnknownUseror OS authentication or kerberos credentials cache.
password Password to authenticate with. Use NULL to authenticate as UnknownUser or OS authentication or kerberos credentials cache.
exename Callin executable name (or other process identifier). This user-defined string will show up in JOBEXAM and in audit records. NULL is a valid value.
flags One or more of the terminal settings listed below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for Caché. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for Caché. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description

Calls into Cache to set up a Cache process..

The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a Caché connection with the cache command, Caché does not open the principal input or output device until it is first used.

Valid values for the flags variable are:

  • CACHE_PROGMODE — Caché should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by Caché results in closing the connection and returning error CACHE_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)

  • CACHE_TTALL — Default. Caché should initialize the terminal's settings and restore them across each call into, and return from, the interface.

  • CACHE_TTCALLIN — Caché should initialize the terminal each time it is called but should restore it only when CacheEnd is called or the connection is broken.

  • CACHE_TTSTART — Caché should initialize the terminal when the connection is formed and reset it when the connection is terminated.

  • CACHE_TTNEVER — Caché should not alter the terminal's settings.

  • CACHE_TTNONE — Caché should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.

  • CACHE_TTNOUSE — This flag is allowed with CACHE_TTALL, CACHE_TTCALLIN, and CACHE_TTSTART. It is implicitly set by the flags CACHE_TTNEVER and CACHE_TTNONE. It indicates that Caché Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.

Return Values for CacheSecureStartW

CACHE_ACCESSDENIED Authentication has failed. Check the audit log for the real authentication error.
CACHE_ALREADYCON Connection already existed. Returned if you call CacheSecureStartH from a $ZF function.
CACHE_CHANGEPASSWORD Password change required. This return value is only returned if you are using Caché authentication.
CACHE_CONBROKEN Connection was formed and then broken, and CacheEnd has not been called to clean up.
CACHE_FAILURE An unexpected error has occurred.
CACHE_STRTOOLONG prinp or prout is too long.
CACHE_SUCCESS Connection formed.

The flags parameter(s) convey information about how your C program will behave and how you want Caché to set terminal characteristics. The safest, but slowest, route is to have Caché set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter CACHE_TTNEVER requires the least overhead.

CacheSetDir

int CacheSetDir(char * dir)
Arguments

dir Pointer to the directory name string.
Description

Dynamically sets the name of the manager's directory (CacheSys\Mgr) at runtime. On Windows, the shared library version of Caché requires the use of this function to identify the managers directory for the installation.

Return Values for CacheSetDir

CACHE_FAILURE Returns if called from a $ZF function (rather than from within a Callin executable).
CACHE_SUCCESS Control function performed.

CacheSetProperty

int CacheSetProperty( )
Description

Stores the value of the property defined by CachePushProperty. The value must be pushed onto the argument stack before this call.

Return Values for CacheSetProperty

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_SUCCESS The operation was successful.

CacheSignal

int CacheSignal(int signal)
Arguments

signal The operating system's signal value.
Description

Passes on signals caught by user's program to Caché.

This function is very similar to CacheAbort, but allows passing of any known signal value from a thread or user side of the connection to the Caché side, for whatever action might be appropriate. For example, this could be used to pass signals intercepted in a user-defined signal handler on to Caché.

Example

rc = CacheSignal(CTRL_C_EVENT); // Windows response to Ctrl-C
rc = CacheSignal(CTRL_C_EVENT); // UNIX response to Ctrl-C
Return Values for CacheSignal

CACHE_CONBROKEN Connection has been broken.
CACHE_NOCON No connection has been established.
CACHE_NOTINCACHE The Callin partner is not in Caché at this time.
CACHE_SUCCESS Connection formed.

CacheSPCReceive

int CacheSPCReceive(int * lenp, Callin_char_t * ptr)
Arguments

lenp Maximum length to receive. Modified on return to indicate number of bytes actually received.
ptr Pointer to buffer that will receive message. Must be at least lenp bytes.
Description

Receive single-process-communication message. The current device must be a TCP device opened in SPC mode, or CACHE_ERFUNCTION will be returned.

Return Values for CacheSPCReceive

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERFUNCTION Current device is not TCP device or is not connected.
CACHE_SUCCESS The operation was successful.

CacheSPCSend

int CacheSPCSend(int len, const Callin_char_t * ptr)
Arguments

len Length of message in bytes.
ptr Pointer to string containing message.
Description

Send a single-process-communication message. The current device must be a TCP device opened in SPC mode, or CACHE_ERFUNCTION will be returned.

Return Values for CacheSPCSend

CACHE_CONBROKEN Connection has been closed due to a serious error.
CACHE_NOCON No connection has been established.
CACHE_ERSYSTEM Either the Caché engine generated a <SYSTEM> error, or Callin detected an internal data inconsistency.
CACHE_ERFUNCTION Current device is not TCP device or is not connected.
CACHE_ERARGSTACK Argument stack overflow.
CACHE_ERSTRINGSTACK String stack overflow.
CACHE_SUCCESS The operation was successful.
Any Caché error From translating a name.

CacheStartA

Variants: CacheStartW, CacheStartH

int CacheStartA(unsigned long flags, int tout, CACHE_ASTRP prinp, CACHE_ASTRP prout)
Arguments

flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for Caché. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for Caché. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description

Calls into Caché to set up a Caché process.

The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a Caché connection with the cache command, Caché does not open the principal input or output device until it is first used.

Valid values for the flags variable are:

  • CACHE_PROGMODE — Caché should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by Caché results in closing the connection and returning error CACHE_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)

  • CACHE_TTALL — Default. Caché should initialize the terminal's settings and restore them across each call into, and return from, the interface.

  • CACHE_TTCALLIN — Caché should initialize the terminal each time it is called but should restore it only when CacheEnd is called or the connection is broken.

  • CACHE_TTSTART — Caché should initialize the terminal when the connection is formed and reset it when the connection is terminated.

  • CACHE_TTNEVER — Caché should not alter the terminal's settings.

  • CACHE_TTNONE — Caché should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.

  • CACHE_TTNOUSE — This flag is allowed with CACHE_TTALL, CACHE_TTCALLIN, and CACHE_TTSTART. It is implicitly set by the flags CACHE_TTNEVER and CACHE_TTNONE. It indicates that Caché Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.

Return Values for CacheStartA

CACHE_ALREADYCON Connection already existed. Returned if you call CacheStartA from a $ZF function.
CACHE_CONBROKEN Connection was formed and then broken, and CacheEndA has not been called to clean up.
CACHE_FAILURE An unexpected error has occurred.
CACHE_STRTOOLONG prinp or prout is too long.
CACHE_SUCCESS Connection formed.

The flags parameter(s) convey information about how your C program will behave and how you want Caché to set terminal characteristics. The safest, but slowest, route is to have Caché set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter CACHE_TTNEVER requires the least overhead.

Example

A Caché process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for a Caché backup. Output appears on the terminal.

CACHE_ASTR inpdev;
CACHE_ASTR outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = CacheStartA(CACHE_TTALL|CACHE_TTNOUSE,0,inpdev,outdev);

CacheStartH

Variants: CacheStartA, CacheStartW

int CacheStartH(unsigned long flags,int tout,CACHEHSTRP prinp,CACHEHSTRP prout)
Arguments

flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for Caché. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for Caché. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description

Calls into Caché to set up a Caché process.

The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a Caché connection with the cache command, Caché does not open the principal input or output device until it is first used.

Valid values for the flags variable are:

  • CACHE_PROGMODE — Caché should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by Caché results in closing the connection and returning error CACHE_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)

  • CACHE_TTALL — Default. Caché should initialize the terminal's settings and restore them across each call into, and return from, the interface.

  • CACHE_TTCALLIN — Caché should initialize the terminal each time it is called but should restore it only when CacheEnd is called or the connection is broken.

  • CACHE_TTSTART — Caché should initialize the terminal when the connection is formed and reset it when the connection is terminated.

  • CACHE_TTNEVER — Caché should not alter the terminal's settings.

  • CACHE_TTNONE — Caché should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.

  • CACHE_TTNOUSE — This flag is allowed with CACHE_TTALL, CACHE_TTCALLIN, and CACHE_TTSTART. It is implicitly set by the flags CACHE_TTNEVER and CACHE_TTNONE. It indicates that Caché Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.

Return Values for CacheStartH

CACHE_ALREADYCON Connection already existed. Returned if you call CacheStartH from a $ZF function.
CACHE_CONBROKEN Connection was formed and then broken, and CacheEndH has not been called to clean up.
CACHE_FAILURE An unexpected error has occurred.
CACHE_STRTOOLONG prinp or prout is too long.
CACHE_SUCCESS Connection formed.

The flags parameter(s) convey information about how your C program will behave and how you want Caché to set terminal characteristics. The safest, but slowest, route is to have Caché set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter CACHE_TTNEVER requires the least overhead.

Example

A Caché process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for a Caché backup. Output appears on the terminal.

inpdev;
outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = CacheStartH(CACHE_TTALL|CACHE_TTNOUSE,0,inpdev,outdev);

CacheStartW

Variants: CacheStartA, CacheStartH

int CacheStartW(unsigned long flags,int tout,CACHEWSTRP prinp,CACHEWSTRP prout)
Arguments

flags One or more of the values listed in the description below.
tout The timeout specified in seconds. Default is 0. If 0 is specified, the timeout will never expire. The timeout applies only to waiting for an available partition, not the time associated with initializing the partition, waiting for internal resources, opening the principal input and output devices, etc.
prinp String that defines the principal input device for Caché. An empty string (prinp.len == 0) implies using the standard input device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
prout String that defines the principal output device for Caché. An empty string (prout.len == 0) implies using the standard output device for the process. A NULL pointer ((void *) 0) implies using the NULL device.
Description

Calls into Caché to set up a Caché process.

The input and output devices (prinp and prout) are opened when this command is executed, not deferred until the first I/O operation. By contrast, normally when you initiate a Caché connection with the cache command, Caché does not open the principal input or output device until it is first used.

Valid values for the flags variable are:

  • CACHE_PROGMODE — Caché should treat the connection as one in Programmer mode, rather than the Application mode. This means that distinct errors are reported to the calling function and the connection remains active. (By default, a Callin connection is like execution of a routine in application mode. Any runtime error detected by Caché results in closing the connection and returning error CACHE_CONBROKEN for both the current operation and any subsequent attempts to use Callin without establishing a new connection.)

  • CACHE_TTALL — Default. Caché should initialize the terminal's settings and restore them across each call into, and return from, the interface.

  • CACHE_TTCALLIN — Caché should initialize the terminal each time it is called but should restore it only when CacheEnd is called or the connection is broken.

  • CACHE_TTSTART — Caché should initialize the terminal when the connection is formed and reset it when the connection is terminated.

  • CACHE_TTNEVER — Caché should not alter the terminal's settings.

  • CACHE_TTNONE — Caché should not do any output or input from the principal input/output devices. This is equivalent to specifying the null device for principal input and principal output. Read commands from principal input generate an <ENDOFFILE> error and Write command to principal output are ignored.

  • CACHE_TTNOUSE — This flag is allowed with CACHE_TTALL, CACHE_TTCALLIN, and CACHE_TTSTART. It is implicitly set by the flags CACHE_TTNEVER and CACHE_TTNONE. It indicates that Caché Open and Use commands are not allowed to alter the terminal, subsequent to the initial open of principal input and principal output.

Return Values for CacheStartW

CACHE_ALREADYCON Connection already existed. Returned if you call CacheStartW from a $ZF function.
CACHE_CONBROKEN Connection was formed and then broken, and CacheEndW has not been called to clean up.
CACHE_FAILURE An unexpected error has occurred.
CACHE_STRTOOLONG prinp or prout is too long.
CACHE_SUCCESS Connection formed.

The flags parameter(s) convey information about how your C program will behave and how you want Caché to set terminal characteristics. The safest, but slowest, route is to have Caché set and restore terminal settings for each call into ObjectScript. However, you can save ObjectScript overhead by handling more of that yourself, and collecting only information that matters to your program. The parameter CACHE_TTNEVER requires the least overhead.

Example

A Caché process is started. The terminal is reset after each interface Callin function. The start fails if a partition is not allocated within 20 seconds. The file dobackup is used for input. It contains an ObjectScript script for a Caché backup. Output appears on the terminal.

inpdev;
outdev;
int rc;

strcpy(inpdev.str, "[BATCHDIR]dobackup");
inpdev.len = strlen(inpdev.str);
strcpy(outdev.str,"");
outdev.len = strlen(outdev.str);
rc = CacheStartW(CACHE_TTALL|CACHE_TTNOUSE,0,inpdev,outdev);

CacheTCommit

int CacheTCommit( )
Description

Executes a Cache TCommit command.

Return Values for CacheTCommit

CACHE_SUCCESS TCommit was successful.

CacheTLevel

int CacheTLevel( )
Description

Returns the current nesting level ($TLEVEL) for transaction processing.

Return Values for CacheTLevel

CACHE_SUCCESS TLevel was successful.

CacheTRollback

int CacheTRollback(int nlev)
Arguments

nlev Determines how many levels to roll back, (all levels if 0, one level if 1).
Description

Executes a Cache TRollback command. If nlev is 0, rolls back all transactions in progress (no matter how many levels of TSTART were issued) and resets $TLEVEL to 0. If nlev is 1, rolls back the current level of nested transactions (the one initiated by the most recent TSTART) and decrements $TLEVEL by 1.

Return Values for CacheTRollback

CACHE_SUCCESS TStart was successful.

CacheTStart

int CacheTStart( )
Description

Executes a Cache TStart command.

Return Values for CacheTStart

CACHE_SUCCESS TStart was successful.

CacheType

int CacheType( )
Description

Returns the native type of the item returned by CacheEvalA, CacheEvalW, or CacheEvalH as the function value.

Return Values for CacheType

CACHE_ASTRING 8-bit string.
CACHE_CONBROKEN Connection has been closed due to a serious error condition or RESJOB.
CACHE_DOUBLE 64-bit Caché floating point.
CACHE_ERSYSTEM Either ObjectScript generated a <SYSTEM> error, or if called from a $ZF function, an internal counter may be out of sync.
CACHE_IEEE_DBL 64-bit IEEE floating point.
CACHE_INT 32-bit integer.
CACHE_NOCON No connection has been established.
CACHE_NORES No result whose type can be returned (no call to CacheEvalA or CacheEvalW preceded this call).
CACHE_OREF Caché object reference.
CACHE_WSTRING Unicode string.
Example

rc = CacheType();

CacheUnPop

int CacheUnPop( )
Description

Restores the stack entry from CachePop.

Return Values for CacheUnPop

CACHE_NORES No result whose type can be returned has preceded this call.
CACHE_SUCCESS The operation was successful.
FeedbackOpens in a new tab