Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 8 Using TIBCO Object Service Broker SDK (Java) : Session Object Methods

Session Object Methods
Session
The class constructor.

 
public Session()
 
or
 
public Session(String sessParam,
String codepage) throws SessionException

 
Parameters:
 
The SDK (C/C++)/SDK (Java) code page to be used for this session. The valid values for this field are the code page names shown in TIBCO Object Service Broker National Language Support.
 
WIN‑1252 is recommended for use in clients that do not depend on TIBCO Object Service Broker code pages; it supports all TIBCO Object Service Broker code pages.
ISO8859‑1 works only with code pages that do not support the euro sign.
ISO8859‑15 works only with code pages that support the euro sign.
The following translations occur:
Value of code page
A euro code page
x'9F' (the universal currency symbol) in the non-euro code page «-» 1 x'20' in the euro code page.
A non-euro code page
x'9F' (the universal currency symbol) in the non-euro code page «-» x'20' in the euro code page.
The Windows code page
x'80' (the euro symbol) in the Windows code page «-» x'20' in the non-euro code page.
x'A4' (the universal currency symbol) in the Windows code page «-» code point x'9F' in the non-euro code page.
x'A4' (the universal currency symbol) in the Windows code page «-» x'20' in the euro code page.
x'80' (the euro symbol) in the Windows code page «-» x'9F' in the non-euro code page.

1
In this table, the “«-»” symbol means “translates to, in both directions”.

For the second form of this method, these parameters are used to start a session.
Return Value:
None.
Throws:
The second form of this method throws SessionException with rc = SessionException.STARTSS_FAILED (4) if a session cannot be started.
Comments
An application program can use the first form of the Session method, which constructs an object representing an inactive session, to create an object in preparation for starting a session later. The second form also invokes the start method to start a TIBCO Object Service Broker session.
call
Calls a rule.

 
public String call(String func,
byte[] dataIn,
byte[] dataOut) throws SessionException
 
or
 
public int call(String func,
byte[] dataIn,
byte[] dataOut,
byte[] ruleRetValue,
int ruleRetValueStart,
int   ruleRetValueMaxLen) throws SessionException

 
Parameters:
 
