com.omnipilot.lassopro
Class LassoCall

java.lang.Object
  extended bycom.omnipilot.lassopro.LassoCall

public class LassoCall
extends java.lang.Object

The core of the Lasso Java API v8.0. All the interaction between an LJAPI module and Lasso Professional is achieved by a means of invoking various methods implemented in this class. These functions can be used to perform the following tasks:

Most methods return the result code - either NOERR if the function succeeds, or an error code indicating there was a problem during this method execution.

See Also:
LassoDSModule, LassoTagModule, LassoErrors

Field Summary
protected  int NOERR
           
 
Constructor Summary
protected LassoCall()
           
 
Method Summary
 int acquireSem(java.lang.String named)
          Acquires a previously created semaphore.
 int addColumnInfo(java.lang.String name, int nullOK, int type, int protection)
          Adds information about a particular column.
Column information should be added in the order in which the columns occur in the database.
 int addColumnInfo2(java.lang.String name, int nullOK, int type, int protection, java.lang.String[] valueList)
          Adds information, including valuelists, about a particular column.
Column information should be added in the order in which the columns occur in the database.
 int addDataSourceResult(java.lang.String data)
          Adds a datasource result value.
 int addResultHeader(java.lang.String header)
          Appends the supplied data to the header.
 int addResultRow(byte[][] columns)
          Another way to add the column binary data for the next result row.
 int addResultRow(java.lang.String[] columns)
          Adds all the column data for the next result row.
 int arrayGetElement(LassoTypeRef array, int index, LassoTypeRef outElement)
          Retrieves the specified element of the provided array instance.
 int arrayGetSize(LassoTypeRef array, IntValue outLen)
          Retrieves the size of the provided array instance.
 int arrayRemoveElement(LassoTypeRef array, int index)
          Removes the specified element from the provided array instance.
 int arraySetElement(LassoTypeRef array, int index, LassoTypeRef element)
          Sets the specified element of the provided array instance.
 int childrenRun(LassoTypeRef outResult)
          Execute the contents of a container tag.
 int createSem(java.lang.String named)
          Creates a named semaphore object.
 int destroySem(java.lang.String named)
          Destroys existing semaphore.
 int findInputColumn(java.lang.String named, LassoValue outColumn)
          Gets an individual input column by name.
 int findTag(java.lang.String named, LassoTypeRef outTag, boolean disableOnDemand)
          Searches for a tag.
 int findTagParam(java.lang.String paramName, LassoValue outParam)
          Finds and fetches a tag param by name.
 int findTagParam2(java.lang.String paramName, LassoTypeRef outType)
          Retrieves a parameter that was passed to the LJAPI tag call.
 int formatBuffer(java.lang.String buffer, LassoValue outResult)
          Formats the supplied buffer and puts the resulting data in the data field of the LassoValue.
 java.lang.String fullyQualifyPath(java.lang.String relativePath)
          Converts a relative path into a from-the-server-root path.
 boolean getAutoResolveFullPaths()
          Retreives Lasso's current file resolution mode.
 java.lang.String getCookieValue(java.lang.String named)
          Retrieves a cookie value set by the client.
 int getCookieValue(java.lang.String named, LassoValue outValue)
          Retrieves a cookie value set by the client.
 int getDataHost(LassoValue outHost, LassoValue outUsernamePassword)
          Returns the host that maintains the current database.
 int getDataHost(LassoValue outHost, LassoValue outDefaultSchema, LassoValue outUsernamePassword)
          Returns the host that maintains the current database.
 int getDataHostID(IntValue outID)
          Returns the host id (for internal use only).
 int getDataSourceModuleName(LassoValue outName)
          Returns the name the current datasource module was registered with.
 int getDataSourceName(LassoValue outName, IntValue outUseHostDefault, LassoValue outUsernamePassword)
          Gets the currently specified database name and associated data.
 java.lang.Object getDSConnection()
          Returns the current datasource connection object, or null if no connection has been set yet.
 int getInputColumn(int index, LassoValue outColumn)
          Gets an individual input column by index.
 int getInputColumnCount(IntValue outCount)
          Gets the number of input columns for this database action.
static java.lang.String getInternalPath(java.lang.String platformPath)
          Converts a platform-specific pathname into an internal pathname.
 int getIsStatementOnly()
          Used to check for the -statementonly LDML inline param.
 int getLassoParam(int key, LassoValue outParam)
          Fetches an internal server-specific variable.
 int getLogicalOp(IntValue outOp)
          Gets the logical operator for this database action.
 int getMaxRows(IntValue outRows)
          The maximum number of rows in the found set to return.
static java.lang.String getPlatformSpecificPath(java.lang.String internalPath)
          Converts an internal pathname into a platform-specific pathname.
 int getPrimaryKeyColumn(LassoValue outColumn)
          Gets the name and the value of the currently specified primary key column.
 int getPrimaryKeyColumn2(int index, LassoValue outColumn)
          Gets the name and the value of the indexed primary key column.
 int getRequestParam(int key, LassoValue outParam)
          Fetches a request-specific variable.
 int getResultHeader(LassoValue outHeader)
          Allows access to the result (HTTP) header.
 int getReturnColumn(int index, LassoValue outColumn)
          Gets an individual return column by index.
 int getReturnColumnCount(IntValue outCount)
          Gets the number of return columns for this action.
 int getRowID(IntValue outId)
          Gets the currently specified record id (FileMaker-specific).
 int getSchemaName(LassoValue outName)
          Gets the currently specified schema name.
 int getSiteID()
           
 java.lang.String getSiteName()
           
 int getSkipRows(IntValue outRows)
          The number of rows that should be skipped in the found set.
 int getSortColumn(int index, LassoValue outColumn)
          Gets an individual sort column by index.
 int getSortColumnCount(IntValue outCount)
          Gets the number of sort columns for this database action.
 int getTableName(LassoValue outName)
          Gets the currently specified table name.
 int getTagEncoding(IntValue outMethod)
          Deprecated.  
 int getTagName(LassoValue outName)
          Fetches the name of the tag that triggered this call.
 int getTagParam(int paramIndex, LassoValue outParam)
          Fetches the indicated parameter that was sent to the tag.
 int getTagParam2(int paramIndex, LassoTypeRef outType)
          Retrieves a parameter that was passed to the LJAPI tag call.
 int getTagParamCount(IntValue outCount)
          Fetches the number of parameters that were passed to the tag.
 int getTagReturnValue(LassoTypeRef outValue)
          Provides direct access to the LJAPI tag's return value.
 int getTagSelf(LassoTypeRef outSelf)
          Returns the type instance that the current tag call was a member of.
 int getVariable(java.lang.String named, int index, LassoValue outValue)
          Deprecated.  
 int getVariable2(java.lang.String named, LassoTypeRef outValue)
          Provides access to a defined variable.
 int getVariableCount(java.lang.String named, IntValue outCount)
          Deprecated.  
static java.lang.String getVersion()
          Returns LJAPI version string
 byte[] handleExternalConversion(LassoTypeRef inInstance, java.lang.String inEncoding)
          The basis of table-level automatic encoding and translation.
 int handleInternalConversion(byte[] inData, java.lang.String inEncoding, int inClosestLassoType, LassoTypeRef outType)
          Converts a single-byte or binary representation of a Lasso type BACK INTO an instance of that type
 int includeRaw(java.lang.String filePath, LassoValue out)
          Works just like the include tag.
 int isAdministrator()
          Checks the current request for administrator privileges.
 int isAnonymous()
          Checks the current request for the lowest privilege level.
 boolean isFullInternalPath(java.lang.String path)
          Tests the given internal path to see if it is a full path from the filesystem root.
 int isLassoLite()
          Returns NOERR if Lasso edition is LassoLite.
 boolean isValid()
          Returns true if a native object instance this LassoCall refers to has not been destroyed yet.
 java.lang.String internalToFullPlatformPath(java.lang.String relativeOrFullInternalPath)
          Converts an internal path into a full platform specific path.
