com.blueworld.lassopro
Class LassoCall

java.lang.Object
  |
  +--com.blueworld.lassopro.LassoCall

public final class LassoCall
extends java.lang.Object

The core of the Lasso Java API v7.0. All the interaction between an LJAPI module and Lasso Professional is achieved by 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 ERR_NOERR signifying that no errors had occured during this method execution, or an integer error code.

See Also:
LassoDSModule, LassoTagModule, LassoErrors

Method Summary
 int acquireSem(java.lang.String named)
          Acquires previously created semaphore
 int addColumnInfo(java.lang.String name, int nullOK, int type, int protection)
          Adds information about a particular column.
 int addDataSourceResult(java.lang.String data)
          Adds a result value.
 int addResultHeader(java.lang.String header)
          Simply 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)
          This method gets an array element from a previously created array instance.
 int arrayGetSize(LassoTypeRef array, IntValue outLen)
          This method gets an array element from a previously created array instance.
 int arrayRemoveElement(LassoTypeRef array, int index)
          This method removes an element from a previously created array instance.
 int arraySetElement(LassoTypeRef array, int index, LassoTypeRef element)
          This method sets an array element in a previously created array instance.
 int childrenRun(LassoTypeRef outResult)
          Same purpose and usage as the children_run LDML tag.
 int createSem(java.lang.String named)
          Semaphores are a means by which access to shared resources can be control amongst several threads of execution.
 int destroySem(java.lang.String named)
          Destroys existing semaphore
 int findInputColumn(java.lang.String name, LassoValue outColumn)
          Gets an individual input column by name.
 int findTagParam(java.lang.String paramName, LassoValue outParam)
          Finds and fetches a tag param by name.
 int findTagParam2(java.lang.String paramName, LassoTypeRef outType)
          This allows tag parameters to be acquired while preserving their types.
 int formatBuffer(java.lang.String buffer, LassoValue outResult)
          Formats the supplied buffer and put the resulting data in the data member of the LassoValue.
 java.lang.String fullyQualifyPath(java.lang.String relativePath)
          Converts a relative path into a from-the-server-root path.
 int getCookieValue(java.lang.String named, LassoValue outValue)
          Finds a cookie value
 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 getDataSourceModuleName(LassoValue outName)
          Returns the name the datasource module originally registered under.
 int getDataSourceName(LassoValue outName, IntValue outUseHostDefault, LassoValue outUsernamePassword)
          Gets the currently specified database name.
 java.lang.Object getDSConnection()
          Returns the current datasource connection, 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 getLassoParam(int key, LassoValue outParam)
          Fetches an internal 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 an internal 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 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, i.
 int getTagParam(int paramIndex, LassoValue outParam)
          Fetches the indicated parameter that was sent to the tag.
 int getTagParam2(int paramIndex, LassoTypeRef outType)
          This allows tag parameters to be acquired while preserving their types.
 int getTagParamCount(IntValue outCount)
          Fetches the number of parameters that were passed to the tag
 int getTagSelf(LassoTypeRef outSelf)
          Used in LJAPI tags that are members of a custom type.
 int getVariable(java.lang.String named, int index, LassoValue outValue)
          Retrieves the specified variable value
 int getVariable2(java.lang.String named, LassoTypeRef outValue)
          This allows variables to be acquired while preserving their types.
 int getVariableCount(java.lang.String named, IntValue outCount)
          Retrieves the number of variables with the specified name
 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"
 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()
          Returns ERR_NOERR is the current user has administrator priveleges.
 int isLassoLite()
          Returns ERR_NOERR if Lasso edition is LassoLite
 boolean isValid()
          Returns true if a native object instance this LassoCall refers to has not been destroyed yet.
