Callin Function Reference

Alphabetical Function List

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• CacheDoRtn — Performs a routine call.

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

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

• CacheErrorA[W][H] — Returns the most recent error message, its associated source string, and the offset to where in the source string the error occurred.

• CacheErrxlateA[W][H] — Translates an integer error code into a Cache error string.

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

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

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

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

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

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

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

• CacheGlobalGet — Obtains the value of the global reference defined by CachePushGlobal[W][H] and any subscripts. The node value is pushed onto the argument stack.

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

• CacheGlobalKill — Performs a ZKILL on a global node or tree.

• CacheGlobalOrder — Performs a $Order on the specified global.

• CacheGlobalQuery — Performs a $Query on the specified global.

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

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

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

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

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

• CacheOflush — Flushes any pending output.

• CachePop — Pops a value off argument stack.

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

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

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

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

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

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

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

• CachePopOref — Pops an OREF off argument stack.

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

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

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

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

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

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

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

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

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

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

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

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

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

• CachePushInt — Pushes an integer onto the argument stack.

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

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

• CachePushLock[W][H] — Initializes a CacheAcquireLock command by pushing the lock name on the argument stack.

• CachePushLockX[W][H] — Initializes a CacheAcquireLock command by pushing the lock name and an environment string on the argument stack.

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

• CachePushOref — Pushes an OREF onto the argument stack.

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

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

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

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

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

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

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

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

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

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

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

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

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

• CacheSPCReceive — Receive single-process-communication message.

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

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

• CacheTCommit — Executes a Cache TCommit command.

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

• CacheTRollback — Executes a Cache TRollback command.

• CacheTStart — Executes a Cache TStart command.

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

• CacheUnPop — Restores the stack entry from CachePop.

CacheAbort

int CacheAbort(unsigned long type)

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.

rc = CacheAbort(CACHE_CTRLC);

CacheAcquireLock

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

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

CacheBitFind

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

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”).

CacheBitFindB

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

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”).

CacheChangePasswordA

Variants: CacheChangePasswordW, CacheChangePasswordH

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

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

CacheChangePasswordH

Variants: CacheChangePasswordA, CacheChangePasswordW

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

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

CacheChangePasswordW

Variants: CacheChangePasswordA, CacheChangePasswordH

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

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

CacheCloseOref

int CacheCloseOref(unsigned int oref)

Decrements the system reference counter for an OREF.

CacheContext

int CacheContext()

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.

rc = CacheContext();

CacheConvert

int CacheConvert(unsigned long type, void * rbuf)

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

Valid values of type are:

• CACHE_ASTRING — 8-bit character string.

• CACHE_CHAR — 8-bit signed integer.

• CACHE_DOUBLE — 64-bit floating point.

• CACHE_FLOAT — 32-bit floating point.

• CACHE_INT — 32-bit signed integer.

• CACHE_INT2 — 16-bit signed integer.

• CACHE_INT4 — 32-bit signed integer.

• CACHE_INT8 — 64-bit signed integer.

• CACHE_UCHAR — 8-bit unsigned integer.

• CACHE_UINT — 32-bit unsigned integer.

• CACHE_UINT2 — 16-bit unsigned integer.

• CACHE_UINT4 — 32-bit unsigned integer.

• CACHE_UINT8 — 64-bit unsigned integer.

• CACHE_WSTRING — Unicode character string.

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)

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

• CACHE_DISACTRLC — Caché ignores CTRL-C.

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

rc = CacheCtrl(CACHE_ENABCTRLC);

CacheCvtExStrInA

Variants: CacheCvtExStrInW, CacheCvtExStrInH

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

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

CacheCvtExStrInW

Variants: CacheCvtExStrInA, CacheCvtExStrInH

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

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

CacheCvtExStrInH

Variants: CacheCvtExStrInA, CacheCvtExStrInW

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

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

CacheCvtExStrOutA

Variants: CacheCvtExStrOutW, CacheCvtExStrOutH

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

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é.)

CacheCvtExStrOutW

Variants: CacheCvtExStrOutA, CacheCvtExStrOutH

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

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é.)

CacheCvtExStrOutH

Variants: CacheCvtExStrOutA, CacheCvtExStrOutW

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

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é.)

CacheCvtInA

Variants: CacheCvtInW, CacheCvtInH

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

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

CacheCvtInH

Variants: CacheCvtInA, CacheCvtInW

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

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

CacheCvtInW

Variants: CacheCvtInA, CacheCvtInH

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

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

CacheCvtOutA

Variants: CacheCvtOutW, CacheCvtOutH

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

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é.)

CacheCvtOutH

Variants: CacheCvtOutA, CacheCvtOutW

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

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é.)

CacheCvtOutW

