com.intersys.cache.jni
Class CacheJNI

java.lang.Object
  extended bycom.intersys.cache.jni.CacheJNI

public class CacheJNI
extends Object

Interface for calling into Cache' from Java programs. This can only be used from Java programs which have been invoked via the Cache'->Java linkage provided by the $SYSTEM.Java methods. These programs are running in a JVM loaded by Cache', created using $SYSTEM.Java.InitVM(). This class cannot be used to connect "standalone" java applications or applets to Cache'; use one of the IP based connections for that situation.

isLoaded() indicates whether the other methods of this class can be used or not. Calling a method of this class when isLoaded() returns false will result in a java.lang.UnsatisfiedLinkError error.

Multi-threaded Java Applications and Cache'
Philosophically the design of software which uses this class follows one of two patterns: Applications where the Java code is viewed as a subroutine of a Cache' and the inverse where Cache' is viewed as a service provider to a Java application. There isn't any fundamental difference between these two but software which is primarily a Java application using the services of the Cache' database may have to worry about multithreading issues. This can be an issue for Cache applications which call out to Java but that is much less likely. The issue is that Cache is not re-entrent and only one Java thread at a time can make use of the CacheJNI interface. It is not enough to simply declare the CacheJNI methods as synchronized because the scope of the required synchronization is greater than just a single CacheJNI method call. Consider the case of a thread which wants to retrieve a global reference from Cache'. This thread must block other threads from the time it starts setting up the call stack with PushGlobal() until it completes the operation with a call to one of the CacheJNI.Pop methods to retrieve the result left on the stack by GetGlobal().

It is the Java programmer's responsibility to arbitrate access to the CacheJNI methods among Java threads and to ensure that the CacheJNI methods are not used while a process is executing within Cache. An example of the latter would be a Cache' program that starts a Java thread and returns to run "in Cache'" while the Java thread continues in Java. If the Java thread wants to call into Cache' it must wait for the Cache' thread to call back into Java. The consequenses of violating these rules can be disasterous. At best they can result in memory violations which will terminate the Cache process, and the Java Virtual Machine. At worst they can result in Cache' system hangs, requiring a Cache' restart, or Cache' database degradation.

A Java application which views Cache as a service can deal with these issues using the Java synchronized statement or method to arbitrate use of this interface. For a Cache' program which makes use of Java as a service it would be better to define a messaging interface between the Java threads and the Cache' program where the Java threads post messages to a queue which the Cache' side of the application pulls off with the $SYSTEM.Java methods.


Field Summary
static int CACHE_ERBADARG
          Error code indicating an argument to a method is out of range or otherwise invalid.
static int CACHE_ERINTERRUPT
          Error code returned if operations is interrupted by a CTRL/C
static int CACHE_ERNOCON
          Error code returned from an attempt to access Cache' when the process is already executing in "Cache' context".
static int CACHE_ERNORES
          Error code indicating a function was called to pop an argument off of the argument stack but no argument was present to be popped.
static int CACHE_ERRETTOOSMALL
          Error code indicating that the return buffer is too small and nothing has been returned
static int CACHE_ERRETTRUNC
          Error code indicating that the return buffer was too small so only a portion of the requested item was returned.
static int CACHE_ERSTRTOOLONG
          Error code returned if a string argument is too long
static int CACHE_ERUNKNOWN
          Error code returned from the routines that translate error codes into text ErrorMessage(int) that indicates that the specified error code is not valid.
static int CACHE_TYPE_DOUBLE
          When returned from TopArgType() means the argument is a 64bit floating point number.
static int CACHE_TYPE_INT
          When returned from TopArgType() means the argument is a 32bit integer.
static int CACHE_TYPE_OREF
          Returned from TopArgType() to indicate that the next item to pop is an internal Cache' object id.
static int CACHE_TYPE_STRING
          Returned from TopArgType() to indicate that the next item to pop is a Cache' string.
 
Constructor Summary
CacheJNI()
           
 
Method Summary
static void CallFunction(int rtnflags, int narg)
          Call the function specified by PushFunction() using the arguments stacked with the PushArg methods and get a value back.