static int log(int msgLevel, java.lang.String message)
          Log a message.
 int mapFindElement(LassoTypeRef map, LassoTypeRef key, LassoTypeRef outElement)
          This method finds an element in a previously created map instance.
 int mapGetElement(LassoTypeRef map, int index, LassoTypeRef outPair)
          This method gets an element from a previously created map instance using the element index.
 int mapGetSize(LassoTypeRef map, IntValue outLen)
          This function gets the size of a previously created map instance.
 int mapRemoveElement(LassoTypeRef map, LassoTypeRef key)
          This method removes an element from a previously created map instance.
 int mapSetElement(LassoTypeRef map, LassoTypeRef key, LassoTypeRef value)
          This function sets an element in a previously created map instance.
 int operationAllowed(int secureOperation, java.lang.String internalPathname)
          Returns ERR_NOERR is the given operation is permitted by Lasso security.
 int outputTagBytes(byte[] data)
          Alias for outputTagData
 int outputTagData(byte[] data)
          Output some data onto the page.
 int outputTagData(java.lang.String data)
          Output some data onto the page.
 int pairGetFirst(LassoTypeRef pair, LassoTypeRef outValue)
          This method gets the first element from a previously created pair instance.
 int pairGetSecond(LassoTypeRef pair, LassoTypeRef outValue)
          This method gets the second element from a previously created pair instance.
 int pairSetFirst(LassoTypeRef pair, LassoTypeRef first)
          This method sets the first element in a previously created pair instance.
 int pairSetSecond(LassoTypeRef pair, LassoTypeRef second)
          This method sets the second element in a previously created pair instance.