Variants: CacheCvtOutA, CacheCvtOutH

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

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é.)

CacheDoFun

int CacheDoFun(unsigned int flags, int narg)

Performs a routine call (special case).

CacheDoRtn

int CacheDoRtn(unsigned int flags, int narg)

Performs a routine call.

CacheEnd

int CacheEnd()

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

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

rc = CacheEnd();

CacheEndAll

int CacheEndAll()

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

rc = CacheEndAll();

CacheErrorA

Variants: CacheErrorW, CacheErrorH

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

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

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)

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

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)

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

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)

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

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)

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

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)

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

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)

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.

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

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)

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.

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

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)

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.

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

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)

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

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

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)

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.

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

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)

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.

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

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)

Releases the storage associated with an EXSTR string.

CacheExStrNew

Variants: CacheExStrNewW, CacheExStrNewH

unsigned char * CacheExStrNew(CACHE_EXSTRP zstr, int size)

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.

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)

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.

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)

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.

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

CacheExtFun

int CacheExtFun(unsigned int flags, int narg)

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

CacheGetProperty

int CacheGetProperty()

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

CacheGlobalData

int CacheGlobalData(int narg, int valueflag)

Performs a $Data on the specified global.

CacheGlobalGet

int CacheGlobalGet(int narg, int flag)

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

CacheGlobalGetBinary

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

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.

CacheGlobalIncrement

int CacheGlobalIncrement(int narg)

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

CacheGlobalKill

int CacheGlobalKill(int narg, int nodeonly)

Performs a ZKILL on a global node or tree.

CacheGlobalOrder

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

Performs a $Order on the specified global.

CacheGlobalQuery

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

Performs a $Query on the specified global.

CacheGlobalRelease

int CacheGlobalRelease( )

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

CacheGlobalSet

int CacheGlobalSet(int narg)

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.

CacheIncrementCountOref

int CacheIncrementCountOref(unsigned int oref)

Increments the system reference counter for an OREF.

CacheInvokeClassMethod

int CacheInvokeClassMethod(int narg)

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

CacheInvokeMethod

int CacheInvokeMethod(int narg)

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

CacheOflush

int CacheOflush()

Flushes any pending output.

CachePop

int CachePop(void ** arg)

Pops a value off argument stack.

CachePopCvtH

Variants: CachePopCvtW

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

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

CachePopCvtW

Variants: CachePopCvtH

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

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.

CachePopDbl

int CachePopDbl(double * nump)

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

CachePopExStr

Variants: CachePopExStrW, CachePopExStrH

int CachePopExStr(CACHE_EXSTRP sstrp)

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

CachePopExStrCvtW

Variants: CachePopExStrCvtH

int CachePopExStrCvtW(CACHE_EXSTRP sstr)

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.

CachePopExStrCvtH

Variants: CachePopExStrCvtW

int CachePopExStrCvtW(CACHE_EXSTRP sstr)

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.

CachePopExStrW

Variants: CachePopExStr, CachePopExStrH

int CachePopExStrW(CACHE_EXSTRP sstrp)

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

CachePopExStrH

Variants: CachePopExStr, CachePopExStrW

int CachePopExStrH(CACHE_EXSTRP sstrp)

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

CachePopInt

int CachePopInt(int* nump)

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

CachePopInt64

int CachePopInt64(long long * nump)

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

CachePopList

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

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

CachePopOref

int CachePopOref(unsigned int * orefp)

Pops an OREF off argument stack.

CachePopPtr

int CachePopPtr(void ** ptrp)

Pops a pointer off argument stack in internal format.

CachePopStr

Variants: CachePopStrW, CachePopStrH

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

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

CachePopStrH

Variants: CachePopStr, CachePopStrW

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

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

CachePopStrW

Variants: CachePopStr, CachePopStrH

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

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

CachePromptA

Variants: CachePromptW, CachePromptH

int CachePromptA(CACHE_ASTRP rbuf)

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

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)

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

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

CachePromptW

Variants: CachePromptA, CachePromptH

int CachePromptW(CACHEWSTRP rbuf)

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

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)

Pushes a class method reference onto the argument stack.

CachePushClassMethodH

Variants: CachePushClassMethod, CachePushClassMethodW

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

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

CachePushClassMethodW

Variants: CachePushClassMethod, CachePushClassMethodH

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

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

CachePushCvtH

Variants: CachePushCvtW

int CachePushCvtH(int len, const wchar_t * ptr)

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

CachePushCvtW

Variants: CachePushCvtH

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

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.

CachePushDbl

int CachePushDbl(double num)

Pushes a Caché double onto the argument stack.

CachePushExStr

Variants: CachePushExStrW, CachePushExStrH

int CachePushExStr(CACHE_EXSTRP sptr)