static void DoFunction(int rtnflags, int narg)
          Execute the function specified by PushFunction() as a routine (discard the return value) passing the arguments stacked with the PushArg methods.
static void DoRoutine(int rtnflags, int narg)
          Call the routine specified by PushRoutine() passing the arguments stacked with the PushArg methods.
static String ErrorMessage(int code)
          Return the text of the error message associated with the specified code.
static void Evaluate(String cmd)
          Evaluate a COS expression as if it was specified on the right hand side of an equals sign.
static void Execute(String cmd)
          Execute a COS statement as if it was passed to the COS Execute command.
static void GetGlobal(int narg, int undefok)
          Retrieves the value of the global reference specified by PushGlobal() and PushArg().
static void GetLocal(String name)
          Retrieves the value of the specified local variable.
static void getLock()
          Returns with the lock on the class monitor that prevents multiple threads from using the native methods of this class at the same time.
static void GetProperty()
          Retrieve the value of a class property.
static void InvokeClassMethod(int narg)
          Execute the class method specified by PushClassMethod() passing the arguments set up with the PushArg methods.
static void InvokeMethod(int narg)
          Execute an instance method specified by PushMethod() passing the arguments set up with the PushArg methods.
static boolean isLoaded()
          Tests whether this class can be used to access Cache' from a Java program.
static void main(String[] str)
           
static CacheInternalArg Pop()
          Removes the argument on the top of the Cache' argument stack which would be something returned from one of the functions in this class that return data from Cache' back to Java such as CallFunction(int,int) or GetGlobal(int,int).
static double PopDouble()
          Returns the argument on the top of the Cache' argument stack as a double.
static float PopFloat()
          Returns the argument on the top of the Cache' argument stack as a float.
static int PopInt()
          Returns the argument on the top of the Cache' argument stack as an integer.
static CacheExternalOref PopOref()
          Used when the argument on top of the Cache' argument stack is an internal Cache' object id.
static String PopString()
          Returns the argument on the top of the Cache' argument stack as a string.
static void PushArg(CacheExternalOref oref)
          Pushes an integer onto the Cache' argument stack as a Cache' object reference id.
static void PushArg(double dblarg)
          Pushes a double onto the Cache' argument stack as a Cache' floating point number.
static void PushArg(float floatarg)
          Pushes a float onto the Cache' argument stack as a Cache' floating point number.
static void PushArg(int intarg)
          Pushes an integer onto the Cache' argument stack as a Cache' integer.
static void PushArg(String strarg)
          Pushes a string onto the Cache' argument stack as a Cache' string.
static void PushClassMethod(String classname, String methodname, int returnrequired)
          Pushes the name of a Class (static) method in preparation for calling it.
static int PushFunction(String name)
          Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value).
static int PushFunction(String tag, int offset, String environment, String name)
          Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value).
static int PushFunction(String tag, String name)
          Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value).
static void PushGlobal(String gloname)
          Pushes the Global name portion of a global reference in preparation for calling SetGlobal or GetGlobal to perform a global reference in the current namespace.
static void PushGlobal(String gloname, String env)
          Pushes the Global name and environment portions of a global reference in preparation for calling SetGlobal or GetGlobal.
static void PushMethod(CacheExternalOref oref, String methodname, int returnrequired)
          Pushes the name of an instance method in preparation for calling it.
static void PushProperty(CacheExternalOref oref, String propertyname)
          Pushes a property name with class reference in preparation for calling SetProperty or GetProperty.
static int PushRoutine(String name)
          Pushes the name of a COS Routine in order to call it.
static int PushRoutine(String tag, int offset, String environment, String name)
          Pushes the name of a COS Routine in order to call it.
static int PushRoutine(String tag, String name)
          Pushes the name of a COS Routine in order to call it.
static boolean releaseLock()
          Releases the lock on the class monitor that my be blocking other threads from using this class.
static void SetGlobal(int narg)
          Sets the value of the global reference specified by PushGlobal() and PushArg().
static void SetLocal(String name)
          Sets the value of the specified local variable.
static void SetProperty()
          Sets the the value of a class property.
static int TopArgType()
          Return the type of the top argument on the Cache' argument stack, if its a valid argument.