static int registerConstant(java.lang.String name, LassoTypeRef val)
          Define named constant
 int releaseSem(java.lang.String named)
          Releases previously aquired semaphore
 int removeVariable(java.lang.String named, int index)
          Removes the specified variable
 java.lang.String resolvePath(java.lang.String fromRootPath)
          Converts a from-the-root path into a full internal path
 int returnTagValue(LassoTypeRef value)
          This allows LJAPI tags to return sophisticated data types.
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 setDSConnection(java.lang.Object inConnection)
          Called to set the current connection for the datasource May recurse to deliver the ACTION_CLOSE message if there is already a valid db connection.
 int setDSDefaultCharset(java.lang.String inCharsetName)
          Called to set the default charset to be used for string encoding, such as "ISO-8859-1", etc.
 int setNumRowsFound(int num)
          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 header.
 int setResultMessage(java.lang.String msg)
          Sets the result message that can be displayed
 int setRowID(int id)
          Sets the currently specified record id (FileMaker-specific).
 int setVariable(java.lang.String named, java.lang.String value, int index)
          Sets the specified variable
 int setVariable2(java.lang.String named, LassoTypeRef value)
          This allows variables to be set while preserving their types.
 int storeGetData(java.lang.String key, LassoValue outValue)
          Fetches data that has been stored.
 int storeHasData(java.lang.String key, IntValue outLength)
          Returns ERR_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)
          Pass "anonymous" with no password to switch to lowest priveleges
 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 ERR_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)
          This is used to add new members to type instances.
 int typeAlloc(java.lang.String typeName, LassoTypeRef[] params, LassoTypeRef outType)
          typeAlloc will attempt to allocate a new type instance.
 int typeAllocArray(LassoTypeRef outArray, LassoTypeRef[] inElements)
          Allocates new Lasso type tag of type array.
 int typeAllocBoolean(LassoTypeRef outBool, boolean value)
          This function allows new instances of boolean data types to be allocated.
 int typeAllocCustom(LassoTypeRef outCustom, java.lang.String typeName)
          This function is used within module methods that were registered as being a type initializer (FLAG_INITIALIZER).
 int typeAllocDecimal(LassoTypeRef outDecimal, double value)
          Allocates new Lasso type tag of type decimal.
 int typeAllocDecimal(LassoTypeRef outDecimal, double value, int precision)
          Allocates new Lasso type tag of type decimal with the given precision.
 int typeAllocFromProto(LassoTypeRef inProto, LassoTypeRef outType)
          Allocate a new type based on the given type.
 int typeAllocInteger(LassoTypeRef outInteger, long value)
          Allocates new Lasso type tag of type integer.
 int typeAllocMap(LassoTypeRef outMap, LassoTypeRef[] inElements)
          This method allows new instances of map data types to be allocated.
 int typeAllocMap(LassoTypeRef outMap, LassoTypeRef[] inKeys, LassoTypeRef[] inValues)
          Same as above, only in this case the map keys and values are passed in a separate parameters.
 int typeAllocNull(LassoTypeRef outNull)
          Allocates new Lasso type tag of type null.
 int typeAllocOneOff(java.lang.String inName, java.lang.String inParentTypeName, LassoTypeRef outType)
          This method allocates a new type with the given name.
 int typeAllocPair(LassoTypeRef outPair, LassoTypeRef inFirst, LassoTypeRef inSecond)
          Allocates new Lasso type tag of type pair.
 int typeAllocReference(LassoTypeRef outRef, LassoTypeRef referenced)
          Allocates new Lasso type tag of type reference.
 int typeAllocString(LassoTypeRef outString, byte[] value)
          Allocates new Lasso type tag of type string.
 int typeAllocString(LassoTypeRef outString, java.lang.String value)
          Allocates new Lasso type tag of type string.
 int typeAllocStringConv(LassoTypeRef outString, java.lang.String value, java.lang.String conv)
          Allocates new Lasso type tag of type string from a Java string using specified encoding.
 int typeAllocTag(LassoTypeRef outTag, java.lang.String className, java.lang.String methodName)
          Allocates new Lasso type tag of type tag.
 int typeAppendString(LassoTypeRef type, java.lang.String value)
          This function appends a string to an existing string instance.
 int typeAssign(LassoTypeRef left_hand_side, LassoTypeRef right_hand_side)
          typeAssign performs an assignment of one type to another.
 int typeDetach(LassoTypeRef toDetach)
          Prevents the type from being destroyed once the LJAPI call returns.
 int typeFree(LassoTypeRef inType)
          typeFree will attempt to free a type created through typeAlloc (or any other method).
 int typeFreeCustomJavaObject(LassoTypeRef type)
          Releases the Java object previously attached to a custom type.
 int typeGetBoolean(LassoTypeRef type, IntValue outValue)
          This method gets the data from a previously created boolean instance.
 byte[] typeGetBytes(LassoTypeRef type)
          This method returns the data of a type instance as an array of bytes.
 java.lang.Object typeGetCustomJavaObject(LassoTypeRef type)
          Retrieves the Java object previously attached to a custom type.
 int typeGetDecimal(LassoTypeRef type, FloatValue outValue)
          This method gets the data from a previously created decimal instance.
 int typeGetInteger(LassoTypeRef type, IntValue outValue)
          This method gets the data from a previously created integer instance.
 int typeGetMember(LassoTypeRef fromType, java.lang.String named, LassoTypeRef outMember)
          This function is used to retrieve a member from a type instance.
 int typeGetName(LassoTypeRef target, LassoValue outName)
          Retrieves the name of the target type.
 int typeGetProperties(LassoTypeRef targetType, LassoTypeRef outPair)
          This method has two uses.
 int typeGetString(LassoTypeRef type, LassoValue outValue)
          This method gets the data from a previously created string instance.
 int typeInheritFrom(LassoTypeRef inChild, LassoTypeRef inNewParent)
          Change the inheritence structure of a type.
 int typeIsA(LassoTypeRef target, java.lang.String typeName)
          Returns ERR_NOERR is the target is of the specified type.
 int typeRunTag(LassoTypeRef tagType, java.lang.String named, LassoTypeRef[] params, LassoTypeRef returnValue, LassoTypeRef optionalTarget)
          Used to execute a given tag.
 int typeRunTag(LassoTypeRef tagType, java.lang.String named, LassoTypeRef param, LassoTypeRef returnValue, LassoTypeRef optionalTarget)
          Convenience function.
 int typeSetBoolean(LassoTypeRef type, boolean value)
          This method sets the value of a previously created boolean type instance.
 int typeSetBytes(LassoTypeRef type, byte[] value)
          This method sets the data of a type instance.
 int typeSetCustomJavaObject(LassoTypeRef type, java.lang.Object object)
          typeSetCustomJavaObject permits attachment of Java objects to custom types.
 int typeSetDecimal(LassoTypeRef type, double value)
          This method sets the value of a previously created decimal type instance.
 int typeSetDecimal(LassoTypeRef type, double value, int precision)
          This method sets the value of a previously created decimal type instance using specified precision.
 int typeSetInteger(LassoTypeRef type, long value)
          This method sets the value of a previously created integer type instance.
 int typeSetString(LassoTypeRef type, java.lang.String value)
          This method sets the value of a previously created string type instance.
 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
 

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.


registerConstant

public static int registerConstant(java.lang.String name,
                                   LassoTypeRef val)
Define named constant


getRequestParam

public int getRequestParam(int key,
                           LassoValue outParam)
Fetches an internal variable

Parameters:
key - one of the RequestParams constants
outParam - resulting value
See Also:
RequestParams

getLassoParam

public int getLassoParam(int key,
                         LassoValue outParam)
Fetches an internal variable

Parameters:
key - one of the LassoParams constants
outParam - resulting value
See Also:
LassoParams

isLassoLite

public int isLassoLite()
Returns ERR_NOERR if Lasso edition is LassoLite


setResultCode

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


setResultMessage

public int setResultMessage(java.lang.String msg)
Sets the result message that can be displayed


getTagName

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


getTagParamCount

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


