Using the Stateless API Functions

Understanding Connections, Sessions, and Transactions in the Stateless API

The Stateless API connects to Middleware host as defined by the Middleware Proxy Configuration on the computer it is running under. The Stateless API runs locally on the machine, but interacts with the Middleware host. The host does most of the work, which includes connecting to the database and any logic. The Stateless API (aaMES.dll) is responsible for packaging the calls and managing the result set or data objects.

Generally, a session is required when you modify the database (Create or Update method), whereas it is not required when you query the database (Get methods). When a session is created for the Stateless API, a corresponding record is created in the database. Although it is a stateless API, some methods require a session to define the user. For such methods, as long as you pass a valid session, the transaction will go through using the user associated with that session. You must manage the session within the application to ensure that the correct user is associated with the transaction. It is recommended to logon to a session and before each script block, you must validate that you have a SessionID.

Transactions are designed to execute a StartTransaction command at the beginning of the script and a CommitTransaction command or AbortTransaction command at the end of the script. Transactions apply to the thread that they are running under. In System Platform script for Objects, there is one thread for synchronous scripts and there is a separate thread for each asynchronous script. It is recommended to use asynchronous scripts with System Platform Objects.

You can call the StartTransaction command only once. If the transaction has already started, the second StartTransaction command is ignored. A transaction is aborted if an API call fails. It is recommended to use Transaction control to call and check the status. If it fails, call it again. The following is an example code:

System Platform Sample Script CS

Dim aaResult As aaMES.Result;
aaResult = aaMES.Core.aaTransaction.StartTransaction();
If Not aaResult.Success Then
    me.resultText = "StartTransaction 1st try Failed: " + aaResult.Exception.Message;
    aaResult = aaMES.Core.aaTransaction.StartTransaction();
EndIf;
If aaResult.Success Then
    me.resultText  = "StartTransaction PASSED" ;
    'main code block
Else
    me.resultText  = "StartTransaction Failed: " + aaResult.Exception.Message;
EndIf;

Visual Basic .NET Sample Script

Dim aaResult As aaMES.Result
aaResult = aaMES.Core.aaTransaction.StartTransaction
If Not aaResult.Success Then
    Me.resultText.Text = "StartTransaction 1st try Failed: " + aaResult.Exception.Message
    aaResult = aaMES.Core.aaTransaction.StartTransaction
End If
If aaResult.Success Then
    Me.resultText.Text = "StartTransaction PASSED"
    'main code block
Else
    Me.resultText.Text = "StartTransaction Failed: " + aaResult.Exception.Message
End If