# MTSession

The interface to the get and set properties of a session. Also contains methods for handling transactions.

## Program ID

MetraPipeline.MTSession.1

## MTSession Methods

ClearTransaction | Removes references to the transaction.
DecryptEncryptedProp | Decrypt a property encrypted by the MetraTech Listener
GetNewTransaction | Requests creation of a new transaction object.
GetRowset | Returns a rowset from the transaction.
GetTransaction | Gets a pointer to an existing transaction instance.
GetTransactionID | If session is part of an external transaction, this method returns a transaction ID (aka cookie), otherwise it returns empty string.
SetLongProperty | Sets the value of a property as long.
GetLongProperty | Gets the value of a property as long.
SetBSTRProperty | Sets the value of a property as a string.
GetBSTRProperty | Gets the string value of a property.
SetStringProperty | Sets the value of a property as a string.
GetStringProperty | Gets the string value of a property.
SetBoolProperty | Sets the value of a property as a Boolean value.
GetBoolProperty | Gets the Boolean value of a property.
SetDoubleProperty | Sets the value of a property as a double.
GetDoubleProperty | Gets the double value of a property.
SetOLEDateProperty | Sets the value of a property as an OLE automation date.
GetOLEDateProperty | Gets the OLE automation date value of a property.
SetTimeProperty | Sets the value of a property as a time of day.
GetTimeProperty | Gets the time-of-day value of a property.
SetDateTimeProperty | Sets the value of a property as a date/time.
GetDateTimeProperty | Gets the date/time value of a property.
SessionChildren | Returns a set containing all the children of this session.

## MTSession Properties

IsParent | Returns TRUE of the session is part of a compound session and has children.
ParentID | Returns a session's parent ID. This is equivalent of the SessionID property of the parent session.
ServiceID | Returns a session's service ID.
SessionContext | Returns the session context associated with the session set. The following is the order of the session context lookup: 1. Looks if the object was already set and returns it 2. Looks if seralized version of the object was set; deserializes and returns it 3. Looks if user credentials were set; logs in the user and returns constructed session context 4. Authenticates anonymous user and returns constructed session context
SessionID | Returns the pipeline's internal session ID for this session object.
UID | Returns the session's unique ID (UID) unencoded. The UID is generated by the SDK and is unique across systems.
UIDAsString | Returns the session's unique ID (UID) base64 encoded into a string.

## MTSession Enumerated Types

MTSessionProp | Interface that describes a session property.

## Example

Example to be provided in a future release of this online help system.

# Method Detail

## ClearTransaction

This method removes all reference to a transaction from the stage.

WARNING: Transactions must be committed or rolled back before this method is called. It only releases a reference; it does not commit or rollback.

### Visual Basic Syntax

Sub ClearTransaction()

### C++ Syntax

HRESULT ClearTransaction()

## DecryptEncryptedProp

This method decrypts (or un-encrypts) a property encrypted by the MetraTech listener. Any property in a service definition with a trailing underscore will be encrypted by the listener.

### Visual Basic Syntax

Function DecryptEncryptedProp(aPropId As Long) As String

### C++ Syntax

HRESULT DecryptEncryptedProp([in] long aPropID, [out, retval] BSTR* aStringProp);

### Arguments

aPropID

the encrypted property

### Return Value

Returns the property in the clear (not encrypted).

## GetNewTransaction

This method requests that a new MTTransaction object be created.

Note: GetTransaction and GetNewTransaction differ only in whether they attempt to instantiate a new transaction object, or get a reference to an existing object within the stage. These calls have no effect on whether a particular transaction is or will be local or distributed.

### Visual Basic Syntax

Function GetNewTransaction(Configfile As String) As IMTTransaction

### C++ Syntax