static int log(int msgLevel, java.lang.String message)
          Log a message.
 int mapFindElement(LassoTypeRef map, LassoTypeRef key, LassoTypeRef outElement)
          Searches for the specified key in the provided map instance.
 int mapGetElement(LassoTypeRef map, int index, LassoTypeRef outPair)
          Retrieves the specified element of the provided map instance by index.
 int mapGetSize(LassoTypeRef map, IntValue outLen)
          Retrieves the size of the provided map instance.
 int mapRemoveElement(LassoTypeRef map, LassoTypeRef key)
          Removes the specified element from the map based on the provided key.
 int mapSetElement(LassoTypeRef map, LassoTypeRef key, LassoTypeRef value)
          Sets the specified element of the provided map instance.
 int operationAllowed(int secureOperation, java.lang.String internalPathname)
          Tests for file access permissions.
 int outputTagBytes(byte[] data)
          Output some data onto the page.
 int outputTagData(byte[] data)
          Output some data onto the page.
 int outputTagData(java.lang.String data)
          Deprecated.  
 int pairGetFirst(LassoTypeRef pair, LassoTypeRef outValue)
          Retrieves the first member from the provided pair.
 int pairGetSecond(LassoTypeRef pair, LassoTypeRef outValue)
          Retrieves the second member from the provided pair.
 int pairSetFirst(LassoTypeRef pair, LassoTypeRef first)
          Sets the first member of the provided pair.
 int pairSetSecond(LassoTypeRef pair, LassoTypeRef second)
          Sets the second member of the provided pair.
static int registerConstant(java.lang.String name, LassoTypeRef val)
          Register a constant value.
static int registerConstant2(java.lang.String namespaceName, java.lang.String name, LassoTypeRef val)
          Register a constant value.
 int releaseSem(java.lang.String named)
          Releases previously aquired semaphore.
 int removeVariable(java.lang.String named, int index)
          Deprecated.  
 java.lang.String resolveIncludePath(java.lang.String partialPath)
          Converts a partial path into a full, from the file system root, internal path which is guaranteed to be within the web root.
 java.lang.String resolvePath(java.lang.String partialPath)
          Converts a partial path into a full, from the file system root, internal path.
 int returnTagValue(boolean value)
          Return a boolean value from the current LJAPI tag call.
 int returnTagValue(byte[] value)
          Return binary data from the current LJAPI tag call.
 int returnTagValue(double value)
          Return a decimal value from the current LJAPI tag call.
 int returnTagValue(LassoTypeRef value)
          Specifies the return value of the current LJAPI tag call.
 int returnTagValue(long value)
          Return an integer value from the current LJAPI tag call.
 int returnTagValue(java.lang.String value)
          Return a string value from the current LJAPI tag call.
static int runRequest(java.lang.String className, java.lang.String methodName, int tagAction, int unused)
          Creates and runs a new LJAPI call on the given Java module method.
 int setActionStatement(java.lang.String statement)
          Called to set the statement for the current action.
 int setAutoResolveFullPaths(boolean to)
          Toggles how Lasso resolves file paths.
 int setDSConnection(java.lang.Object inConnection)
          Called to set the current connection object for the datasource.
 int setNumRowsFound(int numRows)
          Sets the number of rows found in the query.
 int setResultCode(int err)
          Sets the result code that can be displayed.
 int setResultHeader(java.lang.String header)
          Sets the result (HTTP) header.
 int setResultMessage(java.lang.String msg)
          Sets the result message string
 int setRowID(int id)
          Sets the currently specified record id (FileMaker-specific).
 int setVariable(java.lang.String named, java.lang.String value, int index)
          Deprecated.  
 int setVariable2(java.lang.String named, LassoTypeRef value)
          Sets the specified variable's value.
 int storeGetData(java.lang.String key, LassoValue outValue)
          Fetches data that has been stored.
 int storeHasData(java.lang.String key, IntValue outLength)
          Returns NOERR if the data, specified by key, exists.
 int storePutData(java.lang.String key, byte[] data)
          Adds the data to Lasso's storage.
 int storePutData(java.lang.String key, java.lang.String data)
          Adds the data to Lasso's storage.
 int switchToUser(java.lang.String username, java.lang.String password)
          Switches the current request to the given user.
 int tagGetExpectedParam(LassoTypeRef inTagType, int index, LassoValue outResult, IntValue outRequired)
          Provides access to indexed tag parameter
 int tagGetExpectedParamCount(LassoTypeRef inTagType, IntValue outCount)
          Provides access to tag parameters as specified by the -required/-optional keywords.
 int tagGetReturnType(LassoTypeRef inTagType, LassoValue outResult)
          Provides access to tag parameters as specified by the -returntype keyword
 int tagParamIsDefined(java.lang.String paramName)
          Returns NOERR if the parameter was defined, anything else means it wasn't.
 int tagSetReturnType(LassoTypeRef inTagType, java.lang.String typeName)
          Provides access to tag parameters as specified by the -returntype keywords
 int typeAddMember(LassoTypeRef toType, java.lang.String named, LassoTypeRef member)
          Adds a member to a type instance.
 int typeAddMemberTag(java.lang.String className, java.lang.String methodName, LassoTypeRef toType, java.lang.String tagName)
          Adds a member tag to a type instance.
 int typeAlloc(java.lang.String typeName, LassoTypeRef[] params, LassoTypeRef outType)
          Allocates a new type instance.
 int typeAllocArray(LassoTypeRef outArray, LassoTypeRef[] inElements)
          Allocates a new instance of type array.
 int typeAllocBoolean(LassoTypeRef outBool, boolean value)
          Allocates a new instance of type boolean.
 int typeAllocCustom(LassoTypeRef outCustom, java.lang.String typeName)
          Allocates a custom type within a type initializer.
 int typeAllocDecimal(LassoTypeRef outDecimal, double value)
          Allocates a new instance of type decimal.
 int typeAllocDecimal(LassoTypeRef outDecimal, double value, int precision)
          Allocates a new instance of type decimal with the given precision.
 int typeAllocFromProto(LassoTypeRef inProto, LassoTypeRef outType)
          Allocate a new type instance based on the given type instance.
 int typeAllocInteger(LassoTypeRef outInteger, long value)
          Allocates a new instance of type integer.
 int typeAllocMap(LassoTypeRef outMap, LassoTypeRef[] inElements)
          Allocates a new instance of type map.
 int typeAllocMap(LassoTypeRef outMap, LassoTypeRef[] inKeys, LassoTypeRef[] inValues)
          Allocates a new instance of type map.
 int typeAllocNull(LassoTypeRef outNull)
          Allocates a new instance of type null.
 int typeAllocOneOff(java.lang.String inName, java.lang.String inParentTypeName, LassoTypeRef outType)
          Allocate a new type with the given name.
 int typeAllocPair(LassoTypeRef outPair, LassoTypeRef inFirst, LassoTypeRef inSecond)
          Allocates a new instance of type pair.
 int typeAllocReference(LassoTypeRef outRef, LassoTypeRef referenced)
          Allocates a new hard reference to a type instance.
 int typeAllocString(LassoTypeRef outString, byte[] value)
          Allocates a new instance of type string.
 int typeAllocString(LassoTypeRef outString, java.lang.String value)
          Allocates a new instance of type string.
 int typeAllocStringConv(LassoTypeRef outString, java.lang.String value, java.lang.String conv)
          Allocates a new instance of type string from a Java string using specified encoding.
 int typeAllocTag(LassoTypeRef outTag, java.lang.String className, java.lang.String methodName)
          Allocates a new instance of type tag.
 int typeAllocTagFromSource(LassoTypeRef outTag, java.lang.String source)
          Allocates a new instance of type tag from the given source text.
 int typeAppendString(LassoTypeRef type, java.lang.String value)
          Appends additional data to the string instance.
 int typeAssign(LassoTypeRef left_hand_side, LassoTypeRef right_hand_side)
          typeAssign performs an assignment of one type to another.
 int typeClearFlag(LassoTypeRef type, int flag)
          Removes the flag for the given type instance.
 int typeCollect(LassoTypeRef inType)
          Remove the LJAPI call's reference to a type instance.
 int typeDetach(LassoTypeRef toDetach)
          Prevents the type from being destroyed once the LJAPI call returns.
 int typeFree(LassoTypeRef inType)
          Subtract 1 from an instance's reference count.
 int typeFreeCustomJavaObject(LassoTypeRef type)
          Releases the Java object previously attached to a custom type.
 int typeGetBoolean(LassoTypeRef type, IntValue outValue)
          Retrieves the boolean value from a type instance.
 byte[] typeGetBytes(LassoTypeRef type)
          Retrieves data from a type instance as an array of bytes.
 int typeGetChild(LassoTypeRef from, LassoTypeRef outChild)
          Retrieves the child of the provided instance.
 java.lang.Object typeGetCustomJavaObject(LassoTypeRef type)
          Retrieves the Java object previously attached to a custom type.
 int typeGetDecimal(LassoTypeRef type, DecimalValue outValue)
          Retrieves the decimal value from a type instance.
 int typeGetInteger(LassoTypeRef type, IntValue outValue)
          Retrieves the integer value from a type instance.
 int typeGetMember(LassoTypeRef fromType, java.lang.String named, LassoTypeRef outMember)
          Retrieves a member from a type instance.
 int typeGetName(LassoTypeRef target, LassoValue outName)
          Returns the name of the target type.
 int typeGetParent(LassoTypeRef from, LassoTypeRef outParent)
          Retrieves the parent of the provided type instance.
 int typeGetProperties(LassoTypeRef targetType, LassoTypeRef outPair)
          This method has two uses.
 int typeGetString(LassoTypeRef type, LassoValue outValue)
          Retrieves character data from a type instance.
 int typeHasFlag(LassoTypeRef type, int flag)
          Tests the flag for the given type instance.
 int typeInheritFrom(LassoTypeRef inChild, LassoTypeRef inNewParent)
          Change the inheritence structure of a type.
 int typeIsA(LassoTypeRef target, LassoTypeRef type)
          Tests to see if a type is an instance of another type.
 int typeIsA(LassoTypeRef target, java.lang.String typeName)
          Tests to see if a type is an instance of another type.
 int typename(LassoTypeRef target, LassoValue outName)
          Retrieves the name of the target type.
 int typeRefer(LassoTypeRef toRefer)
          Add 1 to an instance's reference count.
 int typeRunTag(LassoTypeRef tagType, java.lang.String named, LassoTypeRef[] params, LassoTypeRef returnValue, LassoTypeRef optionalTarget)
          Execute a given tag.
 int typeRunTag(LassoTypeRef tagType, java.lang.String named, LassoTypeRef param, LassoTypeRef returnValue, LassoTypeRef optionalTarget)
          Used to execute a given tag.
 int typeSetBoolean(LassoTypeRef type, boolean value)
          Sets the boolean value of a type instance, converting the type if necessary.
 int typeSetBytes(LassoTypeRef type, byte[] value)
          Converts the type instance into a string and sets the value.
 int typeSetCustomJavaObject(LassoTypeRef type, java.lang.Object object)
          typeSetCustomJavaObject permits attachment of Java objects to custom types.
 int typeSetDecimal(LassoTypeRef type, double value)
          Sets the decimal value of a type instance, converting the type if necessary.
 int typeSetDecimal(LassoTypeRef type, double value, int precision)
          Sets the decimal value of a type instance, converting the type if necessary.
 int typeSetFlag(LassoTypeRef type, int flag)
          Sets the flag for the given type instance.
 int typeSetInteger(LassoTypeRef type, long value)
          Sets the integer value of a type instance, converting the type if necessary.
 int typeSetString(LassoTypeRef type, java.lang.String value)
          Converts the type instance into a string and sets the value.
 int typeSetStringConv(LassoTypeRef type, byte[] value, java.lang.String conv)
          Converts the type instance using the specified source data and conversion method.
 int typeStealValue(LassoTypeRef inThief, LassoTypeRef inVictim)
          This function transfers the data from one type to another type.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NOERR

