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


Chapter 4 Using the OIG COM Component : eCTSsession Methods

eCTSsession Methods
Opening Object Integration Gateway Sessions
OpenApplication
Opens an Object Integration Gateway session. An application must open a session to run a transaction or XML document. The OpenApplication method enables you to either create a new session, or borrow one from a pool of existing sessions. Pooled sessions are shared between one or more applications.
Syntax:
MySession.OpenApplication alias [,, mode]
MySession.OpenApplication , sessParms [, mode]
alias (optional)
The case-sensitive name of a defined alias for a set of session parameters. Aliases are held in the Windows registry. By default, sessions are pooled.
sessParms (optional)
mode (optional)
If set to “POOLED”, sessions are created once and pooled for reuse after being released. If set to “UNPOOLED”, sessions are terminated after being released.
Re parameters  You can pass either the alias parameter or the sessParms parameter, but not both. If you pass the alias parameter, the session is pooled by default, unless UNPOOLED is specified for the optional mode parameter. If you pass the sessParms parameter, the session is unpooled by default, unless POOLED is specified for the option mode parameter.
Re default behavior  If you call the OpenApplication method without specifying either the alias parameter or the sessParms parameter, the default Gateway session parameter settings are used. The default session parameters are determined in one of the following two ways:
Closing Object Integration Gateway Sessions
Close
Immediately closes an OIG session. If the underlying session was pooled, the session is returned to the pool of sessions for re-use by another application. If the session was not pooled, the session is terminated and the TIBCO Object Service Broker resources associated with the session are released. If there is a transaction in progress, this transaction is terminated and any updates pending are rolled back. Refer to StartTran.
Syntax: MySession.Close
Invoking Processing
You can use the methods in this section to invoke functionality that is defined to Object Integration Gateway. Each of the objects (for example, transactions) can be explicitly invoked.
RunRule
Runs a rule within the current transaction. A transaction must be started by calling the StartTran method before a rule can be called.
Syntax: MySession.RunRule rulename[, parameters]
parameters (optional)
String array
An array of name-value pairs to be passed to the rule. The parameters specified for this argument override any parameters specified in the URL query string or passed by a POST from an HTML form.
RunTrans
Runs the named transaction.
Syntax: MySession.RunTrans transactionname[, parameters]
parameters (optional)
String array
An array of name-value pairs to be passed to the transaction. The parameters specified for this argument override any parameters specified in the URL query string or passed by a POST from an HTML form.
RunXMLDoc
Obtains or extracts the named XML document.
Syntax: MySession.RunXMLDoc xmldocname[, parameters]
parameters (optional)
String array
An array of name-value pairs to be passed to the XML document. The parameters specified for this argument override any parameters specified in the URL query string or passed by a POST from an HTML form.
StartTran
Starts an OIG transaction. Subsequent RuleXmlDoc or RunRule calls run within the transaction. The transaction is terminated by the next StopTran or Close call. A call to RunTrans while a transaction is active results in the nesting of a TIBCO Object Service Broker transaction to run the OIG transaction. Only one started transaction can be active for an OIG session at one time. Starting a second transaction results in an error.
Syntax: MySession.StartTran updateMode
If this parameter is set to true, updates are permitted while running the transaction. Otherwise, updates are not permitted and locks are not taken for tables.
StopTran
Stops an OIG transaction.
Syntax: MySession.StopTran commit
If this parameter is set to true, updates made to tables during the transaction are applied to the MetaStor when the transaction is terminated.
Handling Data
You can use the methods in this section to pass data to and from Object Integration Gateway, either as a recordset (ADO 2.5 or later) or as an XML document.
GetDocumentFromTable
Returns the XML for an interface table returned by the last RunTrans, RunXmlDoc, or RunRule call as a string. Normally interface tables are returned as ADO Recordset using the GetTable method (refer to GetTable.)
Return type: String
Syntax: dataset = MySession.GetDocumentFromTable tablename
GetTable
Converts an XML document from the last Run method call to an ADO Recordset object, and returns the recordset object. The XML document must be of type MSSCHEMA.
Return type: ADO 2.5 Recordset object
Syntax: recordset = MySession.GetTable [xmldocname]
xmldocname (optional)
The name of the XML document to be extracted. The XML document must be of type MSSCHEMA. If this parameter is not specified, GetTable converts the first XML document in memory.
GetTableFromDocument
Converts an XML document from the last Run method call to an ADO Recordset object, and returns the recordset object. The XML document must be of type MSSCHEMA and is produced as a result of running an XML document rather than as a result of the Pass Data to Client option of an interface table.
Return type: ADO 2.5 Recordset object
Syntax: recordset = MySession.GetTableFromDocument docname
GetTableOfContent
Returns all data returned by the last RunTrans, RunXmlDoc, or RunRule call as an ADO Recordset. This includes interface tables, XML documents, and persistent variables.
The table-of content information related to persistent data is present only if the OIG session has been opened with debug mode specified. Refer to the session parameter DEBUG for more information.
The Recordset returned contains three columns, each row of the table describing a result returned.
Possible types of returned data are as follows:
Return type: ADO 2.5 Recordset object
Syntax:
recordset = MySession.GetTableOfContent
SetDocument
Stages one or more XML documents to be sent to OIG on the next Run method call.
Syntax: MySession.SetDocument docname, document
The name of the OIG XML document definition used for processing the incoming XML document.
SetDocumentFromFile
Stages an XML document to be sent to OIG on the next Run method call. The source of the XML document is read from the file identified by the filename parameter. The filename can be a complete path name or a filename that is relative to the current working directory.
Syntax: MySession.SetDocumentFromFile docname, filename
SetTable
Passes the contents of an ADO Recordset object to a TIBCO Object Service Broker data table. The SetTable method converts the recordset to an XML document of type MSSCHEMA, so that when the next OIG object is invoked, the XML document is sent along with any other parameters and loaded into the named TIBCO Object Service Broker data table.
You can use the SetTable method to pass data to TIBCO Object Service Broker that is required by an OIG object invoked by a subsequent Run method.
Syntax: MySession.SetTable tablename, recordset
The name of the TIBCO Object Service Broker table the recordset is loaded into when the next OIG object is invoked.
ADO 2.5 Recordset object
When the destination table is a TIBCO Object Service Broker screen table, and the subsequently invoked OIG transaction has an associated TIBCO Object Service Broker screen, the data is loaded into that screen table for the screen named in the OIG object definition.
Handling Other Data
In some situations, the result from the Run method is not to be processed as a recordset. In these cases, the following methods manipulate the result string.
GetDocument
Returns an XML document generated by the last execution of the RunTrans or RunXMLDoc methods.
Return type: String
Syntax: xml = MySession.GetDocument [xmldocname]
xmldocname (optional)
The name of the XML document returned. If this parameter is not specified, GetDocument returns the first XML document in the result set.
GetEndMsg
Returns the end message from the last execution of RunTrans or RunXMLDoc. The GetEndMsg method does not take parameters.
The GetEndMsg method is typically used after executing a Run method.
Return type: String
Syntax: msg = MySession.GetEndMsg
GetResult
Returns the HTML generated by the last execution of a Run method. The GetResult method does not take parameters.
Return type: String
Syntax: html = MySession.GetResult
ASP Example:
MySession.RunTrans "DEMOTX"
Response.Write = MySession.GetResult
Managing Persistent Data for Web Sessions
When using OIG with web applications that use Active Server Pages or Visual Basic, it is a common technique to store application state information within the IIS Session object. You can use the following methods for OIG to access relevant session variables by setting up a list of variables that are automatically passed to a Run method. The data that is passed is available via the {argname} syntax when you define OIG objects, or via the ECTSGETARG and ECTSGETSESS utility rules. You can also use the ECTSSETSESS utility rule to update the IIS Session object. The IIS Session object is updated at the end of the Run method.
AddSessionParm
Adds a name to the list of session variables passed to the rules engine at execution of RunTrans or RunXMLDoc.
Syntax: MySession.AddSessionParm varname
RemoveSessionParm
Removes a name from the list of session variables passed to the rules engine at execution of RunTrans or RunXMLDoc.
Syntax: MySession.RemoveSessionParm varname
Managing Persistent Data for Non-Web Sessions
OIG applications that run in a web environment, such as those using Active Server Pages, can use the AddSessionParm and RemoveSessionParm methods to manage a list of web session variables stored in the IIS Session object. However, OIG applications running in non-web environments do not have access to the IIS Session object or its variables. You can use the following methods for a non-web application to create and access a list of session variables that is stored by the COM component. These non-web session variables are stored as a collection of name-value pairs that is passed to, and can be updated by, any of the Run methods.
The following methods can also be called by applications running in a web environment such as Active Server Pages. In such cases, the session variables are stored as web session variables in the IIS Session object.
GetPersistentData
Returns the value of an OIG session variable.
Return type: String
Syntax: value = MySession.GetPersistentData varname
SetPersistentData
Sets the value of an OIG session variable. If the named session variable is not set, the variable is added to the list of session variables passed to the rules engine on subsequent Run method calls. If the session variable is set to an empty string, the variable is removed from the list of variables passed.
Web applications can also use this method to add to, or remove from, the list of web session variables normally managed by the AddSessionParm and RemoveSessionParm methods.
Syntax: MySession.SetPersistentData varname, varvalue

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