Описание XML-функций в Visual FoxPro

Функция

CURSORTOXML(nWorkArea | cTableAlias, cOutput [, nOutputFormat
[, nFlags [, nRecords [, cSchemaName

 [, cSchemaLocation [, cNameSpace]]]]]])

преобразовывает курсор VFP, заданный параметром nWorkArea | cTableAlias, в XML-документ. В качестве курсора может быть указана любая таблица VFP.

Функция возвращает число байт, записанных в файл или в хранящую результат переменную.

Параметры:

cOutput – строка, содержащая имя файла или имя переменной, в которую записывается результат. Если параметр nFlags = 0 или опущен, то результат присваивается переменной. Если переменная с указанным именем не существует, то она будет создана.

Если nFlags = 512, то результат направляется в файл. Если файл не существует, то он будет создан. Если существует, то перезаписан. Установка SET SAFETY анализируется.

nOutputFormat – формат XML-строки (табл. 20.4).

Таблица 20.4

Значения параметра nOutputFormat

nFlags – определяет способ форматирования XML-документа и вид результата (в виде файла или переменной). Задается как сумма указанных в табл. 20.5 флагов.

Таблица 20.5

Значения для параметра nFlags

В табл. 20.6 показано, как записывается атрибут encoding, когда результат имеет ту же кодовую страницу, что и курсор или таблица VFP.

Таблица 20.6

Значения параметра nFlags

В табл. 20.7 приводятся Windows-совместимые кодовые страницы и соответствующие им значения атрибута encoding.

Таблица 20.7

Соответствия Windows-совместимых кодовых страницы
и значений XML-атрибута encoding

nRecords – число записей, передаваемых результату. Если параметр опущен или равен нулю, или больше числа имеющихся в таблице записей, то передаются все записи.

cSchemaName – задает имя и положение информации о схеме. Принимает приведенные в табл. 20.8 значения.

Таблица 20.8

Значения параметра cSchemaName

Если параметр cSchemaLocation опущен или задан в виде пустой строки, а параметр cSchemaName содержит имя файла, то значение cSchemaName записывается в XML-атрибут xsi:SchemaLocation или xsi:noNamespaceSchemaLocation.

Примеры:

CursorToXML("Labels", "MyXMLFile.xml", 1, 512, 0, "MySchema.xsd")

CursorToXML("Labels", "MyXMLFile.xml", 1, 512, 0, "1")

Если в cSchemaName включен URI (Uniform Resource Identifier – унифицированный идентификатор ресурса), то схема записывается в текущую директорию и должна быть передана серверу, чтобы стать доступной браузеру или синтаксическому анализатору. Внешняя схема всегда записывается с то же место, что и XML-файл.

cSchemaLocation – задает адрес, по которому приложение, читающее XML-документ, должно искать файл со схемой. Параметр используется, когда схема и XML-файл имеют разное расположение.

Значение cSchemaLocation записывается в XML-атрибут xsi:SchemaLocation или xsi:noNamespaceSchemaLocation XML-файла с данными. Параметр cSchemaLocation может быть HTTP-адресом или другим URI-значением. Необходимо скопировать файл со схемой по адресу, указанному параметром cSchemaLocation.

Пример. Выполнение функции

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

вызовет появление XML-файла, содержащего следующий атрибут:

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

Задание cSchemaLocation при пустом значении cSchemaName приведет к появлению того же атрибута в XML-файле. Это позволяет указывать на существующую схему без ее повторной генерации при неоднократных вызовах CURSORTOXML( ) для одного и того же курсора (таблицы).

cNamespace – задает пространство имен XML или формируемую схему. По умолчанию равен пустой строке.

Задание параметра cNameSpace устанавливает в атрибут targetNamespace значение параметра и добавляет в схему атрибут elementFormDefault="qualified".

Если параметр cNamespace не задан и генерируется внешняя схема, то декларация пространства имен в схеме будет отсутствовать; если же схема встроенная, то в атрибут targetNamespace будет установлена строка нулевой длины.

Функция CURSORTOXML( ) соблюдает установки SET ORDER, SET FIELDS и SET FILTER. После выполнения функции курсор позиционируется в конце файла, если выгружены все записи, или на последней выгруженной записи.

Независимо от формата данных корневой элемент всегда имеет имя "VFPData".

Результирующий XML в случае полей типа Double содержит ту же точность, что и поле таблицы типа Double.

В случае полей типа Date и DateTime можно выгружать пустые значения. Однако при проверке схемы может возникнуть ошибка, поскольку пустое значение не является допустимым для таких типов (эта проблема актуальна, когда требуется схема и XML-документ проверяется XML-синтаксическим анализатором, интерпретирующим схему).

Чтобы избежать этой проблемы, можно использовать подходящий SELECT – SQL для формирования курсора и затем употребить с ним CURSORTOXML( ). Например, можно заменить пустые даты на NULL, например:

select OrderId, Evl(ShippedDate, .NULL.) as ShippedDate from Orders