protected int NOERR
Constructor Detail

LassoCall

protected LassoCall()
Method Detail

isValid

public boolean isValid()
Returns true if a native object instance this LassoCall refers to has not been destroyed yet. Always evaluates to false when called outside the scope of the current call.


getVersion

public static java.lang.String getVersion()
Returns LJAPI version string


registerConstant

public static int registerConstant(java.lang.String name,
                                   LassoTypeRef val)
Register a constant value. Constants can be called just like tags, but the resulting value will only have a single instance and will have both it's type and value frozen. This is usually called at the same time that tags are registered.

Parameters:
name - the name for the constant
val - the value for the constant

registerConstant2

public static int registerConstant2(java.lang.String namespaceName,
                                    java.lang.String name,
                                    LassoTypeRef val)
Register a constant value. Constants can be called just like tags, but the resulting value will only have a single instance and will have both it's type and value frozen. This is usually called at the same time that tags are registered

Parameters:
namespaceName - the namespace for the constant
name - the name for the constant
val - the value for the constant
Since:
v8.0

getRequestParam

public int getRequestParam(int key,
                           LassoValue outParam)
Fetches a request-specific variable.

Parameters:
key - one of the RequestParams constants identifying the request variable to retrieve.
outParam - the resulting data for the requested variable. Some request variables require additional input data, which is submitted in this parameter
See Also:
RequestParams

getLassoParam

public int getLassoParam(int key,
                         LassoValue outParam)
Fetches an internal server-specific variable.

Parameters:
key - one of the LassoParams constants identifying the server variable to retrieve
outParam - the resulting value for the server variable.
See Also:
LassoParams

isLassoLite

public int isLassoLite()
Returns NOERR if Lasso edition is LassoLite.


setResultCode

public int setResultCode(int err)
Sets the result code that can be displayed.

Parameters:
err - the result code

setResultMessage

public int setResultMessage(java.lang.String msg)
Sets the result message string


getTagName

public int getTagName(LassoValue outName)
Fetches the name of the tag that triggered this call. For example, in the case of: [my_tag: ...] the resulting value would be "my_tag"

Parameters:
outName - The resulting tag name which will be placed in the name field of the LassoValue object.

getTagParamCount

public int getTagParamCount(IntValue outCount)
Fetches the number of parameters that were passed to the tag.

Parameters:
outCount - an object in which to store the result.

getTagParam

public int getTagParam(int paramIndex,
                       LassoValue outParam)
Fetches the indicated parameter that was sent to the tag. Parameter indexes start at zero. If the parameter was specified as a keyword/value pair, the keyword will be placed in the name field, and the value in the data. If the parameter was provided without a keyword, the name portion of the struct will be null. All parameters values will be converted to string, regardless of the original type

Parameters:
paramIndex - the zero-based index of the desired parameter
outParam - the resulting parameter data

tagParamIsDefined

public int tagParamIsDefined(java.lang.String paramName)
Returns NOERR if the parameter was defined, anything else means it wasn't. Only parameters specified with a keyword should be searched for.

Parameters:
paramName - rhe name of the keyworded parameter to search for.

findTagParam

public int findTagParam(java.lang.String paramName,
                        LassoValue outParam)
Finds and fetches a tag param by name. A return value of NOERR means the param was found. The parameter that was passed to the LJAPI tag call must have been specified by keyword. The keyword will be placed in the name field of the LassoValue object, and the value - in the data portion. If only a keyword was provided, the data field will be null.

Parameters:
paramName - the keyword of the desired parameter.
outParam - the resulting parameter value.

getTagEncoding

public int getTagEncoding(IntValue outMethod)
Deprecated.  

Fetches the encoding method indicated for this tag.


outputTagData

public int outputTagData(java.lang.String data)
Deprecated.  

Output some data onto the page.


outputTagData

public int outputTagData(byte[] data)
Output some data onto the page. Suitable for returning binary data.


outputTagBytes

public int outputTagBytes(byte[] data)
Output some data onto the page. Alias for returnTagValueBytes.


getResultHeader

public int getResultHeader(LassoValue outHeader)
Allows access to the result (HTTP) header. The data will be a copy of the current HTTP header data.

Parameters:
outHeader - on return, contains the header data in the name field

setResultHeader

public int setResultHeader(java.lang.String header)
Sets the result (HTTP) header. The data will be set as-is, so make sure it is properly formatted. The data should not include the final trailing CRLF pair.

Parameters:
header - the header data to use

addResultHeader

public int addResultHeader(java.lang.String header)
Appends the supplied data to the header. The data will be set as-is, so make sure it is properly formatted. The data should not include the final trailing CRLF pair.

Parameters:
header - the header data to use

getCookieValue

public int getCookieValue(java.lang.String named,
                          LassoValue outValue)
