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 X# 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.

Note
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.

Namespace: XSharp.VFP
Assembly: XSharp.VFP (in XSharp.VFP.dll) Version: 2.21

Syntax

Copy

 FUNCTION XmlUpdatefram(
	cAliasList,
	nFlags,
	cSchemaLocation
) AS STRING CLIPPER

[ClipperCallingConventionAttribute(new string[] { ... })]
public static string XmlUpdatefram(
	Usual cAliasList = default,
	Usual nFlags = default,
	Usual cSchemaLocation = default
)

Request Example View Source

Parameters

cAliasList (Optional)

Type: Usual
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, X# uses all open tables and cursors in the current data session that contain buffered changes.

nFlags (Optional)

Type: Usual
Specifies whether to return a formatted file. The table in the remarks section lists the additive flags for nFlags.

cSchemaLocation (Optional)

Type: Usual
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:

Copy

1<ROOT xmlns:updg="urn:schemas-microsoft-com:xml-updategram">
2<updg:sync mapping-schema="mySchema.xsd" >
3<updg:before>

Return Value

Type: String
Character data type. XMLUpdateGRAM( ) returns a character string that contains the XML UpdateGram.

Remarks

You can use XMLUpdateGRAM( ) with the OLE DB Provider for X#. However, the _VFPVFPXMLProgID property is not supported because the _VFP system variable is not supported in the OLD EB Provider.

Note
To use the X# 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( ):

Copy

 1Set MultiLocks ON
 2Create CURSOR Test (mField M, cField I AutoInc)
 3Insert Into Test (mField) VALUES ("123456789")
 4Insert Into Test (mField) VALUES ("23456789")
 5Insert Into Test (mField) VALUES ("3456789")
 6Insert Into Test (mField) VALUES ("456789")
 7CursorSetProp("Buffering",5)
 8CursorSetProp("keyfieldlist",'cField')
 9Update Test Set mField = "XXXXXXX" Where cField < 3
10StrToFile(XMLUpdateGRAM(),'xmlupdate.txt')
11MODIFY FILE xmlupdate.txt
12RETURN

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.

Copy

1Select OrderID, CustID, NTOM(Total_Price) as Total_Price;
2From Orders Into CURSOR New_Orders READWRITE
3CursorSetProp("Buffering", 5, "New_Orders")
4Replace Total_Price WITH (Total_Price * 1.083)
5cXMLUpdg = 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 X# 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 X# 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 X# data, see Converting Between XML and X# Data.

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.

Reference

Functions, Globals and Defines

XSharp.VFP Namespace