Working with transactions

With a transaction you can ensure that either all database modifications of a command are executed or rolled back in case of an error (so that the command has no database modifying affect whatsoever).

It is possible to put requests into a transaction context.

      <request>
        <import transaction="true">
          <fields>
            <Company>
              <Company>update software AG</Company>
              <Person>
                  <Wrong>wrong fieldname</ Wrong >
                  <FirstName>John</FirstName>
                  <LastName>Doe</LastName>
                </Person>
            </Company>
          </fields>
        </import>
      </request>

In this sample the company record is NOT inserted due to an error occurring in the following person record (“wrong fieldname”). In order to ensure a rollback of the transaction, the attribute transaction has to be set on the <import> element.

The response returns the error and information about the transaction rollback:

      <response>
        <import transaction="true">
          <return table="FI" tablename="Company" id="4294981504" type="insert"/>
          <return table="KP" id="0" type="error" func="C_Portal::ProcessImportNode">
            <ecode>-10027</ecode>
            <etext>Dictionary: Field not found</etext>
            <table table="KP" tablename="Person"/>
            <field>Wrong</field>
          </return>
          <return type="error" func="C_Portal::XmlProcessCommand">
            <ecode>-10089</ecode>
            <etext>Database transaction: Rollback</etext>
          </return>
        </import>
      </response>

It is possible to put the whole request into a transaction context and/or to control the transaction individually.

If the transaction attribute is set on the request element the behavior is the same as described above for command elements. All commands are executed in one transaction.

      <request transaction="true">
        <putdoc>
          <Name>Testdatei.txt</Name>
          <Keyword>Putdoc_Test</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </putdoc>
        <import>
          <fields>
            <Documents>
              <links>
                <link tablename="Documents" id="$lastRecId"/>
              </links>
              <Private>false</Private>
              <DocClass>Textfile</DocClass>
              <Owner>Own RepName</Owner>
              <FreeC1>Test</FreeC1>
              <!-- … -->
            </Documents>
          </fields>
        </import>
      </request>

In this example, if the import fails, the document is not created as well.

Transactions can be started and active transactions can be committed or rolled back explicitly using the <transaction> command. Transactions are started with cmd="begin", and ended with cmd="end" (rollback on error, otherwise commit), cmd="commit" (explicit commit), or cmd="rollback" (explicit rollback).

      <request>
        <!-- ... -->
        <transaction cmd="begin"/>
        <import>
          <fields>
            <Company>
              <Company>update software AG</Company>
              <Person>
                <Wrong>
                  wrong fieldname</ Wrong >
                  <FirstName>John</FirstName>
                  <LastName>Doe</LastName>
                </Person>
            </Company>
          </fields>
        </import>
        <!-- ... -->
        <transaction cmd="end"/><!—end|commit|rollback -->
        <!-- ... -->
      </request>