Retrieves a cookie value set by the client.

Parameters:
named - the name of the cookie to look for
outValue - the resulting cookie value which will be placed in the name portion of the struct.

getCookieValue

public java.lang.String getCookieValue(java.lang.String named)
Retrieves a cookie value set by the client.

Parameters:
named - the name of the cookie to look for
Returns:
the resulting cookie value, or null if cookie wasn't found
Since:
v8.0

getVariableCount

public int getVariableCount(java.lang.String named,
                            IntValue outCount)
Deprecated.  


getVariable

public int getVariable(java.lang.String named,
                       int index,
                       LassoValue outValue)
Deprecated.  


setVariable

public int setVariable(java.lang.String named,
                       java.lang.String value,
                       int index)
Deprecated.  


removeVariable

public int removeVariable(java.lang.String named,
                          int index)
Deprecated.  


addDataSourceResult

public int addDataSourceResult(java.lang.String data)
Adds a datasource result value. Datasource actions which require returning multiple values can use this to add those values. For example, this call can be used to add the name of a datasource that the module services or the names of the tables in a particular datasource. getInputColumn & findInputColumn can be used by tags to get input form params.

Parameters:
data - the data to add. (TBD: Data must be in ISO8859-1 encoding.)

getDataSourceName

public int getDataSourceName(LassoValue outName,
                             IntValue outUseHostDefault,
                             LassoValue outUsernamePassword)
Gets the currently specified database name and associated data.

Parameters:
outName - on return, contains the database name stored in the data field.
outUseHostDefault - the setting which specifies whether the hosts username/password combo should be used in the absence of a database specific combo
outUsernamePassword - user name and password to be used for logging in to the datasource host.

getTableName

public int getTableName(LassoValue outName)
Gets the currently specified table name.

Parameters:
outName - on return, contains the table name stored in the name field.

getSchemaName

public int getSchemaName(LassoValue outName)
Gets the currently specified schema name.

Parameters:
outName - on return, contains the schema name stored in the name field.

getDataHost

public int getDataHost(LassoValue outHost,
                       LassoValue outUsernamePassword)
Returns the host that maintains the current database.

Parameters:
outHost - the host address and port number strings are returned in the name and data fields, respectively
outUsernamePassword - host default username and password, if any

getDataHost

public int getDataHost(LassoValue outHost,
                       LassoValue outDefaultSchema,
                       LassoValue outUsernamePassword)
Returns the host that maintains the current database. Similar to the previous method, but also returns default host schema.


getDataHostID

public int getDataHostID(IntValue outID)
Returns the host id (for internal use only).


getSkipRows

public int getSkipRows(IntValue outRows)
The number of rows that should be skipped in the found set. See -skiprecords LDML parameter reference for more info.


getMaxRows

public int getMaxRows(IntValue outRows)
The maximum number of rows in the found set to return. See -skiprecords LDML parameter reference for more info.


getRowID

public int getRowID(IntValue outId)
Gets the currently specified record id (FileMaker-specific). See -keyvalue LDML parameter reference for more info.

Parameters:
outId - the resulting numeric -keyvalue param value

setRowID

public int setRowID(int id)
Sets the currently specified record id (FileMaker-specific).

Parameters:
id - the numeric row id.

getPrimaryKeyColumn

public int getPrimaryKeyColumn(LassoValue outColumn)
Gets the name and the value of the currently specified primary key column.

Parameters:
outColumn - on return, contains the resulting key name and value.

getPrimaryKeyColumn2

public int getPrimaryKeyColumn2(int index,
                                LassoValue outColumn)
Gets the name and the value of the indexed primary key column.

Parameters:
index - the zero-based column index
outColumn - on return, contains the resulting key name and value

getInputColumnCount

public int getInputColumnCount(IntValue outCount)
Gets the number of input columns for this database action.


getSortColumnCount

public int getSortColumnCount(IntValue outCount)
Gets the number of sort columns for this database action.


getInputColumn

public int getInputColumn(int index,
                          LassoValue outColumn)
Gets an individual input column by index.

Parameters:
index - the zero-based index of the column to retrieve.

getSortColumn

public int getSortColumn(int index,
                         LassoValue outColumn)
Gets an individual sort column by index.

Parameters:
index - the zero-based index of the sort column to retrieve
Returns:
the resulting column name and value, or null on error

findInputColumn

public int findInputColumn(java.lang.String named,
                           LassoValue outColumn)
Gets an individual input column by name.

Parameters:
named - the name of the input column to retrieve

getLogicalOp

public int getLogicalOp(IntValue outOp)
Gets the logical operator for this database action.

Parameters:
outOp - on return, one of the LassoOperators constants

getReturnColumnCount

public int getReturnColumnCount(IntValue outCount)
Gets the number of return columns for this action.

Parameters:
outCount - on return, contains the resulting number of return columns

getReturnColumn

public int getReturnColumn(int index,
                           LassoValue outColumn)
Gets an individual return column by index.

Parameters:
index - the zero-based index of the return column to retrieve
outColumn - on return, contains the resulting column name and value

addColumnInfo

public int addColumnInfo(java.lang.String name,
                         int nullOK,
                         int type,
                         int protection)
Adds information about a particular column.
Column information should be added in the order in which the columns occur in the database. Column information should be added no matter what the action. For the show action, only column information is added.

Parameters:
name - the column name
nullOK - does the column type allows null values?
type - column type: TYPE_CHAR, TYPE_INT, TYPE_BOOLEAN, TYPE_DECIMAL, TYPE_DATETIME or TYPE_BLOB
protection - is column value read only? Should be either PROTECTION_NONE or PROTECTION_READ_ONLY
See Also:
LassoValue, LassoDSModule

addColumnInfo2

public int addColumnInfo2(java.lang.String name,
                          int nullOK,
                          int type,
                          int protection,
                          java.lang.String[] valueList)
Adds information, including valuelists, about a particular column.
Column information should be added in the order in which the columns occur in the database. Column information should be added no matter what the action is. For the show action, only column information is added.

Parameters:
name - the column name
nullOK - is a null value for this column ok?
type - one of the data types defined in LassoDSModule
protection - the code for the column's protection: either PROTECTION_NONE or PROTECTION_READ_ONLY
valueList - an array of strings for the column's valuelist.
Since:
v8.0

addResultRow

public int addResultRow(java.lang.String[] columns)
Adds all the column data for the next result row.

Parameters:
columns - an array of column values

addResultRow

public int addResultRow(byte[][] columns)
Another way to add the column binary data for the next result row.
        String data[] = { "apples", "oranges", "pears", "cherries" };

        int count = data.length;
        byte cols[][] = new byte[count][];

        for ( i = 0; i < count; i++ )
            cols[i] = data[i].getBytes();

        lasso.addResultRow( cols );
        


setNumRowsFound

public int setNumRowsFound(int numRows)
Sets the number of rows found in the query. This will not always be the same value as the number of rows added with the addResultRow call. as the skip recs and max recs parameters effect that number.


getDataSourceModuleName

public int getDataSourceModuleName(LassoValue outName)
Returns the name the current datasource module was registered with.

Parameters:
outName - on return, contains the datasource module name in the name field.

getDSConnection

public java.lang.Object getDSConnection()
Returns the current datasource connection object, or null if no connection has been set yet.

Since:
v7.0

setDSConnection

public int setDSConnection(java.lang.Object inConnection)
Called to set the current connection object for the datasource. May recurse to deliver the ACTION_CLOSE message if there is already a valid db connection. Once set, the connection could be retrieved from a nested LDML "inline" call.

Parameters:
inConnection - an object representing valid datasource connection.
Since:
v7.0

setActionStatement

public int setActionStatement(java.lang.String statement)
Called to set the statement for the current action. Datasources must call this to support the action_statement LDML tag.

Parameters:
statement - the action statement value
Since:
v8.0

getIsStatementOnly

public int getIsStatementOnly()
Used to check for the -statementonly LDML inline param.

Returns:
NOERR if -statementonly keyword is present
Since:
v8.0

acquireSem

public int acquireSem(java.lang.String named)
Acquires a previously created semaphore. Semaphores are a means by which access to shared resources can be controlled amongst several threads of execution. Each semephore must have a unique name. Always release semaphores as soon as possible.