getTagParam

public int getTagParam(int paramIndex,
                       LassoValue outParam)
Fetches the indicated parameter that was sent to the tag. Param indexes start at zero


tagParamIsDefined

public int tagParamIsDefined(java.lang.String paramName)
Returns ERR_NOERR if the parameter was defined, anything else means it wasn't.


findTagParam

public int findTagParam(java.lang.String paramName,
                        LassoValue outParam)
Finds and fetches a tag param by name. A return value of ERR_NOERR means the param was found


getTagEncoding

public int getTagEncoding(IntValue outMethod)
Deprecated.  

Fetches the encoding method indicated for this tag


outputTagData

public int outputTagData(java.lang.String data)
Output some data onto the page. Lasso will take care of encoding. This can be called as many times as needed


outputTagData

public int outputTagData(byte[] data)
Output some data onto the page. This is recommended method for writing binary data.


outputTagBytes

public int outputTagBytes(byte[] data)
Alias for outputTagData


getResultHeader

public int getResultHeader(LassoValue outHeader)
Allows access to the result (HTTP) header


setResultHeader

public int setResultHeader(java.lang.String header)
Sets the result header. Any data will be validated so as to be in the proper format


addResultHeader

public int addResultHeader(java.lang.String header)
Simply appends the supplied data to the header. Any data will be validated so as to be in the proper format


getVariableCount

public int getVariableCount(java.lang.String named,
                            IntValue outCount)
Retrieves the number of variables with the specified name

Parameters:
named - name of a variable
outCount - count of variables with the specified name

getVariable

public int getVariable(java.lang.String named,
                       int index,
                       LassoValue outValue)
Retrieves the specified variable value

Parameters:
named - name of a variable
index - indexes are zero-based
outValue - value of the named variable

setVariable

public int setVariable(java.lang.String named,
                       java.lang.String value,
                       int index)
Sets the specified variable


removeVariable

public int removeVariable(java.lang.String named,
                          int index)
Removes the specified variable


getCookieValue

public int getCookieValue(java.lang.String named,
                          LassoValue outValue)
Finds a cookie value


getDSConnection

public java.lang.Object getDSConnection()
Returns the current datasource connection, 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 for the datasource May recurse to deliver the ACTION_CLOSE message if there is already a valid db connection.

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

setDSDefaultCharset

public int setDSDefaultCharset(java.lang.String inCharsetName)
Called to set the default charset to be used for string encoding, such as "ISO-8859-1", etc.

Since:
v7.0

addDataSourceResult

public int addDataSourceResult(java.lang.String data)
Adds a 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.


getDataSourceName

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

Parameters:
outName - on return, contains the database name stored in the data field.
outUseHostDefault - true if user name and password returned in outUsernamePassword variable should be used by default.
outUsernamePassword - user name and password to be used for logging in to the datasource host.

getSchemaName

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

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

getTableName

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

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

getDataHost

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

Parameters:
outHost - host address and port are returned in the name and data fields
outUsernamePassword - host default username and password

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.


getSkipRows

public int getSkipRows(IntValue outRows)
The number of rows that should be skipped in the found set.


getMaxRows

public int getMaxRows(IntValue outRows)
The maximum number of rows in the found set to return.


getRowID

public int getRowID(IntValue outId)
Gets the currently specified record id (FileMaker-specific).


setRowID

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


getPrimaryKeyColumn

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


getPrimaryKeyColumn2

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


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.


getSortColumn

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


findInputColumn

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


getLogicalOp

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


getReturnColumnCount

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


getReturnColumn

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


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

addResultRow

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


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


createSem

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


destroySem

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


acquireSem

public int acquireSem(java.lang.String named)
Acquires previously created semaphore


releaseSem

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


formatBuffer

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


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

Parameters:
key - the unique identifier for the data. The data will be returned in the data field of the LassoValue object.

isAdministrator

public int isAdministrator()
Returns ERR_NOERR is the current user has administrator priveleges. This is useful for doing module administration that only the admin should be able to do.


operationAllowed

public int operationAllowed(int secureOperation,
                            java.lang.String internalPathname)
Returns ERR_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.

switchToUser

public int switchToUser(java.lang.String username,
                        java.lang.String password)
Pass "anonymous" with no password to switch to lowest priveleges

Since:
v7.0

typeAlloc

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


typeFree

public int typeFree(LassoTypeRef inType)
typeFree will attempt to free a type created through typeAlloc (or any other method). The actual native object will only be deleted if it can be found in the garbage list. If it can not be found, it is considered to be an invalid parameter and an error is returned.