Pushes a string onto the argument stack.

CachePushExStrCvtW

Variants: CachePushExStrCvtH

int CachePushExStrCvtW(CACHE_EXSTRP sptr)

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

CachePushExStrCvtH

Variants: CachePushExStrCvtW

int CachePushExStrCvtH(CACHE_EXSTRP sptr)

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

CachePushExStrW

Variants: CachePushExStr, CachePushExStrH

int CachePushExStrW(CACHE_EXSTRP sptr)

Pushes a long Unicode string onto the argument stack.

CachePushExStrH

Variants: CachePushExStr, CachePushExStrW

int CachePushExStrH(CACHE_EXSTRP sptr)

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

CachePushFunc

Variants: CachePushFuncW, CachePushFuncH

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

Pushes an extrinsic function reference onto the argument stack.

CachePushFuncH

Variants: CachePushFunc, CachePushFuncW

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

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

CachePushFuncW

Variants: CachePushFunc, CachePushFuncH

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

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

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)

Pushes an extended extrinsic function reference onto the argument stack.

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)

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

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)

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

CachePushGlobal

Variants: CachePushGlobalW, CachePushGlobalH

int CachePushGlobal(int nlen, const Callin_char_t * nptr)

Pushes a global reference onto the argument stack.

CachePushGlobalH

Variants: CachePushGlobal, CachePushGlobalW

intCachePushGlobalH(int nlen, const wchar_t * nptr)

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

CachePushGlobalW

Variants: CachePushGlobal, CachePushGlobalH

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

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

CachePushGlobalX

Variants: CachePushGlobalXW, CachePushGlobalXH

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

Pushes an extended global reference onto the argument stack.

CachePushGlobalXH

Variants: CachePushGlobalX, CachePushGlobalXW

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

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

CachePushGlobalXW

Variants: CachePushGlobalX, CachePushGlobalXH

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

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

CachePushIEEEDbl

int CachePushIEEEDbl(double num)

Pushes an IEEE double onto the argument stack.

CachePushInt

int CachePushInt(int num)

Pushes an integer onto the argument stack.

CachePushInt64

int CachePushInt64(long long num)

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

CachePushList

int CachePushList(int len, const Callin_char_t * ptr)

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.

CachePushLock

Variants: CachePushLockW, CachePushLockH

int CachePushLock(int nlen, const Callin_char_t * nptr)

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

CachePushLockH

Variants: CachePushLock, CachePushLockW

int CachePushLockH(int nlen, const wchar_t * nptr)

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

CachePushLockW

Variants: CachePushLock, CachePushLockH

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

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

CachePushLockX

Variants: CachePushLockXW, CachePushLockXH

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

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

CachePushLockXH

Variants: CachePushLockX, CachePushLockXW

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

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

CachePushLockXW

Variants: CachePushLockX, CachePushLockXH

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

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

CachePushMethod

Variants: CachePushMethodW, CachePushMethodH

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

Pushes an instance method reference onto the argument stack.

CachePushMethodH

Variants: CachePushMethod, CachePushMethodW

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

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

CachePushMethodW

Variants: CachePushMethod, CachePushMethodH

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

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

CachePushOref

int CachePushOref(unsigned int oref)

Pushes an OREF onto the argument stack.

CachePushProperty

Variants: CachePushPropertyW, CachePushPropertyH

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

Pushes a property reference onto the argument stack.

CachePushPropertyH

Variants: CachePushProperty, CachePushPropertyW

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

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

CachePushPropertyW

Variants: CachePushProperty, CachePushPropertyH

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

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

CachePushPtr

int CachePushPtr(void * ptr)

Pushes a pointer onto the argument stack in internal format.

CachePushRtn

Variants: CachePushRtnW, CachePushRtnH

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

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.

CachePushRtnH

Variants: CachePushRtn, CachePushRtnW

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

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.

CachePushRtnW

Variants: CachePushRtn, CachePushRtnH

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

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.

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)

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.

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)

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.

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)

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.

CachePushStr

Variants: CachePushStrW, CachePushStrH

int CachePushStr(int len, const Callin_char_t * ptr)

Pushes a byte string onto the argument stack.

CachePushStrH

Variants: CachePushStr, CachePushStrW

int CachePushStrH(int len, const wchar_t * ptr)

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

CachePushStrW

Variants: CachePushStr, CachePushStrH

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

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

CachePushUndef

int CachePushUndef()

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

CacheReleaseAllLocks

int CacheReleaseAllLocks( )

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

CacheReleaseLock

int CacheReleaseLock(int nsub, int flg)

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

CacheSecureStartA

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)

Calls into Cache to set up a Cache process..

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

Valid values for the flags variable are:

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

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

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

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

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

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

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