createSem

public int createSem(java.lang.String named)
Creates a named semaphore object.

See Also:
acquireSem

destroySem

public int destroySem(java.lang.String named)
Destroys existing semaphore.

See Also:
acquireSem

releaseSem

public int releaseSem(java.lang.String named)
Releases previously aquired semaphore.

See Also:
acquireSem

formatBuffer

public int formatBuffer(java.lang.String buffer,
                        LassoValue outResult)
Formats the supplied buffer and puts the resulting data in the data field of the LassoValue. The buffer should consist of plain text and bracketed Lasso tags.

Parameters:
buffer - the buffer holding the script data
outResult - on return, contains the resulting value

includeRaw

public int includeRaw(java.lang.String filePath,
                      LassoValue out)
Works just like the include tag.


storeHasData

public int storeHasData(java.lang.String key,
                        IntValue outLength)
Returns NOERR if the data, specified by key, exists. The length of the stored data can be returned in the length parameter. This parameter may be null if the length is not required.


storePutData

public int storePutData(java.lang.String key,
                        java.lang.String data)
Adds the data to Lasso's storage. key is the unique identifier for the data.


storePutData

public int storePutData(java.lang.String key,
                        byte[] data)
Adds the data to Lasso's storage. key is the unique identifier for the data.


storeGetData

public int storeGetData(java.lang.String key,
                        LassoValue outValue)
Fetches data that has been stored. The data will be returned in the data field of the LassoValue object.

Parameters:
key - the unique identifier for the data.

isAdministrator

public int isAdministrator()
Checks the current request for administrator privileges. Returns NOERR is the current user has administrator priveleges. This is useful for doing administrative activities or file accesses which only the admin should be able to do.


isAnonymous

public int isAnonymous()
Checks the current request for the lowest privilege level. Returns NOERR if the current user is the anonymous user.

Since:
v8.0

switchToUser

public int switchToUser(java.lang.String username,
                        java.lang.String password)
Switches the current request to the given user. A proper password must be provided. The switch will persist until the request is finished or is switches again. Pass "anonymous" with no password to switch to the lowest privileges.

Since:
v7.0

operationAllowed

public int operationAllowed(int secureOperation,
                            java.lang.String internalPathname)
Tests for file access permissions. Returns NOERR is the given operation is permitted by Lasso security.

Parameters:
secureOperation - one of the constants defined in LassoSecureOperations class
internalPathname - full path to the file using the internal pathname format

getPlatformSpecificPath

public static java.lang.String getPlatformSpecificPath(java.lang.String internalPath)
Converts an internal pathname into a platform-specific pathname.

Parameters:
internalPath - the internal pathname.
Returns:
the resulting platform specific pathname

getInternalPath

public static java.lang.String getInternalPath(java.lang.String platformPath)
Converts a platform-specific pathname into an internal pathname.

Parameters:
platformPath - the platform-specific path name
Returns:
the resulting internal pathname

fullyQualifyPath

public java.lang.String fullyQualifyPath(java.lang.String relativePath)
Converts a relative path into a from-the-server-root path. If the path is already from the root it won't be changed.

Parameters:
relativePath - the relative path
Returns:
the resulting fully-qualified path

resolvePath

public java.lang.String resolvePath(java.lang.String partialPath)
Converts a partial path into a full, from the file system root, internal path.

Parameters:
partialPath - the path to resolve
Returns:
the resulting full path

resolveIncludePath

public java.lang.String resolveIncludePath(java.lang.String partialPath)
Converts a partial path into a full, from the file system root, internal path which is guaranteed to be within the web root.

Parameters:
partialPath - the path to resolve. Must name an item within the web-root or a blank string is returned
Returns:
the resulting full path
Since:
v8.0

internalToFullPlatformPath

public java.lang.String internalToFullPlatformPath(java.lang.String relativeOrFullInternalPath)
Converts an internal path into a full platform specific path. Takes a path, such as one which may have been passed to any Lasso tag, and converts it into a full platform specific path name.

Parameters:
relativeOrFullInternalPath - The input path to convert
Returns:
the resulting converted path
Since:
v8.0 #omnipilot

isFullInternalPath

public boolean isFullInternalPath(java.lang.String path)
Tests the given internal path to see if it is a full path from the filesystem root.

Parameters:
path - the path to test
Returns:
true if the given internal path is a full path from the filesystem root
Since:
v8.0

setAutoResolveFullPaths

public int setAutoResolveFullPaths(boolean to)
Toggles how Lasso resolves file paths. Toggles whether Lasso will resolve the entire given file path (/blah/file.lasso) through the webserver (the default behavior: true) OR whether Lasso will resolve "/" through the server and then prepend that to the given file path (false). The default behavior can conflict with some usages of mod_rewrite. As of LP7, this setting is global.

Parameters:
to - the toggle
Since:
v8.0

getAutoResolveFullPaths

public boolean getAutoResolveFullPaths()
Retreives Lasso's current file resolution mode.

Returns:
true if Lasso will resolve the given file path through the webserver
Since:
v8.0
See Also:
setAutoResolveFullPaths

typeAlloc

public int typeAlloc(java.lang.String typeName,
                     LassoTypeRef[] params,
                     LassoTypeRef outType)
Allocates a new type instance. The name of the type is signified by the first parameter. If a type initializer is found for the given name, it will be executed. A type allocated in this manner will be added to the garbage list for later destruction.

Parameters:
typeName - the name of the type to instantiate
params - an array of parameters to pass to the type initializer. Could be null
outType - a storage for the newly instantiated type

typeAllocCustom

public int typeAllocCustom(LassoTypeRef outCustom,
                           java.lang.String typeName)
Allocates a custom type within a type initializer. This function is used within module methods that were registered as being a type initializer (FLAG_INITIALIZER). It initializes a blank custom type and sets the type's name to the provided value. The new type does not yet have a lineage and has no members added to it. New data or tag members should be added using typeAddMember. The new type should be the return value of the tag call, set via returnTagValue. Any inherited members will be added to the type after the LJAPI call returns.

Warning: Do not call this unless you are in a type initializer. If you are not in a type initializer, the result will be a type that will never be fully initialized.

Parameters:
outCustom - the resulting newly allocated custom type
typeName - the new type's name.

typeAllocFromProto

public int typeAllocFromProto(LassoTypeRef inProto,
                              LassoTypeRef outType)
Allocate a new type instance based on the given type instance. The given type's tag members will be referenced in the new type. No data members are added except for the typename member.

Parameters:
inProto - the original type instance whose tag members will be referenced
outType - the resulting new type instance
Since:
v7.0

typeAllocOneOff

public int typeAllocOneOff(java.lang.String inName,
                           java.lang.String inParentTypeName,
                           LassoTypeRef outType)
Allocate a new type with the given name.

The type does not have to have been registered as a type initializer or registered at all. The new type will have no tag or data members, but those may be added using the appropriate LJAPI call at any time. If no parent type is provided (a null or empty string is passed in), type "null" will be the default. If a parent type is provided, it must have been a validly registered type initializer. OnCreate member tag will be called for the parent and any of its parents, but will not be called for the new type instance itself.

Parameters:
inName - the name for the new type instance
inParentTypeName - the name of the parent type
outType - the new type instance, or null on error
Since:
v7.0

typeRefer

public int typeRefer(LassoTypeRef toRefer)
Add 1 to an instance's reference count. Type instances each have a reference count. Types created or otherwise referenced or received during an LJAPI call can be assumed to have a reference count of at least 1. If client code wishes to utilize any type instance beyond the end of the LJAPI call, it should add 1 to the instance's reference count. This is called "referring to" an instance. When client code has finished utilizing any "referred-to" instance, it should subtract 1 from the instance's reference count using typeFree. When a type instance's reference count reaches zero, the instance is destroyed.

Since:
v8.0

typeFree

public int typeFree(LassoTypeRef inType)
Subtract 1 from an instance's reference count. Once the instance's reference count reaches zero, it is destroyed and the LassoTypeRef is no longer valid. The LassoCall token may be null if it is not available for any reason. Warning: ONLY call this if you have previously called typeRefer using the same type instance or the result may be a double free.

Parameters:
inType - the type instance which should be unreferred to

typeCollect