static void UnPop()
          Decrements the internal Cache' argument stack pointer which pushes the last argument popped back onto the argument stack
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CACHE_TYPE_INT

public static final int CACHE_TYPE_INT
When returned from TopArgType() means the argument is a 32bit integer.

See Also:
Constant Field Values

CACHE_TYPE_DOUBLE

public static final int CACHE_TYPE_DOUBLE
When returned from TopArgType() means the argument is a 64bit floating point number.

See Also:
Constant Field Values

CACHE_TYPE_STRING

public static final int CACHE_TYPE_STRING
Returned from TopArgType() to indicate that the next item to pop is a Cache' string. On non-Unicode Cache' systems, this is a string of 8-bit bytes. On UNICODE systems, this is a string of 16-bit characters. When returned into a Java String, all Cache strings are converted to Unicode.

See Also:
Constant Field Values

CACHE_TYPE_OREF

public static final int CACHE_TYPE_OREF
Returned from TopArgType() to indicate that the next item to pop is an internal Cache' object id.

See Also:
Constant Field Values

CACHE_ERNORES

public static final int CACHE_ERNORES
Error code indicating a function was called to pop an argument off of the argument stack but no argument was present to be popped.

See Also:
Constant Field Values

CACHE_ERBADARG

public static final int CACHE_ERBADARG
Error code indicating an argument to a method is out of range or otherwise invalid.

See Also:
Constant Field Values

CACHE_ERRETTRUNC

public static final int CACHE_ERRETTRUNC
Error code indicating that the return buffer was too small so only a portion of the requested item was returned.

See Also:
Constant Field Values

CACHE_ERUNKNOWN

public static final int CACHE_ERUNKNOWN
Error code returned from the routines that translate error codes into text ErrorMessage(int) that indicates that the specified error code is not valid.

See Also:
Constant Field Values

CACHE_ERRETTOOSMALL

public static final int CACHE_ERRETTOOSMALL
Error code indicating that the return buffer is too small and nothing has been returned

See Also:
Constant Field Values

CACHE_ERNOCON

public static final int CACHE_ERNOCON
Error code returned from an attempt to access Cache' when the process is already executing in "Cache' context". This is only seen in a threaded Java application when a Java thread attempts to access Cache but another "thread" is currently executing in Cache'.

See Also:
Constant Field Values

CACHE_ERINTERRUPT

public static final int CACHE_ERINTERRUPT
Error code returned if operations is interrupted by a CTRL/C

See Also:
Constant Field Values

CACHE_ERSTRTOOLONG

public static final int CACHE_ERSTRTOOLONG
Error code returned if a string argument is too long

See Also:
Constant Field Values
Constructor Detail

CacheJNI

public CacheJNI()
Method Detail

main

public static void main(String[] str)

isLoaded

public static boolean isLoaded()
Tests whether this class can be used to access Cache' from a Java program. When this method returns FALSE, JDBC or another IP based technology must be used as this JVM was not created by a Cache' process.

Returns:
TRUE means the methods of this class can be used. FALSE means that calling a method in this class is not allowed and will generate a java.lang.UnsatisfiedLinkError error.

getLock

public static void getLock()
Returns with the lock on the class monitor that prevents multiple threads from using the native methods of this class at the same time. It is accptable for a thread to call getLock() when it already "owns" the monitor but each call to getLock() must be matched with a call to releaseLock(). This method blocks if the lock is inuse by another thread.


releaseLock

public static boolean releaseLock()
Releases the lock on the class monitor that my be blocking other threads from using this class. If this thread has called getLock() multiple times then this method must be called once for every call to getLock() as the montior is a counting semaphore and the lock is not considered free until the count reaches zero.


PushArg

public static void PushArg(float floatarg)
                    throws CallinException
Pushes a float onto the Cache' argument stack as a Cache' floating point number.

Parameters:
floatarg - 32bit floating point number to push
Throws:
CallinException

PushArg

public static void PushArg(int intarg)
                    throws CallinException
Pushes an integer onto the Cache' argument stack as a Cache' integer.

Parameters:
intarg - 32bit integer to push
Throws:
CallinException

PushArg

