Compartir a través de

CURSORTOXML( ) Function

  • Artículo

Converts a Visual FoxPro cursor to XML.

CURSORTOXML(nWorkArea | cTableAlias, cOutput [, nOutputFormat 
[, nFlags [, nRecords [, cSchemaName [, cSchemaLocation [, cNameSpace ]]]]]])

Parameters

  • nWorkArea
    Specifies the work area of the table from which to create the XML string.

    If you specify 0 or no value, Visual FoxPro uses the current work area.

  • cTableAlias
    Specifies the alias of the table from which to create the XML string.

  • cOutput
    Specifies the path and file name or memory variable name to which results are sent.

    If nFlags is set to 0 (default) for memory variable output, XML is returned to the memory variable. If the memory variable does not exist, it is created.

    If nFlags is set to 512 for file output, and the file does not exist, it is created. If the file already exists, it is overwritten. The setting for SET SAFETY is observed.

  • nOutputFormat
    Specifies the output format of the XML string. The following table lists the values for nOutputFormat.

    nOuputFormat

    Description

    1 – ELEMENTS

    (Default) Element-centric XML

    2 – ATTRIBUTES

    Attribute-centric XML

    3 – RAW

    Generic, attribute-centric XML

  • nFlags
    Specifies the formatting of the XML that is produced and its destination. The following table lists the values for nFlags.

    nFlags

    Bit

    Output description

    0

    0000

    (Default) Produce XML in UTF-8 format.

    This setting creates a memory variable if one does not exist when specified by cOutput and returns XML to the memory variable.

    The XML declaration does not contain an Encoding= attribute; that is, no encoding attribute is set to UTF-8.

    1

    0001

    Produce unformatted XML as a continuous string.

    2

    0010

    Enclose empty elements with 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. Output is set to the cursor code page.

    To ensure accurate character translation, the Visual FoxPro default code page must match the code page of the cursor. You can accomplish this by setting character and memo fields in the cursor to NOCPTRAN (character binary/memo binary).

    When setting this value with tables using any of the code pages, the encoding attribute in the XML is set to an empty string (""). To change to the correct encoding attribute, use the STRTRAN( ) function.

    For example, for code page 936, provide the following to the resulting XML string:

    strxml=STRTRAN(strxml, 'encoding=""', 'encoding="gb2312"'

    32

    100000

    Output encoding.

    512

    1000000000

    Output to the file specified by cOutput.

    If a file does not exist, it is created. If the file already exists, it is overwritten. The setting for SET SAFETY is observed.

    4096

    1000000000000

    Disables base64 encoding.

    CURSORTOXML( ) exports Memo (Binary) fields as xsd:base64binary unless you use nFlags set to 4096. In Visual FoxPro, base64 encoding is meant for encoding only binary data.

    32768

    none

    Indicates that a code page should be used.

    The following table describes how the encoding attribute is written when output encoding defaults to the cursor or table code page.

    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 cursor code page.

    +32

    10

    Set output encoding attribute to UTF-8 with no character translation.

    +48

    11

    Set output encoding attribute to UTF-8 and translate character data to UTF-8.

    The following table lists common Windows-compatible code pages.

    Code page

    Platform

    Encoding attribute in XML Declaration

    Comments

    437

    MS-DOS, US

    ibm437

     

    850

    MS-DOS, International

    ibm850

     

    865

    MS-DOS, Nordic

    Empty string ("")

     

    866

    MS-DOS, Russian

    cp866

     

    932

    Windows, Japanese

    shift-jis

     

    936

    Simplified Chinese

    gb2312

     

    949

    Windows, Korean

    iso-2022-kr

    or:

    ks_c_5601-1987

    950

    Windows, Traditional Chinese (Taiwan)

    big5

     

    1250

    Windows, East European

    Windows-1250

    Note case.

    1251

    Windows, Russian

    Windows-1251

     

    1252

    Windows, U.S., West European

    Windows-1252

     

    1253

    Windows, Greek

    Windows-1253

     

    1254

    Windows, Turkish

    Windows-1254

     

    1255

    Windows, Hebrew

    Windows-1255

     

    1256

    Windows, Arabic

    Windows-1256

     

    Note

    Visual FoxPro uses Windows-1252 as the default encoding. You can specify that the encoding attribute be set to match the code page, such as Big5 (code page 950), when using double-byte character sets (DBCS) for DBCS languages for which Visual FoxPro supports code pages.

    When using Windows-1252 and DBCS, no additional character translation is required to display correctly in Internet Explorer.

    However, to make XML more compliant for Web browsers that can interpret UTF-8, you can optionally set the encoding attribute to UTF-8 instead of Windows-1252. The result set undergoes translation to UTF-8 characters only when you set nFlags to 48 (specify the encoding attribute as UTF-8 and translate character data to UTF-8 format). This is required only when the data actually contains double-byte characters. You do not have to use character translation, STRCONV ( ), for example, if you are outputting only Latin (single byte) characters.

  • nRecords
    Specifies the number of records to output to XML and has a default value is 0.

    If nRecords is 0, all records are output. If nRecords is greater than the number of records remaining in the table, all remaining records are output.

  • cSchemaName
    Specifies the name and location to contain schema information for the data in cOutput, for example "MySchema.xsd". If no extension is provided, the schema file is created with an .xsd extension.

    The following table lists the values for cSchemaName.

    cSchemaName

    Description

    cSchemaName

    Specifies the name and path of the external file for the schema (scoped to the root element of the XML).

    Note

    If cSchemaName contains a file name and cSchemaLocation is not provided or is blank, the contents of cSchemaName are written to the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute in the XML.

    In the following example, Visual FoxPro generates a generic XML file named MyXMLFile.xml from the Labels.dbf file in the "Labels" alias and the schema file named MySchema in the same folder.

    CURSORTOXML("LABELS", "myXMLFile.xml", 1, 512, 0, "mySchema.xsd")

    If cSchemaName includes a URI, the schema is written to the current directory and must be uploaded to the server to be accessed by the browser or parser. External schemas always are written to the same location as the XML file.

    "1"

    Specifies an inline schema is produced. For example, the following code produces an inline schema:

    CURSORTOXML("LABELS", "myXMLFile.xml", 1, 512, 0, "1")

    ""

    Specifies that no schema is produced.

  • cSchemaLocation
    Specifies an optional location where the application reading the XML data should look for the schema file.

    Note

    Use this parameter only when you are deploying your schema to a location other than the location of the XML data.

    The contents of cSchemaLocation are written to the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute of the XML data produced. The cschemaLocation parameter can be an HTTP address or other URI. You need to copy the schema file to the location you have specified in cSchemaLocation.

    The following example produces XML data:

       CURSORTOXML("LABELS", "myXMLFile.xml", 1, 512, 0, ;
       "mySchema.xsd", "https://www.microsoft.com/mySchema.xsd")

    containing the following attribute:

       xsi:noNamespaceSchemaLocation=" https://www.microsoft.com/mySchema.xsd"

    Specifying cSchemaLocation when cSchemaName is blank causes the same attributes to be written to the XML data. This makes it possible for you to point to an existing schema without recreating the schema each time CURSORTOXML( ) is called.

  • cNamespace
    Specifies the namespace of the XML or schema to be produced and has an empty string ("") as the default value.

    Specifying a value for cNameSpace sets the targetNamespace attribute to the same value and adds the elementFormDefault="qualified" attribute to the schema.

    If you do not specify a cNamespace value, and the schema is external, no namespace declaration is written to the schema. If you do not specify a cNamespace value and the schema is inline, the targetNamespace in the schema is set to an empty string ("").

Return Value

Numeric data type. CURSORTOXML( ) returns the number of bytes written to the file or a memory variable.

Remarks

You can use CURSORTOXML( ) 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 OLE DB Provider.

Note

To use the Visual FoxPro OLE DB Provider with CURSORTOXML( ), you must install MSXML 3.0 on the computer with the OLE DB Provider.

CURSORTOXML( ) output adheres to the cursor index order, SET FIELDS TO, and current filter settings. However, it does not preserve the cursor location. After the calling CURSORTOXML( ), if all records are output, the cursor record pointer reports EOF. If not all records are output, it points to the last record output to XML.

The resulting XML from CURSORTOXML( ) contains the same scale as the exported table if the table contains Double data type values. For example, if a Double column is created with a scale of 6 using the following codem the resulting XML contains six digits to the right of the decimal point:

CREATE TABLE test (col1 b(6))

When you use the CURSORTOXML( ) function to export a table or cursor to XML, the root node is always called "VFPData", regardless of the output format.

For Date types only, you can export "EMPTY" Date and DateTime types using CURSORTOXML( ). However, the XML schema validation might fail because "EMPTY" is not valid for these types in an XML schema definition (XSD) schema. This is an issue only if a schema is required, and the resulting XML is validated against an XML parser that can interpret XSD schemas. To work around this issue, you might need to change the data to a nonempty representation by calling the appropriate SELECT statement and use CURSORTOXML( ) on the created cursor. For example, you can change the empty Date or DateTime values to .NULL.:

SELECT orderid, EVL(shippeddate,.NULL.) as ShippedDate FROM orders

You can also change the empty Date or DateTime to an appropriate representation for "empty":

SELECT orderid, IIF(EMPTY(shippeddate),{^1899-12-30 00:00:00},tc11); 
   as ShippedDate FROM orders

When using flag 32768, the flags 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.

See Also

Concepts

Converting Between XML and Visual FoxPro Data

XML Data in Visual FoxPro

Reference

XMLUPDATEGRAM( ) Function

XMLTOCURSOR( ) Function

Other Resources

Functions