Share via

CURSORTOXML( ) Function

  • Article

Converts Visual FoxPro cursor to XML text.

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

Returns

Numeric. The number of bytes written to the file or memvar.

Parameters

  • nWorkArea
    Specifies the work area of the table from which to create the XML string. If you specify 0, or nothing, Visual FoxPro uses the current work area.

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

  • cOutput
    The path and name of the file or the name of the memvar to which results are sent. If nFlags is set for memvar output (the default), the XML is returned to the memvar. If the memvar does not exist, it will be created. If nFlags is set for file output (512), and the file does not exist, it will be created. If the file already exists, it will be overwritten. The SAFETY setting is observed.

  • nOutputFormat
    Specifies the output format of the XML string as in the following table:

    nOuputFormat Description
    1 – ELEMENTS Element-centric XML (default)
    2 – ATTRIBUTES Attribute-centric XML
    3 – RAW Generic, attribute-centric XML

  • nFlags
    Specifies the type of XML schema that is produced according to the following table:

    nFlag Bit Output Description
    0 0000 UTF-8 Formatted XML (default)
    1 0001 Unformatted (continuous string) XML
    2 0010 Empty elements written 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
    512 1000000000 cOutput is Filename. The default nFlag value, 0, creates a memory variable.

    Note   When Output Encoding is UTF-8 (the default), the XML Declaration will 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 & 5 (0010000).

    Encoding flag Bits 4 and 5 Description
    +0 00 Windows 1252 (default)
    +16 01 Output encoding attribute is set to the code page of the cursor
    +32 10 Output encoding attribute is set to UTF-8 - no character translation
    +48 11 Output encoding attribute is set to UTF-8 - characters data translated to UTF-8

    The following table lists common Windows-compatible code pages.

    Code Page Platform Encoding Attribute in XML Declaration Comments
    932 Japanese Windows shift-jis  
    949 Korean Windows iso-2022-kr or:

    ks_c_5601-1987
    950 Chinese (Taiwan) Windows big5  
    1250 East European Windows Windows-1250 note case
    1251 Russian Windows Windows-1251  
    1252 US, West European Windows Windows-1252  
    1253 Greek Windows Windows-1253  
    1254 Turkish Windows Windows-1254  
    1255 Hebrew Windows Windows-1255  
    1256 Arabic Windows Windows-1256  
    437 MS-DOS WINDOWS-1252  
    850 MS-DOS, Int Windows-1252  
    866 MS-DOS, Russian Windows-1251  
    865 MS-DOS, Nordic Windows-1252  

    Note   When using Code Page based encoding (traditional Visual FoxPro single byte or double byte character sets) such as Windows-1252 (code page 1252) or Big5 (code page 950), no additional character translation is required to display correctly in Internet Explorer.

    Note   When Output Encoding is set to UTF-8, the result set might optionally undergo character translation to the UTF-8 format. When there is no encoding attribute, the XML is assumed to be UTF-8, therefore it is not necessary (but might be desirable) to add the UTF-8 encoding attribute.

    Generally, for XML: If there is a byte order mark, the format is Unicode (LE or BE, depending on the BOM). If there is no encoding tag, the format is UTF-8. When Output Encoding is set to UTF-8 (the default), the result set must undergo character translation to the UTF-8 format. When there is no encoding attribute, the XML is assumed to be UTF-8, therefore it is not necessary (but might be desirable) to add the UTF-8 encoding attribute.

  • nRecords
    Specifies the number of records to output to XML. If nRecords is 0 (default), 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 of the schema information for the data in cFileName.

    cSchemaName Description
    "" Specifies that no schema will be produced
    "1" Specifies that an inline schema be produced
    <cSchemaName> Specifies the name and path of the external file to contain the schema (scoped to the root element of the XML)

    If cSchemaName contains a file name, and the cSchemaLocation parameter 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 code, Visual FoxPro generates a generic XML file, myxmlfile.xml, from labels.dbf in the "Labels" alias and the schema file, mySchema, in the same folder.

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

    If you specify "", instead of "mySchema," then no schema is produced; specifying "1," as in the following, produces an inline schema:

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

  • cSchemaLocation
    Specifies an optional location where the application reading the XML data should look for the schema file. The contents of cSchemaLocation are written to the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute of the XML data produced. Use this parameter only when you will be deploying your schema to a location other than the location of the XML data. The cschemaLocation can be an http address or other URI. You will need to copy the schema file to the location you have specified in cSchemaLocation.

    For example:

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

    will produce XML data containing the following attribute:

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

    If cSchemaName is blank, specifying cSchemaLocation will cause the same attributes to be written to the XML data. This allows you to point to an existing schema without recreating the schema each time CursorToXML is called.

  • cNamespace
    Specifies the name of the xml or schema to be produced. The empty string, "", is the default.

    If you specify no cNamespace parameter and the schema is external, then no namespace declaration is written to the schema. If you specify no cNamespace parameter and the schema is inline, then the targetNamespace in the schema is set to "", the empty string.

    If you specify cNameSpace, the targetNamespace attribute is set to the same value and the elementFormDefault="qualified" attribute are added to the schema.

Remarks

CursorToXML( ) output adheres to the cursor index order, SET FIELDS TO, and current filter settings. This function does not preserve the cursor location. After the call, the cursor record pointer will report EOF if all records are output, or will point to the last record output to XML if not all records were output.

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 schema always are written to the same location as the XML file.

When using single byte character sets, the default encoding, Windows-1252, requires no additional character translation to display correctly in Internet Explorer. Unicode and UTF-8 both require that the result set undergo character translation to the appropriate format and, if output to file is specified, that the corresponding Unicode or UTF-8 BOM (Byte Order Mark) be written to the file to designate the file type as Unicode or UTF-8.

See Also

Visual FoxPro and XML | XMLUpdateGram( ) Function | XMLTOCURSOR( ) Function