typeAllocNull

public int typeAllocNull(LassoTypeRef outNull)
Allocates new Lasso type tag of type null.


typeAllocString

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


typeAllocString

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

Since:
v7.0

typeAllocStringConv

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

Since:
v7.0

typeAllocInteger

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


typeAllocDecimal

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


typeAllocDecimal

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


typeAllocPair

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


typeAllocReference

public int typeAllocReference(LassoTypeRef outRef,
                              LassoTypeRef referenced)
Allocates new Lasso type tag of type reference.


typeAllocTag

public int typeAllocTag(LassoTypeRef outTag,
                        java.lang.String className,
                        java.lang.String methodName)
Allocates new Lasso type tag of type tag.


typeAllocArray

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

Parameters:
outArray - resulting type
inElements - the elements to instantite new array type with. Can be null.

typeAllocMap

public int typeAllocMap(LassoTypeRef outMap,
                        LassoTypeRef[] inElements)
This method allows new instances of map data types to be allocated. Types allocated in this manner will be destroyed once the LJAPI call is returned. Note that count here for the map must be divisible by 2. Every 2 elements are taken to be the key and value, respectively.


typeAllocMap

public int typeAllocMap(LassoTypeRef outMap,
                        LassoTypeRef[] inKeys,
                        LassoTypeRef[] inValues)
Same as above, only in this case the map keys and values are passed in a separate parameters.


typeAllocBoolean

public int typeAllocBoolean(LassoTypeRef outBool,
                            boolean value)
This function allows new instances of boolean data types to be allocated. Types allocated in this manner will be destroyed once the LJAPI call is returned.


typeAllocCustom

public int typeAllocCustom(LassoTypeRef outCustom,
                           java.lang.String typeName)
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 __type_name__ member to the provided value. The new type does not yet have a lineage and has no members added to it besides __type_name__. New data or tag members should be added using typeAddMember. The new custom type should be the return value of the type initializer. 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.


typeAllocFromProto

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

Since:
v7.0

typeAllocOneOff

public int typeAllocOneOff(java.lang.String inName,
                           java.lang.String inParentTypeName,
                           LassoTypeRef outType)
This method allocates 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 will be called for the parent and beyond

Since:
v7.0

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 - target
inNewParent - new parent type
Since:
v7.0

typeAppendString

public int typeAppendString(LassoTypeRef type,
                            java.lang.String value)
This function appends a string to an existing string instance.

Since:
v7.0

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)
This method gets the data from a previously created string instance. When setting a value, the type is converted if required.


typeGetBytes

public byte[] typeGetBytes(LassoTypeRef type)
This method returns the data of a type instance as an array of bytes.

Since:
v7.0

typeGetInteger

public int typeGetInteger(LassoTypeRef type,
                          IntValue outValue)
This method gets the data from a previously created integer instance. When setting a value, the type is converted if required.


typeGetDecimal

public int typeGetDecimal(LassoTypeRef type,
                          FloatValue outValue)
This method gets the data from a previously created decimal instance. When setting a value, the type is converted if required.


typeGetBoolean

public int typeGetBoolean(LassoTypeRef type,
                          IntValue outValue)
This method gets the data from a previously created boolean instance. When setting a value, the type is converted if required.


typeSetString

public int typeSetString(LassoTypeRef type,
                         java.lang.String value)
This method sets the value of a previously created string type instance.


typeSetBytes

public int typeSetBytes(LassoTypeRef type,
                        byte[] value)
This method sets the data of a type instance. The type is converted if required.

Since:
v7.0

typeSetInteger

public int typeSetInteger(LassoTypeRef type,
                          long value)
This method sets the value of a previously created integer type instance.


typeSetDecimal

public int typeSetDecimal(LassoTypeRef type,
                          double value)
This method sets the value of a previously created decimal type instance.


typeSetDecimal

public int typeSetDecimal(LassoTypeRef type,
                          double value,
                          int precision)
This method sets the value of a previously created decimal type instance using specified precision.


typeSetBoolean

public int typeSetBoolean(LassoTypeRef type,
                          boolean value)
This method sets the value of a previously created boolean type instance.


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.


typeGetName

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


typeIsA

public int typeIsA(LassoTypeRef target,
                   java.lang.String typeName)
Returns ERR_NOERR is the target is of the specified type.


typeRunTag

