Updategrams tutorial
General Updategrams

## Updategram Overview

Updategrams allow database updates to be defined as XML. This is ultimately achieved by mapping the XML nodes against corresponding database columns.

Updategrams can be used to replace existing data access components in a middle tier. A typical application will include a middle tier consisting of Business Logic and Data Access code. The Data Access code will interface with the database using disconnected Recordsets and Command objects calling stored procedures etc. Most of the Data Access section of the middle tier can be replaced with Updategrams.

Most Data Access tiers (both middle tier code and stored procedures) will individually deal with specific database tables or groups of related tables. This can inhibit performance and quite often several round trips to the database are required to complete a transaction.

Updategrams can solve this problem by including all of the data in an XML document, which is then mapped to database tables and columns. The entire database update can then be accomplished in one fell swoop. This update can include inserting, updating and deleting data.

The 'xmlsql_update' function supports XML-based insert, update, and delete operations performed on an existing table in database.

## Updategram Basics

The general format of an updategram is:

    <sql:sync xmlns:sql="xml-sql">
            <sql:before>
                    <TABLENAME [sql:id="value"] col="value" col="value"?../>
            </sql:before>
            <sql:after>
                    <TABLENAME [sql:id="value"] [sql:at-identity="value"] col="value" col="value"?../>
            </sql:after>
    </sql:sync>

    or

    <sql:sync xmlns:sql="xml-sql">
            <sql:before>
                    <TABLENAME [sql:id="value"]>
    		   <col>"value"</col>
    		   <col>"value"</col>
    		   ...
    		</TABLENAME>
    		...
            </sql:before>
            <sql:after>
                    <TABLENAME [sql:id="value"] [sql:at-identity="value"]>
    		   <col>"value"</col>
    		   <col>"value"</col>
    		   ...
    		</TABLENAME>
    		...
            </sql:after>
    </sql:sync>

## Elements Description

- The <sync> tag of the updategram signifies the beginning of an operation(s).
- The rows specified in the <before> refer to existing records in the database.
- The rows specified in the <after> block refer to what the user wants in the database.
- TABLENAME identifies target table.
- The sql:at-identity attribute stores the last identity value added by the system (if possible).
- The captured identity value can then be used in subsequent operations.
- The sql:id attribute is used to mark rows. This forces an association between the record specified in the <before> and <after> block in the updategram.
- When there are multiple instances specified, it is recommended that sql:id attribute be used for all of the instances.
- Each TABLENAME refers to a single table. Multiple <TABLENAME..../> entries are allowed in the same <before> , or <after> tags, or in both <before> and <after> tags; however, nesting is not allowed.
- The <before> and <after> tags are optional. A missing tag is the same as having a tag with no content.

## Determining Actions

In an updategram if only the <after> block is specified, the rows specified in the <after> block are inserted in the table(s). If both the <before> and <after> blocks are specified, then the rows specified in the <after> block for which there is no corresponding rows in the <before> block are inserted in the table(s). In an update operation, the instances (rows) specified in the <before> block refer to the existing rows in the database. The corresponding instances (rows) in the <after> block reflect what the user wants in the database. A row update operation is performed if there is an instance (row) in both <before> and <after> sections with the same set of values for the attributes that uniquely identify a row in a table. The set of rows specified in the <before> block must be valid in the database for the updategram to successfully update the rows. In a delete operation, if only the <before> block is specified in the updategram, the instances (rows) specified in the <before> block are deleted from the table(s). If both the <before> and <after> blocks are specified, the instances (rows) for which there is no corresponding instances (rows) in the <after> block are deleted from the table(s).

## Example

- This example creates a SQL function that takes the orders and order lines from the demo database and applies a stylesheet to the FOR XML rendition of these to make updategrams. Use the updategrams to fill out a similar table structure containing order summary with only fulfilled orders included.

The interface will show the sources of the report and the transformed report which is the updategram.