The rules functional expression in a textual form: RULENAME(ARG1,ARG2,...,ARGN). The expression length must be less than or equal to 514 (Session.MAXRULEEXPRLEN constant).
The input commarea: a byte array, formatted in accordance with the commarea format specification (refer to Comments).
The output commarea: a byte array, formatted in accordance with the commarea format specification.
A byte array meant to hold the rules return value. If ruleRetValue is null, no return value is stored.
The index where the SDK (Java) should start storing the return value in the ruleRetValue array.
The maximum number of bytes available for the rules return value in the ruleRetValue array. If ruleRetValueMaxLen is zero, no return value is stored.
Return Value:
The first form of the method returns the rules return value as a String object.
The second form returns the actual length of the rules return value as returned by the rule. Compare this length to the value passed as ruleRetValueMaxLen to determine if truncation took place.
The rules return value is the value that the called rule returns in a RETURN statement.
Exceptions:
SessionException with rc = SessionException.CALLRULE_FAILED (11) is thrown in case of failure.
Comments
If the func parameter value is NULL, both forms of the call method throw an exception with an error reason code of SessionException.NORULENAME (96). Also, if the func parameter value is longer than 514 (Session.MAXRULEEXPRLEN), both forms throw an exception with an error reason code of Session.RULEEXPRTOOLONG (3090).
If the session already abends or is already stopped, or no transaction is started within the session, the call method throws an exception with an error reason code of SessionException.CALLOUTOFSEQ (36).
The two forms of the call method differ in how they handle the rules return value:
The second form stores the value in the input ruleRetValue byte array. The value is stored in the SDK (C/C++)/SDK (Java) code page (refer to start), starting from the ruleRetValueStart index, for up to ruleRetValueMaxLen bytes. This form returns the full length of the rules return value. Therefore, if this full-length value is greater than the value passed in ruleRetValueMaxLen, truncation occurred.
Passing null as ruleRetValue or zero as ruleRetValueMaxLen results in no rules return value stored. This is not an error.
If the rule does not return a value, the first form of the call method returns an empty string and the second form stores no bytes in ruleRetValue.
Both forms of the call method use the dataIn and dataOut commareas for binary data exchange between the application and the rule. The SDK (Java) commarea is a byte array formatted as follows:
The total number of bytes in an SDK (Java) commarea is the number of bytes indicated in the header, plus the size of the header. The size of the commarea byte array does not matter as long as it is big enough. If the array is too small, both forms of the call method fail with either a SessionException.INCOMMLENERR (40) or a SessionException.OUTCOMMLENERR (41) error reason code, depending on where the commarea error is detected.
The TIBCO Object Service Broker Execution Environment creates a copy of dataIn and makes the address to the area available to the rule through the APIINHANDLE field of the @SESSION(0) table. For dataOut, the Execution Environment allocates memory for the whole area and copies the area header. The address to dataOut is made available through the APIOUTHANDLE field of the @SESSION(0) table.
Access to dataIn and dataOut using MAP tables is always granted by the system and MAP tables can be used without @MAP registration of the dataIn and dataOut addresses. dataIn is accessible for reading and dataOut for reading and writing. For more information about MAP tables, refer to TIBCO Service Gateway for Files Installing and Operating.
When a rule completes successfully, the contents of the dataOut are transferred back from the Execution Environment to the application memory. Consider reducing the number of bytes your rule transmits to the application. You do this by properly reformatting the dataOut header. The Execution Environment, before transmitting data back, reevaluates the dataOut header to determine the correct number of bytes to send back to the application. Do not use this method to increase the total size of the area. If the contents of the header indicate that the total area size is larger than the original (at the beginning of the rules call), the call fails with a SessionException.DATAOUTCORRUPT (49409) error reason code.
In its first form, the call method must create a temporary copy of the return value to perform the code page translation. Therefore this form is not the best option for applications dealing with long return values.
In its second form, the call method does not convert the rules return value to Unicode. It leaves it up to the application to store and convert the value in the most optimal application-specific manner. No temporary copies of any kind are created during the call in this form.
See Also
TIBCO Object Service Broker Programming in Rules about the rules language and writing rules.
TIBCO Object Service Broker Shareable Tools and TIBCO Object Service Broker Managing Data about the @SESSION(0) table and the MAP table.
endMessage
Returns the end message from the last rule called within the session.

 
public String endMessage()

 
Parameters:
None.
Return Value:
The end message from the last rules call, via a call method, or an error message if the rule failed. If neither an end message nor an error message is available from the rule, returns null. The maximum length of the end message is 148 (Session.MAXENDMSGLEN constant).
Exceptions:
None.
Comments
endMessage returns a String object, not a null reference, in these cases:
If the last rules call succeeded, endMessage returns the message generated by the rule via an ENDMSG call, or an empty string if the rule did not generate a message.
If the last call failed with a SessionException.RULEFAILED (3091) error reason code, endMessage returns a rules error message.
In all other cases, endMessage returns null. The java.lang.Throwable.getMessage method returns a message that is formed according to the above. If the rules call throws an exception with a SessionException.RULEFAILED (3091) error reason code, the message text contains the rules error message instead of a reason code description.
See Also
TIBCO Object Service Broker Shareable Tools about ENDMSG.
execTran
Equivalent to executing a sequence of startTrans, call, and stopTrans methods.
The changes are committed if the rules call succeeds and rolled back if it throws an exception.
The method supplies the return value from the rule in one of two ways:
In its second form, execTran stores the value, encoded using the SDK (C/C++) /SDK (Java) code page, in a region of a caller-supplied byte array.

 
public String execTran(String transParams,
String func,
byte[] dataIn,
byte[] dataOut) throws SessionException
or
 
public int execTran(String transParams,
String func,
byte[] dataIn,
byte[] dataOut,
byte[] ruleRetValue,
int ruleRetValueStart,
int ruleRetValueMaxLen) throws SessionException

 
Parameter:
 
