--- title: "Updating Data Using XML Updategrams (SQLXML 4.0) | Microsoft Docs" ms.custom: "" ms.date: "03/17/2017" ms.prod: "sql-server-2016" ms.reviewer: "" ms.suite: "" ms.technology: - "dbe-xml" ms.tgt_pltfrm: "" ms.topic: "reference" helpviewer_keywords: - "IDREF type attribute [SQLXML]" - "before attribute" - " block" - " block" - "id attribute" - " block" - "updg:after attribute" - "mapping-schema attribute" - "IDREFS type attribute [SQLXML]" - "updg:id attribute" - "multiple record updates" - "after attribute" - "updategrams [SQLXML], updating data" - "updg:before attribute" - "record updates [SQLXML]" ms.assetid: 90ef8a33-5ae3-4984-8259-608d2f1d727f caps.latest.revision: 28 author: "douglaslMS" ms.author: "douglasl" manager: "jhubbard" --- # Updating Data Using XML Updategrams (SQLXML 4.0) When you update existing data, you must specify both the **\** and **\** blocks. The elements specified in the **\** and **\** blocks describe the desired change. The updategram uses the element(s) that are specified in the **\** block to identify the existing record(s) in the database. The corresponding element(s) in the **\** block indicate how the records should look after executing the update operation. From this information, the updategram creates an SQL statement that matches the **\** block. The updategram then uses this statement to update the database. This is the updategram format for an update operation: ``` [ ... ] [ ...] ``` **\** The elements in the **\** block identify existing records in the database tables. **\** The elements in the **\** block describe how the records specified in the **\** block should look after the updates are applied. The **mapping-schema** attribute identifies the mapping schema to be used by the updategram. If the updategram specifies a mapping schema, the element and attribute names specified in the **\** and **\** blocks must match the names in the schema. The mapping schema maps these element or attribute names to the database table and column names. If an updategram does not specify a schema, the updategam uses default mapping. In default mapping, the **\** specified in the updategram maps to the database table and the child elements or attributes map to the database columns. An element in the **\** block must match with only one table row in the database. If the element either matches multiple table rows or does not match any table row, the updategram returns an error and cancels the entire **\** block. An updategram can include multiple **\** blocks. Each **\** block is treated as a transaction. Each **\** block can have multiple **\** and **\** blocks. For example, if you are updating two of the existing records, you could specify two **\** and **\** pairs, one for each record being updated. ## Using the updg:id Attribute When multiple elements are specified in the **\** and **\** blocks, use the **updg:id** attribute to mark rows in the **\** and **\** blocks. The processing logic uses this information to determine what record in the **\** block pairs with what record in the **\** block. The **updg:id** attribute is not necessary (although recommended) if either of the following exists: - The elements in the specified mapping schema have the **sql:key-fields** attribute defined on them. - There is one or more specific value supplied for the key field(s) in the updategram. If either is the case, the updategram uses the key columns that are specified in the **sql:key-fields** to pair the elements in the **\** and **\** blocks. If the mapping schema does not identify key columns (by using **sql:key-fields**) or if the updategram is updating a key column value, you must specify **updg:id**. The records that are identified in the **\** and **\** blocks do not have to be in the same order. The **updg:id** attribute forces the association between the elements that are specified in the **\** and **\** blocks. If you specify one element in the **\** block and only one corresponding element in the **\** block, using **updg:id** is not necessary. However, it is recommended that you specify **updg:id** anyway to avoid ambiguity. ## Examples Before you use the updategram examples, note the following: - Most of the examples use default mapping (that is, no mapping schema is specified in the updategram). For more examples of updategrams that use mapping schemas, see [Specifying an Annotated Mapping Schema in an Updategram (SQLXML 4.0)](../../../relational-databases/sqlxml-annotated-xsd-schemas-xpath-queries/updategrams/specifying-an-annotated-mapping-schema-in-an-updategram-sqlxml-4-0.md). - Most of the examples use the AdventureWorks sample database. All the updates are applied to the tables in this database. You can restore the AdventureWorks database. ### A. Updating a record The following updategram updates the employee last name to Fuller in the Person.Contact table in the AdventureWorks database. The updategram does not specify any mapping schema; therefore, the updategram uses default mapping. ``` ``` The record described in the **\** block represents the current record in the database. The updategram uses all of the column values specified in the **\** block to search for the record. In this updategram, the **\** block provides only the ContactID column; therefore, the updategram uses only the value to search for the record. If you were to add the LastName value to this block, the updategram would use both the ContactID and LastName values to search. In this updategram, the **\** block provides only the LastName column value because this is the only value that is being changed. ##### To test the updategram 1. Copy the updategram template above and paste it into a text file. Save the file as UpdateLastName.xml. 2. Create and use the SQLXML 4.0 Test Script (Sqlxml4test.vbs) to execute the updategram. For more information, see [Using ADO to Execute SQLXML 4.0 Queries](../../../relational-databases/sqlxml/using-ado-to-execute-sqlxml-4-0-queries.md). ### B. Updating multiple records by using the updg:id attribute In this example, the updategram performs two updates on the HumanResources.Shift table in the AdventureWorks database: - It changes the name of the original day shift that starts at 7:00AM from "Day" to "Early Morning". - It inserts a new shift named "Late Morning" that starts at 10:00AM. In the updategram, the **updg:id** attribute creates associations between elements in the **\** and **\** blocks. ``` ``` Notice how the **updg:id** attribute pairs the first instance of the \ element in the **\** block with the second instance of the \ element in the **\** block. ##### To test the updategram 1. Copy the updategram template above and paste it into a text file. Save the file as UpdateMultipleRecords.xml. 2. Create and use the SQLXML 4.0 Test Script (Sqlxml4test.vbs) to execute the updategram. For more information, see [Using ADO to Execute SQLXML 4.0 Queries](../../../relational-databases/sqlxml/using-ado-to-execute-sqlxml-4-0-queries.md). ### C. Specifying multiple \ and \ blocks To avoid ambiguity, you can write the updategram in Example B by using multiple **\** and **\** block pairs. Specifying **\** and **\** pairs is one way of specifying multiple updates with a minimum of confusion. Also, if each of the **\** and **\** blocks specify at most one element, you do not have to use the **updg:id** attribute. > [!NOTE] > To form a pair, the **\** tag must immediately follow its corresponding **\** tag. In the following updategram, the first **\** and **\** pair updates the shift name for the day shift. The second pair inserts a new shift record. ``` ``` ##### To test the updategram 1. Copy the updategram template above and paste it into a text file. Save the file as UpdateMultipleBeforeAfter.xml. 2. Create and use the SQLXML 4.0 Test Script (Sqlxml4test.vbs) to execute the updategram. For more information, see [Using ADO to Execute SQLXML 4.0 Queries](../../../relational-databases/sqlxml/using-ado-to-execute-sqlxml-4-0-queries.md). ### D. Specifying multiple \ blocks You can specify multiple **\** blocks in an updategram. Each **\** block that is specified is an independent transaction. In the following updategram, the first **\** block updates a record in the Sales.Customer table. For the sake of simplicity, the updategram specifies only the required column values; the identity value (CustomerID) and the value being updated (SalesPersonID). The second **\** block adds two records to the Sales.SalesOrderHeader table. For this table, SalesOrderID is an IDENTITY-type column. Therefore, the updategram does not specify the value of SalesOrderID in each of the \ elements. Specifying multiple **\** blocks is useful because if the second **\** block (a transaction) fails to add records to Sales.SalesOrderHeader table, the first **\** block can still update the customer record in the Sales.Customer table. ``` ``` ##### To test the updategram 1. Copy the updategram template above and paste it into a text file. Save the file as UpdateMultipleSyncs.xml. 2. Create and use the SQLXML 4.0 Test Script (Sqlxml4test.vbs) to execute the updategram. For more information, see [Using ADO to Execute SQLXML 4.0 Queries](../../../relational-databases/sqlxml/using-ado-to-execute-sqlxml-4-0-queries.md). ### E. Using a mapping schema In this example, the updategram specifies a mapping schema by using the **mapping-schema** attribute. (There is no default mapping; that is, the mapping schema provides the necessary mapping of elements and attributes in the updategram to the database tables and columns.) The elements and attributes specified in the updategram refer to the elements and attributes in the mapping schema. The following XSD mapping schema has **\**, **\**, and **\** elements that map to the Sales.Customer, Sales.SalesOrderHeader, and Sales.SalesOrderDetail tables in the database. ``` ``` This mapping schema (UpdategramMappingSchema.xml) is specified in the following updategram. The updategram adds an order detail item in the Sales.SalesOrderDetail table for a specific order. The updategram includes nested elements: an **\** element nested inside an **\** element. The primary key/foreign key relationship between these two elements is specified in the mapping schema. ``` ``` ##### To test the updategram 1. Copy the mapping schema above and paste it into a text file. Save the file as UpdategramMappingSchema.xml. 2. Copy the updategram template above and paste it into a text file. Save the file as UpdateWithMappingSchema.xml in the same folder as was used to save the mapping schema (UpdategramMappingSchema.xml). 3. Create and use the SQLXML 4.0 Test Script (Sqlxml4test.vbs) to execute the updategram. For more information, see [Using ADO to Execute SQLXML 4.0 Queries](../../../relational-databases/sqlxml/using-ado-to-execute-sqlxml-4-0-queries.md). For more examples of updategrams that use mapping schemas, see [Specifying an Annotated Mapping Schema in an Updategram (SQLXML 4.0)](../../../relational-databases/sqlxml-annotated-xsd-schemas-xpath-queries/updategrams/specifying-an-annotated-mapping-schema-in-an-updategram-sqlxml-4-0.md). ### F. Using a mapping schema with IDREFS attributes This example illustrates how updategrams use the IDREFS attributes in the mapping schema to update records in multiple tables. For this example, assume that the database consists of the following tables: - Student(StudentID, LastName) - Course(CourseID, CourseName) - Enrollment(StudentID, CourseID) Because a student can enroll in many courses and a course can have many students, the third table, the Enrollment table, is required to represent this M:N relationship. The following XSD mapping schema provides an XML view of the tables by using the **\**, **\**, and **\** elements. The **IDREFS** attributes in the mapping schema specify the relationship between these elements. The **StudentIDList** attribute on the **\** element is an **IDREFS** type attribute that refers to the StudentID column in the Enrollment table. Likewise, the **EnrolledIn** attribute on the **\** element is an **IDREFS** type attribute that refers to the CourseID column in the Enrollment table. ``` ``` Whenever you specify this schema in an updategram and insert a record in the Course table, the updategram inserts a new course record in the Course table. If you specify one or more new student IDs for the StudentIDList attribute, the updategram also inserts a record in the Enrollment table for the each new student. The updategram ensures that no duplicates are added to the Enrollment table. ##### To test the updategram 1. Create these tables in the database that is specified in the virtual root: ``` CREATE TABLE Student(StudentID varchar(10) primary key, LastName varchar(25)) CREATE TABLE Course(CourseID varchar(10) primary key, CourseName varchar(25)) CREATE TABLE Enrollment(StudentID varchar(10) references Student(StudentID), CourseID varchar(10) references Course(CourseID)) ``` 2. Add this sample data: ``` INSERT INTO Student VALUES ('S1','Davoli') INSERT INTO Student VALUES ('S2','Fuller') INSERT INTO Course VALUES ('CS101', 'C Programming') INSERT INTO Course VALUES ('CS102', 'Understanding XML') INSERT INTO Enrollment VALUES ('S1', 'CS101') INSERT INTO Enrollment VALUES ('S1', 'CS102') ``` 3. Copy the mapping schema above and paste it into a text file. Save the file as SampleSchema.xml. 4. Save the updategram (SampleUpdategram) in the same folder used to save the mapping schema in the previous step. (This updategram drops a student with StudentID="1" from the CS102 course.) ``` ``` 5. Create and use the SQLXML 4.0 Test Script (Sqlxml4test.vbs) to execute the updategram. For more information, see [Using ADO to Execute SQLXML 4.0 Queries](../../../relational-databases/sqlxml/using-ado-to-execute-sqlxml-4-0-queries.md). 6. Save and execute the following updategram as described in the previous steps. The updategram adds the student with StudentID="1" back into the CS102 course by adding a record in the Enrollment table. ``` ``` 7. Save and execute this next updategram as described in the previous steps. This updategram inserts three new students and enrolls them in the CS101 course. Again, the IDREFS relationship inserts records in the Enrollment table. ``` ``` This is the equivalent XDR schema: ``` ``` For more examples of updategrams that use mapping schemas, see [Specifying an Annotated Mapping Schema in an Updategram (SQLXML 4.0)](../../../relational-databases/sqlxml-annotated-xsd-schemas-xpath-queries/updategrams/specifying-an-annotated-mapping-schema-in-an-updategram-sqlxml-4-0.md). ## See Also [Updategram Security Considerations (SQLXML 4.0)](../../../relational-databases/sqlxml-annotated-xsd-schemas-xpath-queries/security/updategram-security-considerations-sqlxml-4-0.md)