public static void PushArg(double dblarg)
                    throws CallinException
Pushes a double onto the Cache' argument stack as a Cache' floating point number. There is no loss of precision in the conversion to Cache'.

Parameters:
dblarg - 64bit floating point number to push
Throws:
CallinException

PushArg

public static void PushArg(CacheExternalOref oref)
                    throws CallinException,
                           ObjectClosedException
Pushes an integer onto the Cache' argument stack as a Cache' object reference id.

Parameters:
oref - Reference to a Cache' object being pushed on the stack as an argument.
Throws:
CallinException
ObjectClosedException

PushArg

public static void PushArg(String strarg)
                    throws CallinException,
                           CacheException
Pushes a string onto the Cache' argument stack as a Cache' string. Strings in Java are Unicode but Cache' only supports Unicode strings in Unicode builds of Cache. If this is not a Unicode build of Cache' the string is converted from 16-bit characters to 8-bit characters as it is passed into Cache'. If there are 16-bit characters in the data, characters where the high 8 bits are not zero, that character is replaced with a '?' in the string that is passed into Cache'.

Parameters:
strarg - string to push
Throws:
CallinException
CacheException

PushGlobal

public static void PushGlobal(String gloname)
                       throws CallinException,
                              CacheException
Pushes the Global name portion of a global reference in preparation for calling SetGlobal or GetGlobal to perform a global reference in the current namespace.

COS Equivilent: ^Gloname

Parameters:
gloname - the global name (without leading "^") to push
Throws:
CallinException
CacheException
See Also:
SetGlobal(int), GetGlobal(int, int)

PushGlobal

public static void PushGlobal(String gloname,
                              String env)
                       throws CallinException,
                              CacheException
Pushes the Global name and environment portions of a global reference in preparation for calling SetGlobal or GetGlobal. This is a reference of the form ^|"<environment>"|<globalname>.

COS Equivilent: ^|<env>|Gloname

Parameters:
gloname - the global name (without leading "^") to push
env - environment string of the form "namespace" or "^remote system^directory".
Throws:
CallinException
CacheException
See Also:
SetGlobal(int), GetGlobal(int, int)

PushProperty

public static void PushProperty(CacheExternalOref oref,
                                String propertyname)
                         throws CallinException,
                                CacheException,
                                ObjectClosedException
Pushes a property name with class reference in preparation for calling SetProperty or GetProperty.

COS Equivilent: <tba>

Parameters:
oref - object reference of the class containing the property
propertyname - name of the property to work with
Throws:
CallinException
CacheException
ObjectClosedException
See Also:
SetProperty(), GetProperty()

PushMethod

public static void PushMethod(CacheExternalOref oref,
                              String methodname,
                              int returnrequired)
                       throws CallinException,
                              CacheException,
                              ObjectClosedException
Pushes the name of an instance method in preparation for calling it.

COS Equivilent: <tba>

Parameters:
oref - object reference id of the class containing the method
methodname - name of the method to call
returnrequired - 0 means that the method does not need to return a value. 1 means that it does (eg. via a COS argumented quit command) or else a <COMMAND> error will be generated.
Throws:
CallinException
CacheException
ObjectClosedException
See Also:
InvokeMethod(int)

PushClassMethod

public static void PushClassMethod(String classname,
                                   String methodname,
                                   int returnrequired)
                            throws CallinException,
                                   CacheException
Pushes the name of a Class (static) method in preparation for calling it.

COS Equivilent: <tba>

Parameters:
classname - name of the class containing the static method
methodname - name of the method to call
returnrequired - 0 means that the method does not need to return a value. 1 means that it does (eg. via a COS argumented quit command) or else a <COMMAND> error will be generated.
Throws:
CallinException
CacheException
See Also:
InvokeClassMethod(int)

PushRoutine

public static int PushRoutine(String name)
                       throws CacheException,
                              CallinException
Pushes the name of a COS Routine in order to call it. Execution begins at the top of the routine and the routine is located in the current namespace.

COS Equivilent: ^Routine

Parameters:
name - Name of the routine to call in the current namespace.
Throws:
CacheException
CallinException
See Also:
DoRoutine(int, int)