The input commarea: a byte array, formatted in accordance to the commarea format specification (refer to call).
The output commarea: a byte array, formatted in accordance to the commarea format specification.
Return Value:
The first form of the method returns the rules return value as a String object.
The second form returns the actual length of the rules return value as returned by the rule. Compare this length to the value passed as ruleRetValueMaxLen to determine if truncation took place.
The rules return value is the value that the called rule returns in a RETURN statement.
Exceptions
SessionException is thrown if errors are encountered.
The value of rc is SessionException.STARTTR_FAILED (10), SessionException.CALLRULE_FAILED (11), or SessionException.STOPTR_FAILED (12), depending on the stage where the first error occurred.
Comments
This is a function that operates in several phases:
The only phase able to interrupt the sequence is the startTrans phase. When that phase is successful, the failure of the rules call stores the error information to throw an exception only after the stopTrans method completes. In this case, errors during the stopTrans phase are not reported.
isActive
Returns the activity status of the session.

 
public boolean isActive()

 
Parameters:
None.
Return Value:
True if the session is active; otherwise, false.
Exceptions:
None.
Comments
It is possible for a TIBCO Object Service Broker session to become inactive any time after starting (due to network problems, Execution Environment abnormal terminations, and so on). When that happens, the start, stop, startTrans, stopTrans, shutdown, and execTran method calls on this session object fail with an appropriate error reason code. In addition, the session object becomes inactive, so that subsequent calls to these methods fail with a SessionException.CALLOUTOFSEQ (36) error reason code.
Use an isActive method call to determine whether the session is still active. If the session is stopped by a stop method call, by a reset method call, or by a shutdown method call, or if it abends, isActive returns false.
reset
Drops a connection to a session.

 
public void reset

 
Parameters:
None.
Return Value:
None.
Throws:
None.
Comments
reset forcefully closes the session by dropping the session connection as opposed to an orderly shutdown by stop. The session does not have to be active for the call to succeed. When a connection is dropped, the Execution Environment generates an error message, and closes the session. All uncommitted data changes are lost. This method bring the session to an inactive state so that subsequent calls to the start, stop, startTrans, stopTrans, shutdown, and execTran methods fail with a SessionException.CALLOUTOFSEQ (36) error reason code. Subsequent calls to isActive return false.
shutdown
Stops all transactions (committing or rolling back the changes), and stops the session regardless of the errors encountered.

 
public void shutdown(boolean commit) throws SessionException

 
Parameters:
 
Return Value:
None.
Exceptions
SessionException is thrown if errors are encountered during the shutdown sequence.
The value of rc is either SessionException.STOPTR_FAILED (12) or SessionException.STOPSS_FAILED (9), depending on the stage where the first error occurred.
Comments
This method is a sequence of stopTrans method calls and a stop method call. Even if an error occurs, the sequence continues to the end. Information on the first (or only) error is stored and an exception is thrown after the sequence completes, and all the transactions and the session are stopped.
start
Starts an SDK (Java) session.

 
public void start(String sessParam,
String codepage) throws SessionException

 
Parameters:
 
The session parameter string. This string must contain CLIHOST and CLIPORT to specify an osMon (Windows or Solaris) or an Execution Environment (z/OS) location. Can contain CLIENDIAN.
The SDK (C/C++)/SDK (Java) code page to be used for this session. If it is null or empty, the method throws SessionException with an error reason code of SessionException.UNDEFCODEPAGE (161). For valid values, refer to Session.
Use the session parameters string (sessParam) to define various session behavior aspects. There are a number of parameters that are specific for the SDK (Java) (and SDK (C/C++)). These are (names are case insensitive):
 
