Partager via

XMLUPDATEGRAM( ) Function

  • Article

Mirrors changes made in a buffered table or cursor in an XML UpdateGram and returns a character string that contains the UpdateGram. To use XMLUPDATEGRAM( ), you must use SET MULTILOCKS ON and enable table buffering.

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.

SQL Server and Visual Studio .NET support the DiffGram format for updating XML. SQL XML requires mapping schema to support this format. Therefore, XMLUPDATEGRAM( ) does not support this format.

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 Use UTF-8 formatted XML (Default)
    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

    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 Windows 1252 (Default)
    +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 Values

Character data type. XMLUPDATEGRAM( ) returns a character string that contains the XML UpdateGram.

Remarks

Before calling XMLUPDATEGRAM( ), you should specify the key field list by calling CURSORSETPROP( ) with a KeyFieldList clause 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. To avoid possible errors generated by XMLUPDATEGRAM( ) on tables containing Memo or General fields, use the CURSORSETPROP( ) function.

To include memo data in the XML UpdateGram, set the KeyFieldList property using CURSORSETPROP( ) as shown in the following example:

SET MULTILOCKS ON
CREATE CURSOR Test (mField M, cField C(10))
APPEND BLANK
CUSORSETPROP("Buffering",5)
CUSORSETPROP("keyfieldlist",'cfield')
Value = REPLICATE('x ',500)
REPLACE mField WITH mValue, cField WITH "Test"
? XMLUPDATEGRAM()
RETURN

You must use an explicit schema on the SQL Server and reference the schema in the XML UpdateGram to write memo data in the XML UpdateGram to SQL Server.

Unlike the CURSORTOXML( ) function, XMLUPDATEGRAM( ) disregards SET FIELDS statements and reads from the underlying cursor directly. If you want 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, you can use the following SQL SELECT statement to create a new cursor, then use that cursor with XMLUPDATEGRAM( ) as in the following example for showing context:

* Make Total_Price a currency field.
SELECT OrderID, CustID, NTOM(Total_Price) as Total_Price;
      FROM Orders INTO CURSOR New_Orders READWRITE 
   CURSORSETPROP("Buffering", 5, "New_Orders")      && Enable buffering.
   REPLACE Total_Price WITH (Total_Price * 1.083)   && Add sales tax.
   cXMLUpdg = XMLUPDATEGRAM("New_Orders")      && Create XML UpdateGram.

See Also

CURSORTOXML( ) Function | XMLTOCURSOR( ) Function | CURSORSETPROP( ) Function