PushRoutine

public static int PushRoutine(String tag,
                              String name)
                       throws CacheException,
                              CallinException
Pushes the name of a COS Routine in order to call it. Execution begins at the specified tag in the routine and the routine is located in the current namespace.

COS Equivilent: tag^Routine

Parameters:
name - Name of the routine to call in the current namespace.
tag - tag to begin executation at
Throws:
CacheException
CallinException
See Also:
DoRoutine(int, int)

PushRoutine

public static int PushRoutine(String tag,
                              int offset,
                              String environment,
                              String name)
                       throws CacheException,
                              CallinException
Pushes the name of a COS Routine in order to call it. Execution begins at the specified tag in the routine and the routine is located in the specified namespace.

COS Equivilent: tag+offset^|<env>|Routine

Parameters:
name - Name of the routine to call in the current namespace.
tag - tag which is the base of the offset in finding the first line of the routine to execute.
offset - numeric offset from tag to being executation at
Throws:
CacheException
CallinException
See Also:
DoRoutine(int, int)

PushFunction

public static int PushFunction(String name)
                        throws CacheException,
                               CallinException
Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value). Execution begins at the top of the routine and the routine is located in the default namespace.

COS Equivilent: $$^Function or Do ^Function

Parameters:
name - Name of the routine to call in the current namespace.
Throws:
CacheException
CallinException
See Also:
DoFunction(int, int), CallFunction(int, int)

PushFunction

public static int PushFunction(String tag,
                               String name)
                        throws CacheException,
                               CallinException
Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value). Execution begins at the specified tag in the routine and the routine is located in the current namespace.

COS Equivilent: $$tag^Function or Do tag^Function

Parameters:
name - Name of the routine to call in the current namespace.
tag - tag to begin executation at
Throws:
CacheException
CallinException
See Also:
DoFunction(int, int), CallFunction(int, int)

PushFunction

public static int PushFunction(String tag,
                               int offset,
                               String environment,
                               String name)
                        throws CacheException,
                               CallinException
Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value). Execution begins at the specified tag in the routine and the routine is located in the current namespace.

COS Equivilent: $$tag+offset^|<env>|Function or Do tag+offset^|<env>|Function

Parameters:
name - Name of the routine to call in the current namespace.
tag - tag which is the base of the offset in finding the first line of the routine to execute.
offset - numeric offset from tag to being executation at
Throws:
CacheException
CallinException
See Also:
DoFunction(int, int), CallFunction(int, int)

UnPop

public static void UnPop()
                  throws CallinException
Decrements the internal Cache' argument stack pointer which pushes the last argument popped back onto the argument stack

Throws:
CallinException

Pop

public static CacheInternalArg Pop()
                            throws CallinException
Removes the argument on the top of the Cache' argument stack which would be something returned from one of the functions in this class that return data from Cache' back to Java such as CallFunction(int,int) or GetGlobal(int,int). The other Pop<type> methods which return the top argument convert it to the specified type. This method returns an opaque structure that can be used to examine the Cache' type of the data and retrieve it in whatever format is required.

Throws:
CallinException

PopInt

public static int PopInt()
                  throws CallinException
Returns the argument on the top of the Cache' argument stack as an integer. If the argument is not already a Cache' integer it is converted based on Cache's data type conversion rules.

Throws:
CallinException

PopFloat

public static float PopFloat()
                      throws CallinException
Returns the argument on the top of the Cache' argument stack as a float. If the argument is not already a Cache' floating point number it is converted based on Cache's data type conversion rules. This may loose precision as floating point numbers in Cache' are 64 bit values.

Throws:
CallinException

PopDouble

public static double PopDouble()
                        throws CallinException
Returns the argument on the top of the Cache' argument stack as a double. If the argument is not already a Cache' floating point number it is converted based on Cache's data type conversion rules.

Throws:
CallinException

PopString

public static String PopString()
                        throws CallinException
Returns the argument on the top of the Cache' argument stack as a string. If the argument is not already a Cache' string, it is converted based on Cache's data type conversion rules.

Throws:
CallinException

PopOref

public static CacheExternalOref PopOref()
                                 throws CallinException