public int typeRunTag(LassoTypeRef tagType,
                      java.lang.String named,
                      LassoTypeRef[] params,
                      LassoTypeRef returnValue,
                      LassoTypeRef optionalTarget)
Used to execute a given tag. The tag can be run given a specific name and parameters, and the return value of the tag 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 - 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
params - optional tag parameters. Could be null.
returnValue - the result of this tag execution
optionalTarget - to be used in a member tag calls. Otherwise it should be null

typeRunTag

public int typeRunTag(LassoTypeRef tagType,
                      java.lang.String named,
                      LassoTypeRef param,
                      LassoTypeRef returnValue,
                      LassoTypeRef optionalTarget)
Convenience function. Same as above, only accepts a single LassoTypeRef parameter instead of an array

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

getTagSelf

public int getTagSelf(LassoTypeRef outSelf)
Used in LJAPI tags that are members of a custom type. It returns the type instance that the current call was a member of. If the current call is not a member, an error is returned and outSelf.isNull() will evaluate to true.


returnTagValue

public int returnTagValue(LassoTypeRef value)
This allows LJAPI tags to return sophisticated data types.


getVariable2

public int getVariable2(java.lang.String named,
                        LassoTypeRef outValue)
This allows variables to be acquired while preserving their types.


setVariable2

public int setVariable2(java.lang.String named,
                        LassoTypeRef value)
This allows variables to be set while preserving their types.


getTagParam2

public int getTagParam2(int paramIndex,
                        LassoTypeRef outType)
This allows tag parameters to be acquired while preserving their types.


findTagParam2

public int findTagParam2(java.lang.String paramName,
                         LassoTypeRef outType)
This allows tag parameters to be acquired while preserving their types.


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

childrenRun

public int childrenRun(LassoTypeRef outResult)
Same purpose and usage as the children_run LDML tag.


typeGetMember

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


typeAddMember

public int typeAddMember(LassoTypeRef toType,
                         java.lang.String named,
                         LassoTypeRef member)
This is used to add new members to type instances. The member can be any sort of type including tags or other custom types.


arrayGetSize

public int arrayGetSize(LassoTypeRef array,
                        IntValue outLen)
This method gets an array element from a previously created array instance.


arrayGetElement

public int arrayGetElement(LassoTypeRef array,
                           int index,
                           LassoTypeRef outElement)
This method gets an array element from a previously created array instance.


arraySetElement

public int arraySetElement(LassoTypeRef array,
                           int index,
                           LassoTypeRef element)
This method sets an array element in a previously created array instance.


arrayRemoveElement

public int arrayRemoveElement(LassoTypeRef array,
                              int index)
This method removes an element from a previously created array instance.


mapGetSize

public int mapGetSize(LassoTypeRef map,
                      IntValue outLen)
This function gets the size of a previously created map instance.


mapFindElement

public int mapFindElement(LassoTypeRef map,
                          LassoTypeRef key,
                          LassoTypeRef outElement)
This method finds an element in a previously created map instance.


mapGetElement

public int mapGetElement(LassoTypeRef map,
                         int index,
                         LassoTypeRef outPair)
This method gets an element from a previously created map instance using the element index.


mapSetElement

public int mapSetElement(LassoTypeRef map,
                         LassoTypeRef key,
                         LassoTypeRef value)
This function sets an element in a previously created 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.


mapRemoveElement

public int mapRemoveElement(LassoTypeRef map,
                            LassoTypeRef key)
This method removes an element from a previously created map instance.


pairGetFirst

public int pairGetFirst(LassoTypeRef pair,
                        LassoTypeRef outValue)
This method gets the first element from a previously created pair instance.


pairGetSecond

public int pairGetSecond(LassoTypeRef pair,
                         LassoTypeRef outValue)
This method gets the second element from a previously created pair instance.


pairSetFirst

public int pairSetFirst(LassoTypeRef pair,
                        LassoTypeRef first)
This method sets the first element in a previously created pair instance.


pairSetSecond

public int pairSetSecond(LassoTypeRef pair,
                         LassoTypeRef second)
This method sets the second element in a previously created pair instance.


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, for example, 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, when OnAssign member itslef 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

getDataSourceModuleName

public int getDataSourceModuleName(LassoValue outName)
Returns the name the datasource module originally registered under.


getPlatformSpecificPath

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


getInternalPath

public static java.lang.String getInternalPath(java.lang.String platformPath)
Converts a platform-specific pathname into an 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.


resolvePath

public java.lang.String resolvePath(java.lang.String fromRootPath)
Converts a from-the-root path into a full internal path


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