Также можно заменить пустую дату некоторой фиктивной величиной, например:

select OrderId, Iif(Empty(ShippedDate), {^1899–12–30 00:00:00}, ShippedDate) ;
    as ShippedDate from Orders

Функция

XMLTOCURSOR(eExpression | cXMLFile [, cCursorName [, nFlags]])

преобразовывает XML-документ, заданный параметром eExpression | cXMLFile, в курсор или таблицу VFP.

Функция возвращает число созданных записей.

Параметры:

eExpression – корректный XML-текст. Параметр может быть переменной VFP, memo-полем, либо результатом HTTP-запроса, выполнения SOAP-метода, XMLDOM или ADO-потока. XMLCURSOR( ) генерирует ошибку, если XML-документ не найден или если eExpression не проходит синтаксический контроль.

cXMLFile – имя XML-файла.

cCursorName – имя курсора для записи результата. Если курсор уже существует и открыт, то VFP закрывает курсор и затем создает новый в неиспользуемой рабочей области. Если параметр опущен или задан в виде пустой строки, то VFP создаст курсор с именем XMLResult.

Если nFlags = 8192 и если курсор cCursorName содержит данные, VFP добавляет импортируемые данные в существующий курсор или таблицу. Курсор (таблица) должен быть открыт. Если cCursorName – это пустая строка и nFlags = 8192, то VFP импортирует данные в курсор или таблицу, открытую в текущей рабочей области.

nFlags – определяет, как eExpression обрабатывается XMLTOCURSOR( ). Задается как сумма приведенных в табл. 20.9 флагов.

Таблица 20.9

Значения для параметра nFlags

Используя флаг 8192, необходимо принимать во внимание следующее:

Схема таблицы (курсора) должна отвечать поступающим XML-элементам; VFP согласовывает типы данных в соответствии с табл. 20.11. Импортирование несогласуемых типов данных приводит к генерации ошибки.

Если XML содержит ссылку на схему и типы данных в схеме конфликтуют с типами данных курсора (таблицы), то берутся типы данных курсора (таблицы).

Имена элементов XML-данных должны соответствовать именам столбцов курсора (таблицы). VFP импортирует данные только тех элементов, для которых выполняется приведенное условие.

Курсор (таблица) может иметь меньше столбцов, чем предусмотрено XML-файлом, но должен иметь по крайней мере один столбец, отвечающий XML-данным; может также содержать произвольное число столбцов, не имеющих соответствующих XML-элементов.

Если таблица содержит поля типа Integer (AutoInc), функция XMLTOCURSOR( ) не будет выполнена, если SET AUTOINCERROR установлен в ON. Установка SET AUTOINCERROR в OFF или отключение режима автоматического увеличения значения поля посредством функции CURSORSETPROP( ) позволяет выполнить XMLTOCURSOR( ).

VFP интерпретирует XML-данные со схемой или без нее. Схема используется для определения структуры таблицы. Схема берется либо как внутренняя из XML-файла, либо из внешнего файла. Если схемы нет, то импортирование выполняется за 2 прохода.

Символы длиной 2 байта правильно интерпретируется при импортировании данных из XML-файла. Если же источником XML-данных является переменная или строка, то для правильной интерпретации 2-байтовых символов следует применить функцию STRCONV( ), например как в следующем примере:

close databases all

use Home( ) + 'Samples\Data\Customer'

CursorToXML('Customer', 'lcXML', 1, 48, 5, "", "", "")

&& XMLTOCURSOR( ) помещает некорректные символы в результирующий курсор

XMLToCursor(lcXML, "curCustomerList", 4)

&& Используем STRCONV( ) в XMLTOCURSOR( ) для правильного

&& преобразования 2-байтовых символов

XMLToCursor(STRConv(lcXML, 11), "curCustomerList", 4)

browse last

Функция XMLTOCURSOR( ) не выполняет автоматического преобразования XML-строк, например, из ANSI в UTF-8. (Преобразование будет выполнено при чтении XML-данных из файла.) Чтобы выполнить преобразование XML-строки, следует употребить STRCONV( ).

Пример. При исполнении следующего кода синтаксический XML-анализатор генерирует ошибку в момент обнаружения первого ASCII-символа

close database all

use Home(2) + "\Data\Customer"

CursorToXML("Customer", "lcXML", 1, 32)

STRToFile(lcXML, "Customer.xml")

XMLToCursor("Customer.xml", "curCustomer", 512)

Ее можно предотвратить, выполнив функцией STRCONV( ) преобразование XML-строки в UTF-8 при ее записи в файл.

close database all

use Home(2) + "\Data\Customer"

CursorToXML("Customer", "lcXML", 1, 32)

STRToFile(STRConv(lcXML, 9), "Customer.xml")

XMLToCursor("Customer.xml", "curCustomer", 512)

browse last

При вызове XMLTOCURSOR( ) в режиме добавления записей VFP добавит пустую запись, если не будет найдено ни одного соответствующего столбца таблицы или курсора.