Used when the argument on top of the Cache' argument stack is an internal Cache' object id. If the argument is not an internal object id, an error is returned.

Throws:
CallinException
See Also:
CacheExternalOref

DoRoutine

public static void DoRoutine(int rtnflags,
                             int narg)
                      throws CallinException
Call the routine specified by PushRoutine() passing the arguments stacked with the PushArg methods. The order for calling a routine is first use one of the PushRoutine() methods and save the return value to pass into this method. Then push any arguments to the routine using the PushArg() methods. Finally, call this method to call the routine.

COS Equivilent: Do <tag+offset>^|<env>|Routine(<args>)

Parameters:
rtnflags - value returned from PushRoutine
narg - the number of arguments which are being passed to the routine.
Throws:
CallinException
See Also:
PushRoutine(String), PushRoutine(String,String), PushRoutine(String,int,String,String), PushArg(String), PushArg(int), PushArg(float), PushArg(double)

DoFunction

public static void DoFunction(int rtnflags,
                              int narg)
                       throws CallinException
Execute the function specified by PushFunction() as a routine (discard the return value) passing the arguments stacked with the PushArg methods. The order for calling a function is first use one of the PushFunction() methods and save the return value to pass into this method. Then push any arguments to the function using the PushArg() methods. Finally, call this method to execute the function.

COS Equivilent: Do <tag+offset>^|<env>|Function(<args>)

Parameters:
rtnflags - value returned from PushFunction
narg - the number of arguments which are being passed to the function.
Throws:
CallinException
See Also:
PushFunction(String), PushFunction(String, String), PushFunction(String, int, String, String), PushArg(String), PushArg(int), PushArg(float), PushArg(double)

CallFunction

public static void CallFunction(int rtnflags,
                                int narg)
                         throws CallinException
Call the function specified by PushFunction() using the arguments stacked with the PushArg methods and get a value back. The order for calling a function is first use one of the PushFunction() methods and save the return value to pass into this method. Then push any arguments to the function using the PushArg() methods. Finally, call this method to execute the function. The return value from the function is left on the top of the Cache' internal argument stack and is retrieved using one of the Pop methods.

Warning: No error will be generated if you use PushRoutine() to set up the function name that you want to call and the routine will be executed but the return value will be unpredictable when you pop it off the argument stack. This will be resolved in a future release of Cache' at which point an error will be generated.

COS Equivilent: s res=$$<tag+offset>^|<env>|Function(<args>)

Parameters:
rtnflags - value returned from PushFunction
narg - the number of arguments which are being passed to the function.
Throws:
CallinException
See Also:
PushFunction(String), PushFunction(String, String), PushFunction(String, int, String, String), PushArg(String), PushArg(int), PushArg(float), PushArg(double)

InvokeClassMethod

public static void InvokeClassMethod(int narg)
                              throws CallinException
Execute the class method specified by PushClassMethod() passing the arguments set up with the PushArg methods. The order for invoking a a class method is first use PushClassMethod() to specify the class name and the method to invoke. Then push any arguments using the PushArg() methods and finally,call this method to execute the class method.

COS Equivilent: <tba>

Parameters:
narg - the number of arguments which are being passed to the class method.
Throws:
CallinException
See Also:
PushClassMethod(String, String, int), PushArg(String), PushArg(int), PushArg(float), PushArg(double)

InvokeMethod

public static void InvokeMethod(int narg)
                         throws CallinException
Execute an instance method specified by PushMethod() passing the arguments set up with the PushArg methods. The order for invoking a an instance method is first use PushMethod() to specify the object and the method to invoke. Then push any arguments using the PushArg() methods and finally, call this method to execute the instance method.

COS Equivilent: <tba>

Parameters:
narg - the number of arguments which are being passed to the instance method.
Throws:
CallinException
See Also:
PushMethod(CacheExternalOref, String, int), PushArg(String), PushArg(int), PushArg(float), PushArg(double)

GetProperty

public static void GetProperty()
                        throws CallinException
Retrieve the value of a class property. The object reference and the property name are pushed with PushProperty() and this is used to retrieve the data. The result is left on the internal Cache' argument stack and is retrieved with the Pop() methods.