TCP/IP host name of the TIBCO Object Service Broker monitor process (Windows or Solaris) or the Execution Environment (z/OS).
TCP/IP port number of the TIBCO Object Service Broker monitor process (Windows or Solaris) or the Execution Environment (z/OS).
Session endian type. This parameter affects the external representation of MAP table fields with internal syntax B and “*” external syntax. Valid entries are: BIG and LITTLE (case insensitive).
CLIHOST and CLIPORT identify the TIBCO Object Service Broker monitor process (Windows or Solaris) or the Execution Environment (z/OS) on the network, using the CLIHOST parameter to specify a TCP/IP host name and the CLIPORT parameter to specify a TCP/IP port number.
Make sure that your sessParam parameter string contains the CLIHOST and CLIPORT parameters. (CLINODE is not supported by the SDK (Java).) Otherwise, the start method throws an exception with error reason code SessionException.INVNODE (193).
CLIENDIAN provides a way to override the application endian type for a session. This parameter affects the external representation of MAP table fields with numeric internal syntaxes and the “*” external syntax. If CLIENDIAN is not specified, big endian is selected.
Return Value:
None.
Throws:
This method throws SessionException with rc = SessionException.STARTSS_FAILED (4) if a session cannot be started.
Comments
A successful start call changes a session from inactive to active. Use the isActive method to query the current state of a session. If a start call is issued for an object that is already active, the call throws an exception with a SessionException.CALLOUTOFSEQ (36) error reason code. To bring a session back to the inactive state, issue a stop, a reset, or a shutdown method call.
See Also
TIBCO Object Service Broker Parameters about starting sessions and about session Execution Environment parameters.
startTrans
Starts a transaction.

 
public void startTrans(String transParams) throws SessionException

 
Parameter:
 
Transaction parameters are specified as follows (all characters are case insensitive):
BROWSE | UPDATE, TEST | NOTEST, SEARCH=S | I | L, LIBRARY=libname
If you omit a parameter, the startTrans method uses the session default value specified in the session parameter string of the start method or of the Session constructor. These session defaults are set by the BROWSE, TEST, SEARCH, and LIBRARY session parameters. For more information, refer to TIBCO Object Service Broker Parameters.
Return Value:
None.
Throws:
This method throws SessionException with rc = SessionException.STARTTR_FAILED (10) if the method fails.
Comments
The startTrans method starts a transaction within the session. If the session already has transactions started, the startTrans method starts a child transaction.
If the session is already stopped or abended, the startTrans method throws an exception with an error reason code of SessionException.CALLOUTOFSEQ (36).
Use the stopTrans method to stop the currently active transaction.
If the maximum allowed number of transactions are already running in the session, startTrans throws an exception with an error reason code SessionException.TOOMANYTRANS (106). Refer to TIBCO Object Service Broker Parameters for information on the TRANMAXNUM Execution Environment parameter, which sets the maximum value.
stop
Stops an SDK (Java) session.

 
public void stop() throws SessionException

 
Parameters:
None.
Return Value:
None.
Throws:
This method throws SessionException with rc = SessionException.STOPSS_FAILED (9) if the method fails.
Comments
If the session is inactive, the stop method call throws an exception with a SessionException.CALLOUTOFSEQ (36) error reason code. You activate a session by using either the Session constructor with the sessParam and codepage parameters, or a start method call.
If a transaction is still active prior to the stop method call, the call throws an exception with a SessionException.TRANSACTIVE (128) error reason code and the session stays active.
Failures with error reason codes other than SessionException.TRANSACTIVE (128) indicate a failure to complete normal shutdown sequence. The session is rendered inactive anyway.
Use the isActive method to determine the current session state. Use the transNestLevel method to determine the current depth of the transaction stack
stopTrans
Stops the currently active transaction, committing or rolling back the changes.

 
public void stopTrans(boolean commit) throws SessionException

 
Parameters:
 
True if the changes made within the active transaction need to be committed, otherwise false.
Return Value:
None.
Throws:
This method throws SessionException with rc = SessionException.STOPTR_FAILED (12) if the method fails.
Comments
If the session is not active or no transaction started prior to the call, the call throws an exception with SessionException.CALLOUTOFSEQ (36) error reason code.
The current transaction is destroyed and the session nesting level is decremented even if the call ends with an error. Use the transNestLevel method to determine the current transaction nesting level.
transNestLevel
Returns the transaction nesting level of the session.

 
public int transNestLevel()

 
Parameters:
None.
Return Value:
The current transaction nesting level of the session. Returns zero if the session is not active or no transaction is started.
Exceptions:
None.
userId
Returns the user ID of the session.

 
public String userId()

 
Parameters:
None.
Return Value:
The session user ID if the session is active, otherwise null.
Exceptions:
None.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved