CursorToXML Function

Request Example View Source

Parameters

uArea (Optional)

Type: Usual
Specifies the work area number or alias of the table from which to create the XML string. If you specify 0 or no value, X# uses the current work area.

cOutput (Optional)

Type: Usual
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 (Optional)

Type: Usual
Specifies the output format of the XML string. The table in the remarks section lists the values for nOutputFormat.

nFlags (Optional)

Type: Usual
Specifies the formatting of the XML that is produced and its destination. The table in the remarks section lists the values for nFlags.

nRecords (Optional)

Type: Usual
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 (Optional)

Type: Usual
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 table in the remarks section lists the values for cSchemaName.

cSchemaLocation (Optional)

Type: Usual
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 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:

X#

Copy

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

containing the following attribute:

X#

Copy

1xsi:noNamespaceSchemaLocation=" http://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 (Optional)

Type: Usual

Return Value

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

You can use CURSORTOXML( ) with the OLE DB Provider for X#. However, the _VFPVFPXMLProgID property is not supported because the _VFP system variable is not supported in the OLE DB Provider.
To use the X# OLE DB Provider with CURSORTOXML( ), you must install MSXML 3.0 on the computer with the OLE DB Provider. 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: 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.: You can also change the empty Date or DateTime to an appropriate representation for "empty": 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. For XML documents written without setting the 32768 flag, the following code pages are applied. The following table describes how the encoding attribute is written when output encoding defaults to the cursor or table code page. The following table lists common Windows-compatible 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.