public int typeCollect(LassoTypeRef inType)
Remove the LJAPI call's reference to a type instance. The LJAPI garbage collection system usually holds a reference to any used type instances. Calling this will remove that reference, which may result in the instance being destroyed at that point. Usage of a type pointer after calling this is not permitted unless the type has been "referred" to previously using typeRefer.

Parameters:
inType - the type instance to operate on

typeAllocNull

public int typeAllocNull(LassoTypeRef outNull)
Allocates a new instance of type null.

Parameters:
outNull - The resulting new type instance.

typeAllocString

public int typeAllocString(LassoTypeRef outString,
                           java.lang.String value)
Allocates a new instance of type string.

Parameters:
outString - the resulting new type instance
value - The string data from which to copy for the new string instance

typeAllocString

public int typeAllocString(LassoTypeRef outString,
                           byte[] value)
Allocates a new instance of type string.

Since:
v7.0

typeAllocStringConv

public int typeAllocStringConv(LassoTypeRef outString,
                               java.lang.String value,
                               java.lang.String conv)
Allocates a new instance of type string from a Java string using specified encoding.

Parameters:
outString - the resulting new type instance
value - the source data from which to copy for the new string instance
conv - The encoding of the source data
Since:
v7.0

typeAllocInteger

public int typeAllocInteger(LassoTypeRef outInteger,
                            long value)
Allocates a new instance of type integer.

Parameters:
outInteger - the resulting new type instance
value - the integer value which the new type instance will hold

typeAllocDecimal

public int typeAllocDecimal(LassoTypeRef outDecimal,
                            double value)
Allocates a new instance of type decimal.

Parameters:
outDecimal - the resulting new type instance
value - the double value which the new type instance will hold

typeAllocDecimal

public int typeAllocDecimal(LassoTypeRef outDecimal,
                            double value,
                            int precision)
Allocates a new instance of type decimal with the given precision.

Parameters:
outDecimal - the resulting new type instance
value - the double value which the new type instance will hold
precision - the decimal precision that the new type instance will output to

typeAllocPair

public int typeAllocPair(LassoTypeRef outPair,
                         LassoTypeRef inFirst,
                         LassoTypeRef inSecond)
Allocates a new instance of type pair.

Parameters:
outPair - the resulting new type instance
inFirst - the instance to use for the first member of the pair. A reference to the instance will be made.
inSecond - the instance to use for the second member of the pair. A reference to the instance will be made.

typeAllocReference

public int typeAllocReference(LassoTypeRef outRef,
                              LassoTypeRef referenced)
Allocates a new hard reference to a type instance. The new instance will point to the original.

Parameters:
outRef - the resulting new type instance
referenced - the instance to be referenced

typeAllocTag

public int typeAllocTag(LassoTypeRef outTag,
                        java.lang.String className,
                        java.lang.String methodName)
Allocates a new instance of type tag. Note: The method referred to by className and methodName parameters should have the same signature as TAG_METHOD_PROTOTYPE.

Parameters:
outTag - the resulting new type instance
className - the name of the java class implementing your module
methodName - the name of a java method which will be called when the tag is used

typeAllocTagFromSource

public int typeAllocTagFromSource(LassoTypeRef outTag,
                                  java.lang.String source)
Allocates a new instance of type tag from the given source text.

Parameters:
outTag - the resulting new type instance
source - the source text which will be compiled to become the body of the tag
Since:
v8.0

typeAllocArray

public int typeAllocArray(LassoTypeRef outArray,
                          LassoTypeRef[] inElements)
Allocates a new instance of type array.

Parameters:
outArray - the resulting new type instance
inElements - an array of LassoTypeRef's which will become the elements of the array (each item will be referenced). Can be null

typeAllocMap

public int typeAllocMap(LassoTypeRef outMap,
                        LassoTypeRef[] inElements)
Allocates a new instance of type map. Note that count here for the map must be divisible by 2. Every two elements are taken to be the key and value, respectively.

Parameters:
outMap - the resulting new type instance
inElements - an array of LassoTypeRef's which will become the elements of the map. Each even numbered item will be treated as the key for following element

typeAllocMap

public int typeAllocMap(LassoTypeRef outMap,
                        LassoTypeRef[] inKeys,
                        LassoTypeRef[] inValues)
Allocates a new instance of type map. Same as typeAllocMap, only the map keys and values are passed as separate parameters.

Parameters:
outMap - the resulting new type instance
inKeys - an array of LassoTypeRef's which will become the map keys

typeAllocBoolean

public int typeAllocBoolean(LassoTypeRef outBool,
                            boolean value)
Allocates a new instance of type boolean.

Parameters:
outBool - the resulting new type instance
value - the boolean value which the new type instance will hold

typeStealValue

public int typeStealValue(LassoTypeRef inThief,
                          LassoTypeRef inVictim)
This function transfers the data from one type to another type. Both types must be valid and pre-allocated. After the call, victim will still be valid, but will be of type null.

Since:
v7.0

handleExternalConversion

public byte[] handleExternalConversion(LassoTypeRef inInstance,
                                       java.lang.String inEncoding)
The basis of table-level automatic encoding and translation. Converts a Lasso type INTO single-byte or binary data using the specific encoding name. The default for all database, column, table names should be "iso8859-1"

Since:
v7.0

handleInternalConversion

public int handleInternalConversion(byte[] inData,
                                    java.lang.String inEncoding,
                                    int inClosestLassoType,
                                    LassoTypeRef outType)
Converts a single-byte or binary representation of a Lasso type BACK INTO an instance of that type

Parameters:
inClosestLassoType - desired Lasso type. pass one of the TYPE_XXX constants defined in LassoValue
outType - resulting Lasso type intance
Since:
v7.0

typeGetString

public int typeGetString(LassoTypeRef type,
                         LassoValue outValue)
Retrieves character data from a type instance. If the type is a string instance, the data will be converted to UTF-8.
If the type is a bytes instance, the data will be provided unaltered.
For any other type, the result will be the same as converting the type into a string and returning the data as UTF-8

Parameters:
type - the type instance from which to retrieve the character data
outValue - on return, the data will be stored in the name field of the LassoValue

typeGetBytes

public byte[] typeGetBytes(LassoTypeRef type)
Retrieves data from a type instance as an array of bytes.

Parameters:
type - the type instance from which to retrieve the byte data
Returns:
the resulting byte array
Since:
v7.0

typeGetInteger

public int typeGetInteger(LassoTypeRef type,
                          IntValue outValue)
Retrieves the integer value from a type instance.

Parameters:
type - the type instance from which to retieve the integer value
outValue - on return, contains the resulting 64-bit integer value

typeGetDecimal

public int typeGetDecimal(LassoTypeRef type,
                          DecimalValue outValue)
Retrieves the decimal value from a type instance.

Parameters:
type - the type instance from which to retieve the decimal value
outValue - on return, the resulting double value

typeGetBoolean

public int typeGetBoolean(LassoTypeRef type,
                          IntValue outValue)
Retrieves the boolean value from a type instance.

Parameters:
type - the type instance from which to retieve the boolean value.

typeSetString

public int typeSetString(LassoTypeRef type,
                         java.lang.String value)
Converts the type instance into a string and sets the value.

Parameters:
type - the type instance to set
value - the source string data

typeSetBytes

public int typeSetBytes(LassoTypeRef type,
                        byte[] value)
Converts the type instance into a string and sets the value.

Parameters:
type - the type instance to set
value - the data
Since:
v7.0

typeSetStringConv

public int typeSetStringConv(LassoTypeRef type,
                             byte[] value,
                             java.lang.String conv)
Converts the type instance using the specified source data and conversion method. If the special conversion method of "BINARY" is used, the type instance will be converted into a bytes type, the contents of which will be the unaltered source data. The remaining possible values for the conversion method are any of the character encoding methods supported by ICU or any of the converters stored in the '__internal_converters__' global variable. If any of the built-in ICU conversion methods are used, the provided instance will be converted into a string type. If any other conversion methods are used, the resulting type of the provided instance can can vary.

Parameters:
type - the type instance to be converted
value - the source data to be used for the conversion
conv - the conversion method to use when transforming type instance
Since:
v8.0

typeAppendString

public int typeAppendString(LassoTypeRef type,
                            java.lang.String value)
