Using the Caché Callin API
Callin Function Reference
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   
Search:    

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:
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
int CacheAbort(unsigned long type)
Arguments
type Either of the following predefined values that specify how the termination occurs:
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 is used. It is not valid for LDAP, DELEGATED, 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 is used. It is not valid for LDAP, DELEGATED, 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 is used. It is not valid for LDAP, DELEGATED, 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:
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
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:
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:
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:
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é.
Note:
VMS versions of Cache do not use signal handling. On VMS systems, CacheSignal returns CACHE_SUCCESS so that programs compiled for both VMS and for UNIX® do not need to be sensitive to this difference.
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:
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 a 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:
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 a 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:
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 a 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.