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


Chapter 3 Using OIG for .NET : eCTSsession Methods

eCTSsession Methods
Opening Object Integration Gateway Sessions
OpenApplication
Opens an Object Integration Gateway session. An application must open an OIG session to run an OIG 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()
MySession.OpenApplication(mode)
MySession.OpenApplication(poolName)
MySession.OpenApplication(poolName, mode)
MySession.OpenApplication(sessionParms)
MySession.OpenApplication(sessionParms, mode)
The case-sensitive name of a defined pool for a set of OIG session parameters. Pool names are held in the Windows registry. By default such sessions are pooled.
If set to Mode.Pooled sessions are created once and pooled for reuse after being released.
If set to Mode.Unpooled sessions are terminated after being released.
 
If you call the OpenApplication method without specifying either the poolName parameter or the sessionParms parameter, the default OIG 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” on page 28.
Syntax:
MySession.Close()
The storage for objects under .NET’s Common Language Runtime (CLR) Environment is managed by a garbage collector. Remember that objects are reclaimed, and the destructor for the object is invoked, when the CLR garbage collector chooses to do so.
A VB .NET programmer should not expect the underlying TIBCO Object Service Broker session of an opened eCTSsesssion object to be released when the program sets the variable’s object reference to Nothing. For example:
MySession = Nothing
It is good practice to invoke the Close method to release the underlying resources for an eCTSsession when the object is no longer needed. Otherwise, your application could run out of TIBCO Object Service Broker sessions because the CLR garbage collector has not been invoked for a long period of time.
Dispose
Immediately closes an OIG session. This is an alias for the Close method.
Syntax:
MySession.Dispose()
Invoking Processing
The methods in this section can be used to invoke functionality defined to Object Integration Gateway. Each of the OIG objects (for example, transactions) can be explicitly invoked.
RunRule
Runs a rule within the current transaction. Before a rule can be called, a transaction must be started by calling the StartTran method.
Syntax:
MySession.RunRule(ruleName)
MySession.RunRule(ruleName, parms)
A collection of names and their values to be passed to the Gateway rule. The parameters specified for this argument override the parameters specified in the URL query string or passed by a POST from an HTML form.
RunTrans
Runs the named transaction.
Syntax:
MySession.RunTrans(transName)
MySession.RunTrans(transName, parms)
A collection of names and their values to be passed to the transaction. The parameters specified for this argument override the 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(docName)
MySession.RunXmlDoc(docName, parms)
A collection of names and their values to be passed to the XML document. The parameters specified for this argument override the parameters specified in the URL query string or passed by a POST from an HTML form.
StartTran
Starts an OIG transaction. Subsequent RunXmlDoc 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 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 true, updates made to tables during the transaction are applied to the MetaStore when the transaction is terminated.
Handling Data
The methods in this section can be used to pass data to and from Object Integration Gateway either as a ADO.NET DataTable, or as an XML document.
GetDataSet
Returns all the OIG tables returned by the last RunTrans, RunXmlDoc, or RunRule call as a collection of ADO.NET DataTables in an ADO.NET DataSet object. The name of a DataTable in the collection is the name of the interface table.
Return type: ADO.NET DataSet object
Syntax:
dataset = MySession.GetDataSet()
GetDocument
Returns an XML document generated by the last execution of the RunTrans or RunXmlDoc methods.
Return type: String
Syntax:
xml = MySession.GetDocument()
xml = MySession.GetDocument(docName)
The name of the XML document returned. If this parameter is not specified, GetDocument returns the first XML document in the result set.
GetDocumentFromTable
Returns the XML for an interface table returned by the last RunTrans or RunRule call. Normally interface tables are returned as ADO.NET DataTables using the GetTable method.
Return Type: String
Syntax:
dataset = MySession.GetDocumentFromTable(tableName)
GetTable
Converts an XML document from the last Run method call to an ADO.NET DataTable object, and returns the DataTable object. The XML document must be of type ADO.NET.
Return type: ADO.NET DataTable object
Syntax:
datatable = MySession.GetTable()
datatable = MySession.GetTable(documentName)
The name of the XML document to be extracted. The XML document must be of type ADO.NET. 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.NET DataTable object, and returns the DataTable object. The XML document must be of type ADO.NET 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.NET DataTable
Syntax:
datatable = MySession.GetTableFromDocument(documentName)
GetTableOfContent
Returns all data returned by the last RunTrans, RunXmlDoc, or RunRule call as an ADO.NET DataTable. 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 DataTable returned contains three columns, each row of the table describing a result returned.
Possible types of returned data are as follows:
Return type: ADO.NET DataTable object
Syntax:
datatable = MySession.GetTableOfContent()
GetXmlDocument
Returns an XML document generated by the last execution of the RunTrans, RunRule, or RunXmlDoc methods. The resultant XML data is held in a .NET XML DOM object.
Return type: System.Xml.XmlDocument object
Syntax:
xmlDoc = MySession.GetXmlDocument()
xmlDoc = MySession.GetXmlDocument(docName)
The name of the XML document returned. If this parameter is not specified, GetXmlDocument returns the first XML document in the result set.
GetXmlTextReader
Returns an XML document generated by the last execution of the RunTrans or RunXmlDoc methods. The resultant XML data is held in a .NET XmlTextReader object. The XmlTextReader object provides a high-performance, forward-only and read-only way of accessing XML data. The model is similar to the SAX XML model, but implemented as a pull model rather than the SAX push model.
Return type: System.Xml.XmlTextReader object
Syntax:
xmlDoc = MySession.GetXmlTextReader()
xmlDoc = MySession.GetXmlTextReader(docName)
The name of the XML document returned. If this parameter is not specified, GetXmlTextReader returns the first XML document in the result set.
SetDocument
Stages an XML document to be sent to OIG on the next Run method call. You can call the SetDocument method multiple times to stage multiple documents for the next Run method call.
Syntax:
MySession.SetDocument(docName, xmlDoc)
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.NET DataTable object to an TIBCO Object Service Broker data table. The SetTable method converts the DataTable 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, datatable)
The name of the TIBCO Object Service Broker table the DataTable is loaded into when the next OIG object is invoked.
ADO.NET DataTable object
The ADO.NET DataTable to be passed to TIBCO Object Service Broker.
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.
SetXmlDocument
Stages an XML document to be sent to OIG on the next Run method call. The document is passed via a .NET DOM object (System.Xml.XmlDocument). You can call the SetXmlDocument method multiple times to stage multiple documents for the next Run method call.
Syntax:
MySession.SetXmlDocument(docName, xmlDoc)
The name of the OIG XML document definition used for processing the incoming XML document.
System.Xml.
XmlDocument object
Handling HTML and Messages
GetEndMsg
Returns the end message from the last execution of RunTrans or RunXmlDoc. 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.
Return type: String
Syntax:
html = MySession.GetResult()
ASPX Example:
MySession.RunTrans("DEMOTX")
Response.Write(MySession.GetResult())
Handling Errors from eCTSsession
An eCTSsession object throws an eCTSexception object if an error occurs. The eCTSexception class is derived from the .NET ApplicationException class, and has additional properties you can use to get information about rule failures in your OIG application.
You can use the eCTSexception object’s Message property to get the reason for the error. You can also use the following two eCTSexception properties to obtain more information about the error.
HtmlErrorLog
If a rule fails in the OIG application, the rules trace back is returned as string in HTML format. If the error is not due to a rules failure, an empty string is returned.
Syntax:
html = MyeCTSexception.HtmlErrorLog
TextErrorLog
If a rule fails in the OIG application, the rules trace back is returned as string. Each line of the trace back ends with a carriage return followed by a line feed. If the error is not due to a rules failure, an empty string is returned.
Syntax:
text = MyeCTSexception.TextErrorLog
Managing Persistent Data for Web Sessions
When using OIG with ASP.NET web applications, 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
Applications that run in a web environment, such as those using ASP.NET, can use the AddSessionParm and RemoveSessionParm methods to manage a list of web session variables stored in the IIS Session object. However, 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 eCTSsession object. 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 ASP.NET. 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:
varValue = 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