Appends additional data to the string instance.

Parameters:
type - the type instance which will be appended to
value - the source data to append
Since:
v7.0

typeSetInteger

public int typeSetInteger(LassoTypeRef type,
                          long value)
Sets the integer value of a type instance, converting the type if necessary.

Parameters:
type - the type instance which will be set to the provided integer
value - the integer value to use

typeSetDecimal

public int typeSetDecimal(LassoTypeRef type,
                          double value)
Sets the decimal value of a type instance, converting the type if necessary.

Parameters:
type - the type instance which will be set to the provided double
value - the double value to use

typeSetDecimal

public int typeSetDecimal(LassoTypeRef type,
                          double value,
                          int precision)
Sets the decimal value of a type instance, converting the type if necessary.

Parameters:
type - the type instance which will be set to the provided integer
value - the double value to use
precision - the decimal precision which the decimal instance will output to

typeSetBoolean

public int typeSetBoolean(LassoTypeRef type,
                          boolean value)
Sets the boolean value of a type instance, converting the type if necessary.

Parameters:
type - the type instance which will be set to the provided boolean
value - the boolean value to use.

arrayGetSize

public int arrayGetSize(LassoTypeRef array,
                        IntValue outLen)
Retrieves the size of the provided array instance.

Parameters:
array - the array instance
outLen - on return, contains the resulting size

arrayGetElement

public int arrayGetElement(LassoTypeRef array,
                           int index,
                           LassoTypeRef outElement)
Retrieves the specified element of the provided array instance.

Parameters:
array - the array instance
index - the zero-based index at which to retreive the element
outElement - the resulting element

arraySetElement

public int arraySetElement(LassoTypeRef array,
                           int index,
                           LassoTypeRef element)
Sets the specified element of the provided array instance.

Parameters:
array - the array instance
index - the zero-based index at which to set the element
element - the type instance which will be placed at the specified index. The instance will be referenced

arrayRemoveElement

public int arrayRemoveElement(LassoTypeRef array,
                              int index)
Removes the specified element from the provided array instance.

Parameters:
array - the array instance
index - the zero based index at which to remove

mapGetSize

public int mapGetSize(LassoTypeRef map,
                      IntValue outLen)
Retrieves the size of the provided map instance.

Parameters:
map - the map instance
outLen - on return, contains the resulting map size

mapFindElement

public int mapFindElement(LassoTypeRef map,
                          LassoTypeRef key,
                          LassoTypeRef outElement)
Searches for the specified key in the provided map instance.

Parameters:
map - the map instance
key - the key to search for within the map
outElement - on return, the found map element

mapGetElement

public int mapGetElement(LassoTypeRef map,
                         int index,
                         LassoTypeRef outPair)
Retrieves the specified element of the provided map instance by index.

Parameters:
map - the map instance
index - the zero based index at which to retreive
outPair - the pointer in which to store the result. The result will be a pair whose first member is the key and second member is the associated element

mapSetElement

public int mapSetElement(LassoTypeRef map,
                         LassoTypeRef key,
                         LassoTypeRef value)
Sets the specified element of the provided map instance. If no elements were previously stored under the specified key, the element will be added to the map, otherwise the old element will be replaced by a new value.

Parameters:
map - the map instance
key - the instance of the key which will be set
value - the value of the element to associate with the provided key

mapRemoveElement

public int mapRemoveElement(LassoTypeRef map,
                            LassoTypeRef key)
Removes the specified element from the map based on the provided key.

Parameters:
map - the map instance
key - the key to be removed

pairGetFirst

public int pairGetFirst(LassoTypeRef pair,
                        LassoTypeRef outValue)
Retrieves the first member from the provided pair.

Parameters:
pair - the pair instance
outValue - on return, the resulting type instance

pairGetSecond

public int pairGetSecond(LassoTypeRef pair,
                         LassoTypeRef outValue)
Retrieves the second member from the provided pair.

Parameters:
pair - the pair instance
Returns:
the resulting type instance, or null on error

pairSetFirst

public int pairSetFirst(LassoTypeRef pair,
                        LassoTypeRef first)
Sets the first member of the provided pair.

Parameters:
pair - the pair instance
first - the instance to use as the first member. The instance will be referenced

pairSetSecond

public int pairSetSecond(LassoTypeRef pair,
                         LassoTypeRef second)
Sets the second member of the provided pair.

Parameters:
pair - the pair instance
second - the instance to use as the second member. The instance will be referenced

typeGetProperties

public int typeGetProperties(LassoTypeRef targetType,
                             LassoTypeRef outPair)
This method has two uses. If the targetType parameter is not null, it is used to get all the data and tag members from a given type. They are returned as an array of pairs in the outPair value. The first element of each pair is the map of data members for the type. The second element is the map of tag members. Each element in the array represents the members of each type inherited by the targetType.

If the targetType parameter is null, typeGetProperties will return an array containing the variable maps for the currently active request.


typeInheritFrom

public int typeInheritFrom(LassoTypeRef inChild,
                           LassoTypeRef inNewParent)
Change the inheritence structure of a type. Sets new parent of a child. Any parent that child currently has will be destroyed.

Parameters:
inChild - the child instance which will have its inheritance changed
inNewParent - the new parent for the child
Since:
v7.0

typeGetParent

public int typeGetParent(LassoTypeRef from,
                         LassoTypeRef outParent)
Retrieves the parent of the provided type instance.

Parameters:
from - the child instance from which to retrieve the parent
outParent - on return, the type parent
Since:
v8.0

typeGetChild

public int typeGetChild(LassoTypeRef from,
                        LassoTypeRef outChild)
Retrieves the child of the provided instance.

Parameters:
from - the parent instance from which to retrieve the child
outChild - on return, the resulting child type
Since:
v8.0

typeAddMember

public int typeAddMember(LassoTypeRef toType,
                         java.lang.String named,
                         LassoTypeRef member)
Adds a member to a type instance. If the new member is a tag, it will be added to the tag members for the type. Otherwise, the new member will be added as a data member.

Parameters:
toType - the type instance to which the new member will be added
named - the name for the new member
member - the new member to add

typeGetMember

public int typeGetMember(LassoTypeRef fromType,
                         java.lang.String named,
                         LassoTypeRef outMember)
Retrieves a member from a type instance. Members are searched for by name with tag members being searched first. Data members are searched if no tag is found with the given name.

Parameters:
fromType - the type instance in which to search
named - the name of the member to look for
outMember - on return, the found member

typeAddMemberTag

public int typeAddMemberTag(java.lang.String className,
                            java.lang.String methodName,
                            LassoTypeRef toType,
                            java.lang.String tagName)
Adds a member tag to a type instance. A shortcut for the typeAllocTag/typeAddMember pair.

Since:
v7.0

typeSetFlag

public int typeSetFlag(LassoTypeRef type,
                       int flag)
Sets the flag for the given type instance.

Parameters:
type - the type instance on which to set the flag
flag - the flag to set
Since:
v8.0

typeHasFlag

public int typeHasFlag(LassoTypeRef type,
                       int flag)
Tests the flag for the given type instance. Returns true if the flag is set for that type instance.

Parameters:
type - the type instance to be tested
flag - the flag to test for
Since:
v8.0

typeClearFlag

public int typeClearFlag(LassoTypeRef type,
                         int flag)
Removes the flag for the given type instance.

Parameters:
type - the type instance
flag - the flag to remove from the type instance
Since:
v8.0

typename

public int typename(LassoTypeRef target,
                    LassoValue outName)
Retrieves the name of the target type.


getTagSelf

public int getTagSelf(LassoTypeRef outSelf)
Returns the type instance that the current tag call was a member of. This is used in member tags of custom types to return the target of the current call.

Parameters:
outSelf - on return, the resulting type instance

typeGetName

public int typeGetName(LassoTypeRef target,
                       LassoValue outName)
Returns the name of the target type.

Parameters:
target - the type instance to get the name of
outName - the resulting name which will be stored in the name portion of the LassoValue

typeIsA

public int typeIsA(LassoTypeRef target,
                   java.lang.String typeName)
Tests to see if a type is an instance of another type. Test by type code.

Parameters:
target - the target instance to test
typeName - the type code to test for

typeIsA

public int typeIsA(LassoTypeRef target,
                   LassoTypeRef type)