COS Equivilent: <tba>

Throws:
CallinException
See Also:
PushProperty(CacheExternalOref, String)

SetProperty

public static void SetProperty()
                        throws CallinException
Sets the the value of a class property. The object reference and the property name are pushed with PushProperty(). The value is then pushed with one of the PushArg() methods. This is then run to execute the operation.

COS Equivilent: <tba>

Throws:
CallinException
See Also:
PushProperty(CacheExternalOref, String)

GetLocal

public static void GetLocal(String name)
                     throws CallinException,
                            CacheException
Retrieves the value of the specified local variable. This does not accept array references.

WARNING: May not be implemented in which case an error will always be returned.

COS Equivilent: s x=<local variable reference>

Throws:
CallinException
CacheException

SetLocal

public static void SetLocal(String name)
                     throws CallinException,
                            CacheException
Sets the value of the specified local variable. This does not accept array references. The value to be set has already been pushed with one of the PushArg() methods.

WARNING: May not be implemented in which case an error will always be returned.

COS Equivilent: s x=<local variable reference>

Throws:
CallinException
CacheException
See Also:
PushArg(String), PushArg(int), PushArg(float), PushArg(double)

GetGlobal

public static void GetGlobal(int narg,
                             int undefok)
                      throws CallinException
Retrieves the value of the global reference specified by PushGlobal() and PushArg(). To use this method push the global name (and optionally environment string) using PushGlobal and push the subscripts in left to right order with PushArg(). The value of the global reference is left on the top of the Cache' internal argument stack and is retrieved using one of the Pop methods.

COS Equivilent: s res=^|<env>|GlobalRef

Parameters:
narg - the number of subscripts in the global reference stacked
undefok - TRUE means that if the global reference is not defined the operation returns NULL on the stack. FALSE means that an exception will be thrown.
Throws:
CallinException
See Also:
PushGlobal(String), PushGlobal(String,String), PushArg(String), PushArg(int), PushArg(float), PushArg(double)

SetGlobal

public static void SetGlobal(int narg)
                      throws CallinException
Sets the value of the global reference specified by PushGlobal() and PushArg(). To use this method push the global name (and optionally environment string) using PushGlobal and push the subscripts in left to right order with PushArg(). Finally, push the value you want to set the global to. Call this method to execute the operation.

COS Equivilent: s ^|<env>|GlobalRef(<subscripts>)=<value>

Parameters:
narg - the number of subscripts in the global reference stacked
Throws:
CallinException
See Also:
PushGlobal(String), PushGlobal(String,String), PushArg(String), PushArg(int), PushArg(float), PushArg(double)

Execute

public static void Execute(String cmd)
                    throws CallinException
Execute a COS statement as if it was passed to the COS Execute command. Does not return any results.

COS Equivilent: XECUTE "<cmd>"

Parameters:
cmd - the string to be executed as a COS statement
Throws:
CallinException

Evaluate

public static void Evaluate(String cmd)
                     throws CallinException
Evaluate a COS expression as if it was specified on the right hand side of an equals sign. The result is stored on the top of the stack and can be retrieved with the Pop methods.

COS Equivilent: s res=<expression>

Parameters:
cmd - the string to be evaluated as a COS expression
Throws:
CallinException

ErrorMessage

public static String ErrorMessage(int code)
                           throws CallinException
Return the text of the error message associated with the specified code. Code is returned from CacheException.getCode(). If this method is passed an unknown error code, a message to that effect is returned instead of the actual error text.

Note: Certain error codes returned from the methods of this class cannot be translated with this method. These are the CACHE_ER* fields defined in this class. This restriction may be addressed in the future.

Parameters:
code - error code to translate
Throws:
CallinException
See Also:
CacheException.getCode()

TopArgType

public static int TopArgType()
                      throws CallinException
Return the type of the top argument on the Cache' argument stack, if its a valid argument. If there isn't a valid argument, CACHE_ERNORES is returned.

Returns:
argtype which is one of the following: CACHE_TYPE_INT, CACHE_TYPE_DOUBLE, CACHE_TYPE_STRING, CACHE_TYPE_OREF.
Throws:
CallinException