XMLUPDATEGRAM( ) Function
Mirrors changes made in a buffered table or cursor in an XML UpdateGram and returns a character string that contains the UpdateGram.
An XML UpdateGram represents the before and after conditions of the changed portion of a Visual FoxPro table or cursor. Through additional processes, you can use an UpdateGram to commit these changes to the data represented by the XML UpdateGram document.
Note
To use XMLUPDATEGRAM( ), you must use SET MULTILOCKS ON and enable table buffering.
Tip
Before calling XMLUPDATEGRAM( ), you should specify the key field list by calling CURSORSETPROP( ) with the KeyFieldList property against existing cursors and tables. If you do not specify key fields, both the before and after representations contains all the fields in the table. If you specify one or more key fields, only those fields appear in the before section.
XMLUPDATEGRAM( [ cAliasList [, nFlags [, cSchemaLocation]]])
Parameters
cAliasList
Specifies a comma-separated list of open tables or cursors, listed either by name or work area numbers in any combination, to include in the XML UpdateGram. If you specify no value or an empty string ("") for cAliasList, Visual FoxPro uses all open tables and cursors in the current data session that contain buffered changes.nFlags
Specifies whether to return a formatted file. The following table lists the additive flags for nFlags.nFlag
Bit
Output description
0
0000
(Default) Use UTF-8 formatted XML.
1
0001
Use unformatted, for example, continuous string XML.
2
0010
Enclose empty elements with both open and closing elements, for example, <cc04><cc04/>.
4
0100
Preserve white space in fields.
8
1000
Wrap Memo fields in CDATA sections.
16
10000
Output encoding.
32
100000
Output encoding.
32768
none
Indicates that a code page should be used.
Note
When output encoding is UTF-8 (default), the XML Declaration does not contain an Encoding= attribute (no encoding attribute = UTF-8).
When output encoding is set to default to the code page of the cursor or table, the encoding attribute will be written according to the following table.
Note
Encoding flags are set by combining bits 4 and 5 (0010000).
Encoding flag
Bits 4 and 5
Description
+0
00
(Default) Windows 1252
+16
01
Set output encoding attribute to the code page of the cursor.
+32
10
Set output encoding attribute to UTF-8 (no character translation).
+48
11
Set output encoding attribute to UTF-8 and translate double-byte characters to UTF-8.
cSchemaLocation
Specifies the name and location of the mapping schema, if it exists.Note
You must supply the mapping schema.
For example, suppose you pass the a schema called mySchema.xsd to cSchemaLocation, the UpdateGram created contains a mapping schema attirbute as it appears in the following XML:
<ROOT xmlns:updg="urn:schemas-microsoft-com:xml-updategram"> <updg:sync mapping-schema="mySchema.xsd" > <updg:before>
Return Value
Character data type. XMLUPDATEGRAM( ) returns a character string that contains the XML UpdateGram.
Remarks
You can use XMLUPDATEGRAM( ) with the OLE DB Provider for Visual FoxPro. However, the _VFP VFPXMLProgID property is not supported because the _VFP system variable is not supported in the OLD EB Provider.
Note
To use the Visual FoxPro OLE DB Provider with XMLUPDATEGRAM( ), you must install MSXML 3.0 on the computer with the OLE DB Provider.
SQL Server and Visual Studio support the DiffGram format for updating XML. However, SQL XML requires a mapping schema to support this format. Therefore, XMLUPDATEGRAM( ) does not support this format.
To avoid possible errors generated by XMLUPDATEGRAM( ) on tables containing Memo or General fields, use the CURSORSETPROP( ) function. The following example shows how to include memo data in an XML UpdateGram by setting the KeyFieldList property using CURSORSETPROP( ):
SET MULTILOCKS ON
CREATE CURSOR Test (mField M, cField I AUTOINC)
INSERT INTO Test (mField) VALUES ("123456789")
INSERT INTO Test (mField) VALUES ("23456789")
INSERT INTO Test (mField) VALUES ("3456789")
INSERT INTO Test (mField) VALUES ("456789")
CURSORSETPROP("Buffering",5)
CURSORSETPROP("keyfieldlist",'cField')
UPDATE Test SET mField = "XXXXXXX" WHERE cField < 3
STRTOFILE(XMLUPDATEGRAM(),'xmlupdate.txt')
MODIFY FILE xmlupdate.txt
RETURN
To write memo data in the XML UpdateGram to SQL Server, you must use an explicit schema on the SQL Server and reference the schema in the XML UpdateGram.
Unlike the CURSORTOXML( ) function, XMLUPDATEGRAM( ) disregards SET FIELDS statements and reads from the underlying cursor directly. To change the table structure before calling XMLUPDATEGRAM( ), you must copy the data into a new cursor. For example, to change a Numeric field to a Currency field, the following example uses a SQL SELECT statement to create a new cursor and uses that cursor with XMLUPDATEGRAM( ). The example makes the Total_Price field a currency field, enables buffering with CURSORSETPROP( ), adds sales tax with the REPLACE command, and creates an XML UpdateGram using the XMLUPDATEGRAM( ) function.
SELECT OrderID, CustID, NTOM(Total_Price) as Total_Price;
FROM Orders INTO CURSOR New_Orders READWRITE
CURSORSETPROP("Buffering", 5, "New_Orders")
REPLACE Total_Price WITH (Total_Price * 1.083)
cXMLUpdg = XMLUPDATEGRAM("New_Orders")
When using flag 32768, the flag's 16 and 32 settings can affect which code page is applied depending on the type of data you are writing to XML. The following tables show the possible combinations of settings and the code page each combination applies.
For XML documents written with the 32768 flag set, the following code pages are applied.
Flag 16 |
Flag 32 |
Flag 32768 is Set |
Not set |
Not set |
XML documents: Window-1252. Unicode data: code page 1252. Character data: default code page, unless a field is marked as NOCPTRANS. |
True (.T) |
Not set |
XML documents: Plus-CodePage property of the cursor. If XMLField CodePage property is greater than zero (0) and it doesn’t match the cursor’s code page, an error is reported. Unicode data: the Code page property of the cursor object. Character data: none. Raw data from the Visual FoxPro tables (.dbf) are used instead. |
Not set |
Set |
XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: Default code page unless field is marked as NOCPTRANS, in which case no additional character translation to UTF-8 occurs. |
Set |
Set |
XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless a field is marked as NOCPTRANS, in which case the data are translated to UTF-8 using the SYS(3005) setting. |
For XML documents written without setting the 32768 flag, the following code pages are applied.
Flag 16 |
Flag 32 |
Without the 32768 flag |
Not set |
Not set |
XML documents: Window-1252. Unicode data: code page 1252. Character data: default code page unless a field is marked as NOCPTRANS. |
True (.T) |
Not set |
XML documents: CodePage property of the cursor. Character data: none. Raw data from the Visual FoxPro tables (.dbf) are used instead. Unicode data: code page property of the cursor object. |
Not set |
Set |
XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless field is marked as NOCPTRANS, in which case no additional character translation to UTF-8 occurs. |
Set |
Set |
XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless field is marked as NOCPTRANS, in which case, they are translated to UTF-8 using code page for the current SYS(3005) setting. |
For more information about converting XML to Visual FoxPro data, see Converting Between XML and Visual FoxPro Data.
See Also
Concepts
Converting Between XML and Visual FoxPro Data