Tests to see if a type is an instance of another type. Test based on another type instance.

Parameters:
target - the target instance to test
type - the type name to test for
Since:
v8.0

returnTagValue

public int returnTagValue(LassoTypeRef value)
Specifies the return value of the current LJAPI tag call. Any type can be returned. A tag can only have one return value. Setting another return value will overwrite the previous.

Parameters:
value - the value to return

returnTagValue

public int returnTagValue(boolean value)
Return a boolean value from the current LJAPI tag call.

Parameters:
value - the boolean value to return
Since:
v8.0

returnTagValue

public int returnTagValue(long value)
Return an integer value from the current LJAPI tag call.

Parameters:
value - the integer value to return
Since:
v8.0

returnTagValue

public int returnTagValue(java.lang.String value)
Return a string value from the current LJAPI tag call.

Parameters:
value - the string data to be returned
Since:
v8.0

returnTagValue

public int returnTagValue(double value)
Return a decimal value from the current LJAPI tag call.

Parameters:
value - the double value to return

returnTagValue

public int returnTagValue(byte[] value)
Return binary data from the current LJAPI tag call. When using this, the result of the LJAPI call will be a bytes type. This can be called as many times as needed and new data will be appended to any previous data.


getTagReturnValue

public int getTagReturnValue(LassoTypeRef outValue)
Provides direct access to the LJAPI tag's return value. In many cases, directly manipulating this value can yield better performance than returnTagValue. The resulting type instance will start out as type null.

Parameters:
outValue - the resulting return value type instance
Since:
v8.0

typeRunTag

public int typeRunTag(LassoTypeRef tagType,
                      java.lang.String named,
                      LassoTypeRef[] params,
                      LassoTypeRef returnValue,
                      LassoTypeRef optionalTarget)
Execute a given tag. The tag can be run given a specific name and an array of parameters. The tag's return value can be accessed. If the tag is a member tag, the instance of which it is a member can be passed using the final parameter. The params, returnValue and optionalTarget parameters may all be null.

Parameters:
tagType - the tag instance to be executed
named - the name for the tag
params - the array of parameters for the tag. May be null
returnValue - on return, contains the resulting value.
optionalTarget - the target instance for a member tag call. May be null if the tag is not a member tag

typeRunTag

public int typeRunTag(LassoTypeRef tagType,
                      java.lang.String named,
                      LassoTypeRef param,
                      LassoTypeRef returnValue,
                      LassoTypeRef optionalTarget)
Used to execute a given tag. Convenience function. Same as typeRunTag, except that is accepts a single LassoTypeRef parameter instead of an array, returning the resulting type instance.

Parameters:
tagType - must be a valid instance of an executable tag of type LASSO_TAG
named - optionally sets the tag name at the time of execution. Could be null
param - Optional. Single tag parameter. Could be null.
returnValue - the result of this tag execution
optionalTarget - would be used in a member tag call. Otherwise it should be null

findTag

public int findTag(java.lang.String named,
                   LassoTypeRef outTag,
                   boolean disableOnDemand)
Searches for a tag. The search method is the same as would be used to find a tag in a script. Returns ERR_NOERR if the tag is found. The final parameter can be used to disable searching for the tag in any on-demand libraries.

Parameters:
named - the tag name to search for
outTag - the resulting tag, if found
disableOnDemand - used to disable the searching of on-demand libraries
Since:
v8.0

getVariable2

public int getVariable2(java.lang.String named,
                        LassoTypeRef outValue)
Provides access to a defined variable.

Parameters:
named - the name of the variable to access
outValue - the resulting variable value

setVariable2

public int setVariable2(java.lang.String named,
                        LassoTypeRef value)
Sets the specified variable's value. The variable does not have to already exist.

Parameters:
named - the name of the variable to set
value - the value to set

getTagParam2

public int getTagParam2(int paramIndex,
                        LassoTypeRef outType)
Retrieves a parameter that was passed to the LJAPI tag call. The parameter index is zero-based.

Parameters:
paramIndex - the zero based index of the desired parameter
outType - the resulting parameter value

findTagParam2

public int findTagParam2(java.lang.String paramName,
                         LassoTypeRef outType)
Retrieves a parameter that was passed to the LJAPI tag call. The parameter must have been specified by keyword.

Parameters:
paramName - the keyword of the desired parameter
outType - the resulting parameter value

childrenRun

public int childrenRun(LassoTypeRef outResult)
Execute the contents of a container tag. Tags become containers by registering with the flag_typeContainerTag flag. The resulting data will be of type string.

Parameters:
outResult - the resulting data

tagGetReturnType

public int tagGetReturnType(LassoTypeRef inTagType,
                            LassoValue outResult)
Provides access to tag parameters as specified by the -returntype keyword

Since:
v7.0

tagSetReturnType

public int tagSetReturnType(LassoTypeRef inTagType,
                            java.lang.String typeName)
Provides access to tag parameters as specified by the -returntype keywords

Since:
v7.0

tagGetExpectedParamCount

public int tagGetExpectedParamCount(LassoTypeRef inTagType,
                                    IntValue outCount)
Provides access to tag parameters as specified by the -required/-optional keywords.

Since:
v7.0

tagGetExpectedParam

public int tagGetExpectedParam(LassoTypeRef inTagType,
                               int index,
                               LassoValue outResult,
                               IntValue outRequired)
Provides access to indexed tag parameter

Since:
v7.0

typeSetCustomJavaObject

public int typeSetCustomJavaObject(LassoTypeRef type,
                                   java.lang.Object object)
typeSetCustomJavaObject permits attachment of Java objects to custom types. Java object is retained until the typeFreeCustomJavaObject is called, or the type is destroyed.

One of the most common uses of this feature is to attach the LassoTagModule instance to a custom LDML type created by that module. In this case, Lasso will attempt to reuse the Java object and invoke member methods on the attached module instead of creating new module instance for each corresponding call. As an added bonus, module methods will always be executed in the current "context". So, instead of:


 LassoTypeRef type = new LassoTypeRef();
 lasso.getTagSelf(type);
 Object obj = lasso.typeGetCustomJavaObject(type);
 obj.counter++;
one could simply write:

this.counter++;
Note: if the attached object class implements Cloneable interface, an attempt will be made to invoke its clone method during assignment operation if OnAssign member is not implemented by the module.


typeGetCustomJavaObject

public java.lang.Object typeGetCustomJavaObject(LassoTypeRef type)
Retrieves the Java object previously attached to a custom type. Returns null if no object has been associated with this custom type instance.


typeFreeCustomJavaObject

public int typeFreeCustomJavaObject(LassoTypeRef type)
Releases the Java object previously attached to a custom type. Must be called to free the Java object that is no longer needed, or to detach a Java object before attaching a new one.


typeAssign

public int typeAssign(LassoTypeRef left_hand_side,
                      LassoTypeRef right_hand_side)
typeAssign performs an assignment of one type to another. The result will be the same as if the following had been executed in LDML:

#left_hand_side = #right_hand_side


typeDetach

public int typeDetach(LassoTypeRef toDetach)
Prevents the type from being destroyed once the LJAPI call returns. Types that have been detached must eventually be destroyed using typeFree or a memory leak will occur.


runRequest

public static int runRequest(java.lang.String className,
                             java.lang.String methodName,
                             int tagAction,
                             int unused)
Creates and runs a new LJAPI call on the given Java module method. If there is already an active request on the current thread, the methodName will be run within that threads context. If there is no currently active request on the current thread, a new request will be created and run based off the global context.

Parameters:
className - name of the java class implementing the method
methodName - java method. Must have the same signature as TAG_METHOD_PROTOTYPE
tagAction - this parameter will be passed to the methodName and can be used to signal or pass information to the function
unused - reserved for future use

getSiteID

public int getSiteID()

getSiteName

public java.lang.String getSiteName()

log

public static int log(int msgLevel,
                      java.lang.String message)
Log a message. The message goes to the prefered destination for the message level. Messages are limited to 2048 bytes in length. Messages sent to the console are limited to 512 bytes in length. Messages sent to the database are limited a little less than 2048 bytes since the total length of the sql statement used to insert the message is limited to 2048 bytes.

Parameters:
msgLevel - one of the LOG_LEVEL constants
message - message text