|
|
|
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 second form of this method throws SessionException with rc = SessionException.STARTSS_FAILED (4) if a session cannot be started.
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.
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.
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 abends or is 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 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.
|
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 Object Service Broker Managing Data.
When a rule completes successfully, 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. Then, before transmitting data back, the Execution Environment reevaluates the dataOut header to determine the correct number of bytes to send back to the application. You cannot 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 rule call), the call fails with a SessionException.DATAOUTCORRUPT (49409) error reason code.
TIBCO Object Service Broker Shareable Tools and
TIBCO Object Service Broker Managing Data about the @SESSION(0) table and the MAP tables.
The end message from the last rule 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).
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 rule 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.
Equivalent to executing a sequence of startTrans,
call, and
stopTrans methods. The changes are committed if the rule call succeeds and rolled back if it throws an exception.
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 value of rc is either SessionException.STARTTR_FAILED (10), SessionException.CALLRULE_FAILED (11), or SessionException.STOPTR_FAILED (12) depending on the stage where the first error occurred.
The only phase able to interrupt the sequence is the startTrans phase. After that phase has succeeded, the failure of the rule 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.
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 abended, isActive returns false.
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.
The value of rc is either SessionException.STOPTR_FAILED (12) or SessionException.STOPSS_FAILED (9) depending on the stage where the first error occurred.
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.
Starts an SDK (Java) session.
|
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):
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).) If not, 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.
This method throws SessionException with rc = SessionException.STARTSS_FAILED (4) if a session cannot be started.
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.
TIBCO Object Service Broker Parameters about starting sessions and about session Execution Environment parameters.
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.
This method throws SessionException with rc = SessionException.STARTTR_FAILED (10) if the method fails.
The startTrans method starts a transaction within the session. If the session already has transactions started, the startTrans method starts a child transaction.
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.
Stops an SDK (Java) session.
This method throws SessionException with rc = SessionException.STOPSS_FAILED (9) if the method fails.
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
This method throws SessionException with rc = SessionException.STOPTR_FAILED (12) if the method fails.
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.