Share via


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

XML Data in Visual FoxPro

Reference

CURSORTOXML( ) Function

XMLTOCURSOR( ) Function

Other Resources

Functions