HRESULT GetNewTransaction([in] BSTR ConfigFile,
[out, retval] IMTTransaction

### Arguments

ConfigFile

the path of the dbaccess.xml file. If it is not supplied, the system will use installdir\config\Database\dbaccess.xml, where installdir is the folder where you installed the MetraTech Platform.

### Return Value

Returns a pointer to a new MTTransaction instance.

## GetRowset

If txn is true, this method returns the rowset from the existing transaction. If no transaction exists, the method looks for the presence of a transaction cookie in the session's property. If the cookie exists, the method joins the transaction that is represented by the cookie and returns a transaction rowset. If the cookie does not exist, a new local transaction is created and its rowset is returned.

If txn is false, a rowset is returned. This rowset is not associated with any transaction.

This method is used by a plug-in to seamlessly provide transaction support, even if the plug-in writer does not know whether a transaction will be in progress. A plug-in may casually request a rowset using this method and operate on it. Transaction closure/rollback (if necessary) will be handled by the underlying stage.

### Visual Basic Syntax

Function GetRowset(Configfile As String, txn As Boolean) As IMTSQLRowset

### C++ Syntax

HRESULT GetRowset([in] BSTR ConfigFile,
[in] VARIANT_BOOL txn,
[out, retval] IMTSQLRowset **pSQLRowset);

### Arguments

ConfigFile

the path of the dbaccess.xml file. If it is not supplied, the system will use installdir\config\Database\dbaccess.xml, where installdir is the folder where you installed the MetraTech Platform.

txn

Flag that determines whether the plug-in is explicitly or implicitly using transaction control.

### Return Value

A Rowset.

## GetTransaction

This method gets a pointer to the existing MTTransaction instance. The transaction instance was created by a previous plug-in. If no transaction object is instantiated, NULL is returned.

### Visual Basic Syntax

Function GetTransaction() As IMTTransaction

### C++ Syntax

HRESULT GetTransaction([out, retval] IMTTransaction **xaction);

### Return Value

Returns a pointer to the existing MTTransaction instance, or NULL if there is no existing transaction instance.

## GetTransactionID

If session is part of an external transaction, this method returns a transaction ID (aka cookie), otherwise it returns empty string.

### Visual Basic Syntax

GetTransactionID(apTransactionID As String)

C++ Syntax

GetTransactionID([out, retval] BSTR* apTransactionID);

## SetLongProperty

Sets the value of a property as long.

### Visual Basic Syntax

Sub SetLongProperty(propid As Long, propval As Long)

### C++ Syntax

HRESULT SetLongProperty (long propid, long propval) ;

### Arguments

propid

Property ID of the property to set.

### Return Value

The property value.

## GetLongProperty

Gets the value of a property as long.

### Visual Basic Syntax

Function GetLongProperty(propid As Long) As Long

### C++ Syntax

HRESULT GetLongProperty (long propid, [out, retval] long * propval)

### Arguments

propid

The property ID of the property to get.

### Return Value

The property value.

## SetBSTRProperty

Sets the value of a property as a string.

### Visual Basic Syntax

Sub SetBSTRProperty(aPropId As Long, aValue As String)

### C++ Syntax

HRESULT SetBSTRProperty (long aPropId, BSTR aValue) ;

### Arguments

propid

The property ID of the property to set.

### Return Value

The property value.

## GetBSTRProperty

Gets the string value of a property.

### Visual Basic Syntax

Function GetBSTRProperty(aPropId As Long) As String

### C++ Syntax

HRESULT GetBSTRProperty (long aPropId, [out, retval] BSTR * apValue) ;

### Arguments

propid

The property ID of the property to get.

### Return Value

The property value.

## SetStringProperty

Sets the value of a property as a string.

### Visual Basic Syntax

Sub SetStringProperty(aPropId As Long, aValue As String)

### C++ Syntax

HRESULT SetStringProperty (long aPropId, BSTR aValue) ;

### Arguments

propid

The property ID of the property to set.

### Return Value

The property value.

## GetStringProperty

Gets the string value of a property.

### Visual Basic Syntax

Function GetStringProperty(aPropId As Long) As String

### C++ Syntax

HRESULT GetStringProperty (long aPropId, [out, retval] BSTR * apValue) ;

### Arguments

propid

The property ID of the property to get.

### Return Value

The property value.

## SetBoolProperty

Sets the value of a property as a Boolean value.

### Visual Basic Syntax

Sub SetBoolProperty(aPropId As Long, aVal As Boolean)

### C++ Syntax

HRESULT SetBoolProperty (long aPropId, VARIANT_BOOL aVal) ;

### Arguments

propid

The property ID of the property to set.

### Return Value

The property value.

## GetBoolProperty

Gets the Boolean value of a property.

### Visual Basic Syntax

Function GetBoolProperty(propid As Long) As Boolean

### C++ Syntax

HRESULT GetBoolProperty (long propid, [out, retval] VARIANT_BOOL * apValue) ;

### Arguments

propid

The property ID of the property to get.

### Return Value

The property value.

## SetDoubleProperty

Sets the value of a property as a double.

### Visual Basic Syntax

Sub SetDoubleProperty(aPropId As Long, aValue As Double)

### C++ Syntax

HRESULT SetDoubleProperty (long aPropId, double aValue) ;

### Arguments

propid

The property ID of the property to set.

### Return Value

The property value.

## GetDoubleProperty

Gets the double value of a property.

### Visual Basic Syntax

Function GetDoubleProperty(aPropId As Long) As Double

### C++ Syntax

HRESULT GetDoubleProperty (long aPropId, [out, retval] double * apValue) ;

### Arguments

propid

The property ID of the property to get.

### Return Value

The property value.

## SetOLEDateProperty

Sets the value of a property as an OLE automation date.

### Visual Basic Syntax

Sub SetOLEDateProperty(propid As Long, propval As Date)

### C++ Syntax

HRESULT SetOLEDateProperty (long propid, DATE propval) ;

### Arguments

propid

The property ID of the property to set.

### Return Value

The property value.

## GetOLEDateProperty

Gets the OLE automation date value of a property.

### Visual Basic Syntax

Function GetOLEDateProperty(propid As Long) As Date

### C++ Syntax

HRESULT GetOLEDateProperty (long propid, [out, retval] DATE * propval) ;

### Arguments

propid

The property ID of the property to get.

### Return Value

The property value.

## SetTimeProperty

Sets the value of a property as a time of day.

### Visual Basic Syntax

Sub SetTimeProperty(propid As Long, propval As Long)

### C++ Syntax

HRESULT SetTimeProperty (long propid, longpropval) ;

### Arguments

propid

The property ID of the property to set.

### Return Value

The time of day, expressed as seconds after midnight.

## GetTimeProperty

Gets the time-of-day value of a property.

### Visual Basic Syntax

Function GetTimeProperty(propid As Long) As Long

### C++ Syntax

HRESULT GetTimeProperty (long propid, [out, retval] long * propval) ;

### Arguments

propid

The property ID of the property to get.

### Return Value

The time-of-day value, expressed as seconds after midnight.

## SetDateTimeProperty

Sets the value of a property as a date/time.

### Visual Basic Syntax

Sub SetDateTimeProperty(propid As Long, propval As Long)

### C++ Syntax

HRESULT SetDateTimeProperty (long propid, long propval) ;

### Arguments

propid

The property ID of the property to set.

### Return Value

The property value, which is the date/time expressed in UNIX time based on Greenwich Mean Time (GMT).

## GetDateTimeProperty

Gets the date/time value of a property.

### Visual Basic Syntax

Function GetDateTimeProperty(propid As Long) As Long

### C++ Syntax

HRESULT GetDateTimeProperty (long propid, [out, retval] long * propval) ;

### Arguments

propid

The property ID of the property to get.

### Return Value

The property value, which is the date/time expressed in UNIX time based on Greenwich Mean Time (GMT).

## SessionChildren

Returns a set containing all the children of this session.

### Visual Basic Syntax

Function SessionChildren() As MTSessionSet

### C++ Syntax

HRESULT SessionChildren ( [out, retval] IMTSessionSet * * apSet) ;

### Return Value

A set of all the session's children.

# Property Detail

## SessionContext

Returns the session context associated with the session set. The following is the order of the session context lookup:

1. Looks if the object was already set and returns it

2. Looks if seralized version of the object was set; deserializes and returns it

3. Looks if user credentials were set; logs in the user and returns constructed session context

4. Authenticates anonymous user and returns constructed session context

### Visual Basic Syntax

SessionContext As IMTSessionContext

C++ Syntax

HRESULT SessionContext([out, retval] IMTSessionContext pctx);

## IsParent

Returns TRUE if the session is part of a compound session and has children. This is a read-only property.

### Visual Basic Syntax

Property IsParent As Boolean

### C++ Syntax

HRESULT IsParent ( [out, retval] VARIANT_BOOL * isparent) ;

### Return Value

TRUE if session is a parent; FALSE otherwise.

## ParentID

Returns a session's parent ID. This is the equivalent of the SessionID property of the parent session. This is a read-only property.

### Visual Basic Syntax

Property ParentID As Long

### C++ Syntax

HRESULT ParentID ( [out, retval] long * pVal) ;

### Return Value

The session ID of the session's parent.

## ServiceID

Returns a session's service ID. This is a read-only property.

### Visual Basic Syntax

Property ServiceID As Long

### C++ Syntax

HRESULT ServiceID ( [out, retval] long * pVal) ;

### Return Value

The session's service ID.

## SessionID

Returns the pipeline's internal session ID for this session object. This is a read-only property.

(The sessionID is the index of this session within shared memory and is unrelated to the session's unique ID.)

### Visual Basic Syntax

Property SessionID As Long

### C++ Syntax

HRESULT SessionID ( [out, retval] long * pVal) ;

### Return Value

The session ID.

## UID

Returns the session's unique ID (UID) unencoded. (The UID is generated by the SDK and is unique across systems.) This is a read-only property.

### Visual Basic Syntax

Property UID(UID(0 To 15) As Byte)

### C++ Syntax

HRESULT UID ( [out] unsigned char uid[16] ) ;

### Return Value

The session's UID.

## UIDAsString

Returns the session's unique ID (UID) base64-encoded into a string. This is a read-only property.

### Visual Basic Syntax

Property UIDAsString As String

### C++ Syntax

HRESULT UIDAsString ( [out, retval] BSTR * pVal) ;

### Return Value

The session's UID.