XMLTOCURSOR( ) генерирует ошибку, если число столбцов в XML-строке превышает допустимое значение, которое примерно равно 160. Его точная величина зависит от длины имен столбцов.

XMLTOCURSOR( ), создавая курсор, не использует тип Varchar, но поддерживает добавление данных в существующий с Varchar-полями.

XML-документы, имеющие внутреннюю XSD-схему, сгенерированную Visual Studio .NET DataSets, могут содержать элементы, не поддерживаемые VFP, например:

xs:unique name;

xs:annotation;

дополнительные инструкции и атрибуты, такие, как:

- поддержка префикса (например msdata:Prefix);

- атрибут msprop и другие использующие пространство имен атрибуты;

- другие атрибуты msdata, ссылающиеся на значения, не распознаваемые VFP, например msdata:Locale или msdata:Comment.

Такие элементы игнорируются.

Соответствие VFP- и XSD-типов данных описано в табл. 20.10.

Таблица 20.10

Соответствие типов данных VFP и XSD

В табл. 20.11 описан порядок согласования типов данных при nFlags = 8192.

Таблица 20.11

Порядок согласования типов данных при nFlags = 8192

Замечание. Если XML-числовые данные содержат индикатор переполнения, например *****.**, то XMLTOCURSOR( ), если имеется схема, при импортировании такого значения заменяет его в зависимости от типа поля на 0.0 или 0.

Функция

XMLUPDATEGRAM([cAliasList [, nFlags [, cSchemaLocation]]])

отображает изменения, выполненные в буферизованной таблице, в XML UpdateGram.

Функция возвращает строку, содержащую значение XML UpdateGram.

XML UpdateGram содержит представления полей буферизованной таблицы или курсора до и после изменения.

Для употребления функции XMLUPDATEGRAM( ) необходимо установить SET MULTILOCKS в ON и активизировать буферизацию таблиц.

Пример. Создается курсор Test, устанавливаются его свойства, изменяются значения его полей mField, cField и iField и вызывается XMLUpdateGram( ).

set multiLocks on

set memoWidth to 80

create cursor Test (mField M, cField C(20), iField I)

append blank

CursorSetProp("Buffering", 5)

CursorSetProp("KeyFieldList", "cField")

replace mField with "Новое M-значение", ;

cField with "Новое C-значение" ;

iField with 5

? XMLUpdateGram( )

Результат, возвращаемый функцией XMLUPDATEGRAM( ):

<?xml version = "1.0" encoding="Windows-1252" standalone="yes"?>

<root xmlns:updg="urn:schemas-microsoft-com:xml-updategram">

<updg:sync>

<updg:before>

<test>

<mfield/>

<cfield/>

<ifield>0</ifield>

</test>

</updg:before>

<updg:after>

<test>

<mfield>Новое M-значение</mfield>

<cfield>Новое C-значение</cfield>

<ifield>5</ifield>

</test>

</updg:after>

  </updg:sync>

</root>

Замечание. Если опустить вызов

CursorSetProp("KeyFieldList", "cField")

то XMLUPDATEGRAM( ) вернет результат только для полей cField и iField; memo-поле mField в результат не попадет.

Параметры:

cAliasList – список, содержащий разделенные запятыми имена псевдонимов или номера рабочих областей открытых таблиц и курсоров, включаемых в UpdateGram. Если параметр опущен или задан в виде строки нулевой длины, то VFP использует все открытые таблицы и курсоры текущей сессии данных, содержащие буферизованные изменения.

nFlags – определяет способ форматирования результата. Задается как сумма приведенных в табл. 20.12 флагов.

Таблица 20.12

Значения для параметра nFlags

В табл. 20.12 также показано, как записывается атрибут encoding, когда результат имеет ту же кодовую страницу, что и курсор или таблица VFP.

cSchemaLocation – имя и место размещения схемы.

Пример. Пусть для cSchemaLocation использовано значение "mySchema.xsd", тогда значение UpdateGram будет содержать mapping-schema-атрибут, такой же, что и приведенный в следующем фрагменте XML:

<root xmlns:updg="urn:schemas-microsoft-com:xml-updategram">
    <updg:sync mapping-schema="mySchema.xsd">
        <updg:before>

Перед вызовом XMLUPDATEGRAM( ) следует создать список первичных полей для всех открытых курсоров и таблиц, употребив CURSORSETPROP( ) с первым параметром равным "KeyFieldList". При его отсутствии memo-данные в XML UpdateGram включены не будут (см. вышеприведенный пример).

При работе с SQL Server необходимо явно указывать схему, чтобы передать SQL Server memo-данные XML UpdateGram.

XMLUPDATEGRAM( ) не поддерживает формат DiffGram, употребляемый в SQL Server и Visual Studio .NET для XML.

В отличие от CURSORTOXML( ) функция XMLUPDATEGRAM( ) игнорирует установки SET FIELDS.