Click or drag to resize

XmlUpdatefram Function

X#
-- todo --
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 Note
To use XMLUpdateGRAM( ), you must use Set MultiLocks ON and enable table buffering.
Note 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.19
Syntax
 FUNCTION XmlUpdatefram(
	cAliasList,
	nFlags,
	cSchemaLocation
) AS STRING CLIPPER
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 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:
X#
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 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( ):
X#
 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.
X#
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 16Flag 32Flag 32768 is Set
Not setNot 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 setSet 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.
SetSet 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 16Flag 32Without the 32768 flag
Not setNot 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 setSet 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.
SetSet 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.
nFlagBitOutput description
00000(Default) Use UTF-8 formatted XML.
10001Use unformatted, for example, continuous string XML.
20010Enclose empty elements with both open and closing elements, for example, <cc04><cc04/>.
40100Preserve white space in fields.
81000Wrap Memo fields in CDATA sections.
1610000Output encoding.
32100000Output encoding.
32768noneIndicates that a code page should be used.
Note 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 Note
Encoding flags are set by combining bits 4 and 5 (0010000).
Encoding flagBits 4 and 5Description
+000(Default) Windows 1252
+1601Set output encoding attribute to the code page of the cursor.
+3210Set output encoding attribute to UTF-8 (no character translation).
+4811Set output encoding attribute to UTF-8 and translate double-byte characters to UTF-8.
See Also