RSComProvider

Материал из RSB-Doc
Перейти к: навигация, поиск

Содержание

Поле

Interface: IRSCOMField->IRSCOMItem->IDispatch

Coclass: RSCOMField

Описание

Представляет собой интерфейс работы с полем в объекте или ключе. Поля могут быть связанными и свободными. В первом случае интерфейс поля получается при обращении к коллекции полей объекта или ключа. Во втором случае — создается с помощью объекта-фабрики классов свободных полей.

Все возможные поля типа объекта, а также связь полей и ключей фиксированы в описании типа объекта (TypeInfo), которую можно посмотреть с помощью утилиты «Редактор метаданных» (RSTypeInfoEditor.exe).

Поля бывают двух видов: обычные поля и поля-ссылки. Обычные поля представляют собой некоторые именованные атомарные свойства объектов, значения которых относятся к одному из встроенных типов. Примером обычных полей является поле «Идентификатор» (типа FT_Int32), «Наименование» (типа FT_String(100)), «Дата создания» (типа FT_Date) и т. д.

Поля-ссылки позволяют объекту ссылаться на данные другого объекта, организовывать связи между объектами. При этом коллекция полей для ссылающегося типа объекта содержит поле типа FT_Int32, которое ссылается на идентификатор другого типа объекта. В экземпляре объекта значение этого поля будет либо FT_Null, либо 0, либо будет равно идентификатору существующего объекта.

Связи между объектами бывают четырех видов:

  1. Ссылки на глобальные объекты (связь типа «классификатор»). Под «глобальным» имеется в виду самостоятельный тип объекта, не подобъект. Ссылки этого вида могут задаваться как из глобальных объектов, так и из подобъектов. Например, объект документа может ссылаться на глобальный объект «Валюта», используя поле с именем «Валюта оплаты». Значение этого поля для данного документа будет идентификатором определенной валюты.
  2. Ссылка из подобъекта на основной объект (связь типа «первичный контекст»). Подобъекты являются не самостоятельными сущностями, они могу существовать только в контексте основного, самостоятельного объекта. Этот контекст («первичный» для подобъекта, в отличие от возможных «вторичных» контекстов — см. п.3) должен быть задан для всех подобъектов и представляет собой поле-ссылку на идентификатор первичного объекта.
  3. Ссылки между подобъектами (связь типа «контекст»). Один подобъект может ссылаться на другой подобъект того же объекта. Это позволяет получить данные одного подобъекта в контексте другого через коллекцию подобъектов. Например, в гипотетическом объекте «Договор» есть подобъекты «Участники» и «Обязательства». Из коллекции подобъектов договора можно получить всех его участников и все обязательства по данному договору. Если же в подобъекте «Обязательство» задать поле-ссылке на подобъект «Участник», то можно будет получить обязательства только данного участника, обратившись к коллекции подобъектов подобъекта «Участник»:dsContract.SubObjects(«Участник»), dsContract.SubObjects(«Обязательство»), dsContract.SubObjects(«Участник»).SubObjects(«Обязательство»)
  4. Ссылка на родительский объект в дереве (связь типа «родитель»). В иерархически организованных объектах представляет собой поле-ссылку на идентификатор родителя.

Используя поля-ссылки типа «классификатор», «контекст» и «первичный контекст» можно обращаться к полям объекта, на который ссылается это поле. Для этого нужно к имени поля-ссылки добавить имя поля в объекте-ссылке через символ «\». Например, используя поле типа «Валюта оплаты» в гипотетическом примере, можно обращаться к полям объекта «Валюта» (допустим, у объекта «Валюта» есть поле с именем «Код ISO» и «Краткое наименование»):

dsContract.Fields(«Валюта оплаты\Код ISO»)

dsContract.Fields(«Валюта оплаты\Краткое наименование»)

В результате этих вызовов будет получен интерфейс IRSCOMField для соответствующих полей, в котором можно будет узнать значение этого поля, его тип, флаги и прочее. Отметим, что если используемый язык трактует символ «\» как escape-последовательность (например, «C», «C++» или «JScript»), этот символ необходимо продублировать.

Помимо типа связи, ссылки делятся по уровню вложенности. Это разделение справедливо только для типов связи «классификатор» и «контекст». В этом случае различаются ссылки первого уровня (первичные ссылки) и ссылки второго, третьего и т. д. уровней. Первичная ссылка — это поле в коллекции исходного объекта, содержащее ссылку типа «классификатор» или «контекст». Ссылка второго уровня появится в случае, если поле объекта-ссылки, которое указано в составном имени поля через символ «\» в свою очередь является ссылкой. Если продолжать предыдущий пример и предположить, что некоторый объект ссылается на объект «Договор» посредством поля «Ссылка на договор», возможна следующая запись: dsObject.Fields(«Ссылка на договор\Валюта\Код ISO»)

В примере с контекстными ссылками, возможны следующие записи для подобъекта «Обязательсвто»: dsLiability.Fields(«Участник\Контрагент\Город\Наименование»)

Из этого примера видно, что ссылки типа «классификатор» и «контекст» могут быть произвольного уровня вложенности. Важно, что для того, чтобы иметь возможность обращаться к полям классфикаторов и контекстов необходимо, чтобы эти поля были явно запрошены в ConnectString объекта.

Свойства

RSName. Имя поля.

Возвращает имя поля в соответствии с описанием типа объекта (см. TypeInfo). Попытка задать имя поля через это свойство приведет к ошибке «Функция не реализована». Имена полей классификаторов и контекстов пишутся через «\», например «Валюта\Код ISO».

Type. Тип поля.

Возвращает тип поля (типа long) в соответствии с описанием типа объекта (см. TypeInfo). Попытка задать тип поля через это свойство приведет к ошибке «Функция не реализована». Список всех типов полей и соответствующих им типов VARIANT см. в п. Value. Значения для типов указаны в таблице в скобках рядом с графическим именем типа, которое показывается в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

Number. Порядковый номер.

Возвращает порядковый номер поля в конкретном объекте. Для свободных полей не имеет смысла. Порядковые номера полей задаются в описании объекта посредством свойства ConnectString. Попытка задать номер поля через это свойство приведет к ошибке «Функция не реализована».

Owner. Владелец.

Возвращает указатель на IDispatch владельца объекта. Для связанных полей это IDispatch либо объекта, либо ключа, в зависимости от того, из какой коллекции получено поле. Для свободных полей это NULL.

Flags. Флаги.

Возвращает флаги поля в соответствии с описанием типа объекта (см. Описание флагов TypeInfo для полей).

DefaultValue. Значение по умолчанию

Возвращает значение по умолчанию для поля

Value. Значение поля.

Чтение/запись значения поля. Для системных и встроенных типов используются следующие соответствия:

RS-Тип(EfieldType_t) MS-Тип (VARIANT) Комментарии
FT_Null(0) VT_NULL,VT_EMPTY,VT_VOID Значение поля не задано. FT_Null преобразуется в VT_EMPTY.
FT_Int8(1) VT_I1, VT_UI1 FT_Int8 преобразуется в VT_I1.
FT_Int16(2) VT_I2, VT_UI2 FT_Int16 преобразуется в VT_I2.
FT_Int32(3) VT_I4, VT_UI4, VT_INT, VT_UINT, VT_HRESULT FT_Int32 преобразуется в VT_I4.
FT_Int64(4) VT_I8, VT_UI8 FT_Int64 преобразуется в VT_I8.
FT_Char(5) VT_BSTR Одиночный символ преобразуется в строку.
FT_String(6) VT_BSTR -
FT_GUID(7) VT_BSTR Все GUID’ы конвертируются в строку и распознаются из строк.
FT_Date(8) VT_DATE -
FT_Blob(9) VT_UNKNOWN, VT_DISPATCH Двоичные данные читаются из IPersistStreamInit, IPersistStream и IStream. Если входной параметр не поддерживает ни одного из этих интерфейсов, возвращается ошибка «несоответствие типов». При чтении значения всегда возвращается указатель на IStream (внутренняя реализация).
FT_Decimal(10) VT_DECIMAL -
FT_Money(11) VT_CY -
FT_Bool(12) VT_BOOL Наш логический тип имеет размер 1 байт и считается равным «истине», если он отличен от 0 и «лжи», если он равен 0. При чтении/записи значения он преобразуется в VARIANT_TRUE (-1) и VARIANT_FALSE (0) соответственно.
FT_Enum(13) VT_I2 Цифровое значение перечислителя обычно малоинформативно. Для получения строкового значения используется свойство String.
FT_Real4(14) VT_R4 -
FT_Real8(15) VT_R8 -
FT_IfPtr(16) VT_UNKNOWN, VT_DISPATCH Преобразование из VT_UNKNOWN и VT_DISPATCH в FT_IfPtr возможно только для некоторых объектов RSCOMProvider. Для прочих объектов вернется ошибка «несоответствие типов». Встроенные объекты распознаются по интерфейсу IRSIfPtr, который умеет вернуть через QueryInterface СОМ объекты модуля RSCOMProvider. При обратном преобразовании всегда возвращается VT_DISPATCH.

Получить значение можно у любого поля из коллекции полей. При этом, если значение не задано, вернется пустой VARIANT (VT_EMPTY). В объекте и в связанном ключе задать значение можно только для тех полей, у которых свойство ReadOnly возвращает VARIANT_FALSE. В случае свободного ключа или свободных полей флаг ReadOnly не имеет смысла.

Если объект находится в некорректной позиции, попытка чтения/записи значения поля объекта приведет к соответствующей ошибке (BOF или EOF). В этом же случае, для любого поля связанного ключа вернется пустое значение (VT_EMPTY), то есть ошибка возвращаться не будет.

Для полей-ссылок Value имеет тип VT_I4 (FT_Int32) и представляет собой идентификатор объекта, на который ссылается данное поле. В этом случае значение поля будет либо VT_EMPTY (ссылка не задана и не задавалась), либо 0 (ссылка явно «сброшена»), либо целым числом (ссылка на существующий объект). При изменении значения поля-ссылки необходимо устанавливать значение идентификатора существующего объекта. Если объект с данным идентификатором не найден, вызов put_Value вернет ошибку «классификатор не найден».

Если поле имеет тип FT_Blob, свойство Value вернет VARIANT типа VT_UNKNOWN с указателем на интерфейс IStream. Вызывая методы этого интерфейса можно напрямую работать с двоичными данными, при этом все изменения будут сохраняться в объекте. Прямой доступ можно было бы реализовать и проще, через SAFEARRAY байтов. В этом случае тип значения был бы VT_ARRAY| VT_UI1. Однако этого не было сделано именно для того, чтобы не поощрять такой доступ по следующим причинам. Система использует тип FT_Blob для хранения файлов (например, текста и приложения договора, файла отчета и т. п.) и больших строк (например, текст макроса). И в том, и в другом случае удобнее работать с файлами и строками, а не с двоичным буфером. Для этих целей был написан отдельный COM-объект — RSBlobDriver.

Каждый раз при установке значения поля будет происходить преобразование из устанавливаемого значения к типу поля. Если это преобразование невозможно, вернется ошибка «несоответствие типов».

String. Строковое значение.

Строковое значение используется в двух случаях:

  1. если нужно преобразование значения поля (см. Value) из строки/в строку (например, при чтении/записи значения поля из EditBox);
  2. для получения строкового значения перечисляемого поля. Во втором случае, если значение перечислителя не задано, вернется пустая строка.

В обоих случаях строковое значение можно не только прочесть, но и задать.

Size. Количество символов.

Для строковых полей (типа FT_String) возвращает максимально допустимое число символов. Для остальных типов не имеет смысла. Для связанных полей это свойство доступно только для чтения и определяется TypeInfo объекта. Свойство на запись предусмотрено для свободных полей.

ReadOnly. Флаг «Нередактируемое».

Если этот флаг установлен в VARIANT_TRUE, значение поля (свойство Value) изменить нельзя. При попытке задать значения поля будет выдана ошибка «Поле доступно только для чтения». Для связанных полей это свойство определяется TypeInfo объекта.

Нередактируемыми считаются поля, в описании которых установлены флаги TI_READONLY, TI_TIMESTAMP, TI_HASCHILD и TI_CONTEXT_PRIMARY. В первом случае разработчик явно указал, что значение поля ме6нять нежелательно. Однако эту установку можно отменить, задав свойство ReadOnly поля в VARIANT_FALSE. Отметим, что отмена этого флага устранит проверки на клиентской стороне. Проверки на серверной стороне останутся без изменений.

Во всех остальных случаях, значения полей заполняются автоматически и снять флаг «только для чтения» не удастся, то есть установка свойства ReadOnly в VARIANT_FALSE не возымеет никакого эффекта. Кроме того, в связанных полях нередактируемыми считаются поля-идентификаторы, поля-ссылки на родителя в дереве в случае, если объект открыт в режиме «дерево» и вообще все поля, если весь объект доступен только для чтения. В этом случае, сбросить свойство ReadOnly в VARIANT_FALSE также не удастся.

System. Флаг «Системное».

Системные поля задаются в описании типа объекта разработчиками. Удалять такие поля, а также менять описание таких полей могут только разработчики. Это свойство доступно только для чтения и определяется TypeInfo объекта.

Required. Флаг «Обязательное».

Если этот флаг установлен, то для сохранения объекта на сервере требуется задать значение (см. Value) этого поля. Для связанных полей это свойство определяется TypeInfo объекта. Этот флаг можно сбросить, задав свойству Required значение VARIANT_FALSE. Отметим, что отмена этого флага устранит проверки на клиентской стороне. Проверки на серверной стороне останутся без изменений.

ActiveContext. Ссылка на активный контекст.

Для полей контекстных ссылок возвращает VARIANT_TRUE, если подобъект находится в данный момент в контексте другого подобъекта. В примере с обязательствами и участниками договора, если обязательства запрошены в контексте участников, поле-ссылка на участника в обязательстве станет активным контекстом.

Code. Код в базе данных.

Для связанных полей возвращает имя колонки в таблице, в которой хранится значение поля объекта. Если объект не хранится на сервере, возвращается пустая строка. Это свойство доступно только для чтения и определяется TypeInfo объекта.

ClassGUID. GUID классификатора.

Для полей-ссылок возвращает идентификатор (GUID) типа объекта, на который настроена ссылка. Идентификатор представляется строкой. Это свойство доступно только для чтения и определяется TypeInfo объекта.

ClassName. Наименование классификатора.

Для полей-ссылок возвращает наименование типа объекта, на который настроена ссылка. Это свойство доступно только для чтения и определяется TypeInfo объекта.

Методы

Reset. Сбросить значение.

Устанавливает для поля значение по умолчанию. Метод возвращает прежнее значение поля (см. Value). Значение по умолчанию задается в описании типа объекта (см. TypeInfo).

Classifier. Объект-классификатор.

Для полей-ссылок возвращает интерфейс объекта, на который установлена ссылка. Для прочих полей вернет NULL. Название «классификатор» обобщенное: это свойство работает как для связи типа «классификатор», так и для связи типа «контекст». Если параметр bSynchronize равен VARIANT_TRUE, объект-классификатор будет синхронизирован с текущим значением поля, то есть текущая позиция в нем будет соответствовать тому идентификатору, который хранится в поле-ссылке. Отметим, что в случае полей-ссылок на классификаторы объект классификатора будет создан заново по тем полям, которые были указаны в ConnectString исходного объекта. В случае с контекстными ссылками, объект создаваться не будет — он будет взят из коллекции подобъектов основного объекта.

ClassField. Поле-ссылка.

Для полей из объекта-ссылки возвращает интерфейс поля первичной ссылки. Для прочих полей вернет NULL. Например, значения свойства ClassField для поля «Валюта оплаты» и «Валюта оплаты\Код ISO» представляют собой интерфейс поля «Валюта оплаты». Для ссылок более высокого уровня это будет уже не так. Например, для поля «Участник\Контрагент\Город\Наименование» значение свойства ClassField равно «Участник\Контрагент\Город», для которого, в свою очередь, первичной ссылкой является поле «Участник\Контрагент», для которого первичной ссылкой будет поле «Участник», для которого первичной ссылкой будет оно само — поле «Учаcтник».

RootClassField.

Для полей-ссылок любого уровня возвращает интерфейс поля первичной ссылки. Например, для полей «Участник\Контрагент\Город\Наименование», «Участник\Контрагент\Город», «Участник\Контрагент» и «Участник» метод RootClassField вернет интерфейс поля "Участник, потому что именно оно является первичной ссылкой в исходном объекте.

GetEnumFieldValues. Значения перечислителя.

Для перечисляемых полей возвращает SAFEARRAY всех возможных для данного типа перечисления пар «целое — строка». Нижняя граница этого массива равна 0. Пара представляет собой также SAFEARRAY (от 0 до 1), в котором первый элемент — целочисленный VARIANT (типа VT_I2), второй — строковый VARIANT (типа VT_BSTR). Для неперечисляемых полей возвращается пустой массив.

ValueFromXmlFile(FilePath)

Установить содержимое XML-файла как значение

Коллекция полей

Interface: IRSCOMFieldsCollection->IDispatch

Coclass: RSCOMFieldsCollection

Описание

Интерфейс коллекции полей объекта или ключа. Интерфейс возвращается только при обращении к соответствующим свойствам в интерфейсе объекта или ключа. Все возможные поля, которые могут войти в коллекцию объекта, описаны в информации типа объекта (см. TypeInfo). При создании конкретного объекта можно указать подмножество этих полей и определить их порядок (см. ConnectString).

Свойства

Count. Размер.

Возвращает количество полей в коллекции. Доступно только для чтения.

Type. Тип.

Возвращает RSFIELDSCOLLECTION_TYPE (0x80000000). Служебная информация, используется для преобразования указателей на внутренние служебные интерфейсы в указатели на IDispatch. Попытка задать значение этого свойства приведет к ошибке «Функция не реализована».

Owner. Владелец.

Возвращает указатель на IDispatch объекта или ключа, в зависимости от того, чья коллекция.

Методы

Item. Поле по имени/номеру.

По имени поля или его порядковому номеру, возвращает интерфейс поля. В первом случае тип параметра Index должен быть VT_BSTR (можно VT_BYREF), во втором — VT_I2, VT_UI2, VT_I4 или VT_UI4 (также можно VT_BYREF). В противном случае вернется ошибка «Некорректный параметр». Порядок полей в коллекции определяется описанием конкретного объекта — ConnectString.

Ключ

Interface: IRSCOMKey->IRSCOMItem->IDispatch

Coclass: RSCOMKey

Описание

Ключи позволяют получать данные объекта по значению ключевых полей с помощью метода GetData. Ключи бывают связанными и свободными. Первые возвращаются через интерфейс коллекции ключей объекта, вторые — создаются с помощью coclass’а RSCOMKey или метода Clone. Значения полей связанных ключей берутся из текущей позиции в наборе записей объекта. Если текущая запись находится в BOF или EOF, при попытке чтения значений связанного ключа вернется пустое значение (VT_EMPTY), то есть ошибка в этом случае возвращаться не будет.

Описание всех возможных ключей объекта определяется его TypeInfo (информацией типа), которую можно посмотреть с помощью утилиты «Редактор метаданных» (RSTypeInfoEditor.exe).

Свойства

RSName. Имя ключа.

Возвращает имя ключа в соответствии с описанием типа объекта (см. TypeInfo). Попытка задать имя связанного ключа через это свойство приведет к ошибке «Функция не реализована». Для свободного ключа имя задать можно. При этом состав полей ключа изменится в соответствии с новым именем, а буфер значений полей ключа очистится.

Type. Тип.

Возвращает RSKEY_TYPE (0x00020000). Служебная информация, используется для преобразования указателей на внутренние служебные интерфейсы в указатели на IDispatch. Попытка задать значение этого свойства приведет к ошибке «Функция не реализована».

Number. Порядковый номер.

Возвращает порядковый номер ключа в соответствии с описанием типа объекта (см. TypeInfo). Попытка задать значение этого свойства для связанного ключа приведет к ошибке «Несовместимый режим работы». Для свободного ключа порядковый номер можно изменить. При этом очистится буфер значений полей ключа, а состав полей изменится в соответствие с новым номером.

Owner. Владелец.

Для связанного ключа возвращает указатель на IDispatch объекта. Для свободного ключа, всегда возвращает NULL.

Flags. Флаги.

Возвращает флаги ключа в соответствии с описанием типа объекта (см. TypeInfo). Попытка задать флаги поля через это свойство приведет к ошибке «Функция не реализована». Для ключей имеют смысл следующие флаги:

Fields. Коллекция полей.

Возвращает интерфейс коллекции полей ключа. Для связанных ключей, значения полей в коллекции берутся из текущей позиции в наборе записей объекта. Для свободных ключей — из буфера данных ключа.

ObjectGUID. GUID типа объекта.

Ключи не существуют сами по себе, они привязаны к типу объекта. Это свойство возвращает GUID типа (в виде строки), для которого определен данный ключ. Поменять идентификатор типа для связанных ключей нельзя (вернется ошибка «Несовместимый режим работы»). Для свободных ключей установить значение этого свойства — один из способов привязать ключ к типу. После смены типа для свободного ключа, очищается буфер значений его полей.

ObjectName. Наименование типа объекта.

Задавать привязку ключа к типу по GUID’у этого типа неудобно. Это свойство определяет наименование типа, к которому привязан ключ. Как и для свойства ObjectGUID, менять значение ObjectName можно только для свободных ключей.

Методы

Clone. Клонировать ключ.

Метод возвращает указатель на интерфейс свободного ключа, созданного по данному ключу. Клонированный ключ будет иметь тот же набор полей и те же свойства ObjectGUID и ObjectName. Необязательный параметр KeyTag определяет, какой именно ключ нужно создать. По умолчанию (если параметр не задан) новый свободный ключ является копией данного ключа. В качестве KeyTag можно передать либо наименование, либо порядковый номер ключа из описания типа объекта (см. TypeInfo). Таким образом, можно получать одни ключи по другим, например, альтернативные ключи по первичному и наоборот: если первоначально был первичный ключ, а при клонировании был указан номер или наименование альтернативного ключа, то в результате клонирования будет создан альтернативный ключ для того же типа объекта, причем, если в первичном ключе было задано значение идентификатора, то в альтернативном ключе будут заполнены значения полей, соответствующие этому идентификатору. Для связанных ключей значения при преобразовании берутся из текущей записи. Если тип ключа при клонировании не меняется, значения ключевых полей просто копируются. Если источником клонирования является связанный ключ и при этом объект находится в некорректной позиции, значения нового свободного ключа будут пустыми (VT_EMPTY).

CopyFrom. Копировать ключ.

Метод работает только для свободных ключей. Для связанных ключей вызов приведет к ошибке «Несовместимый режим работы». Ключ-источник может быть как свободным, так и связанным, может принадлежать другому типу (иметь другой номер в коллекции ключей) может быть привязан к другому объекту того же типа или даже к другому типу объекта. Функционально, Clone и CopyFrom отличаются тем, что Clone создает новый свободный ключ, а CopyFrom — нет. Если источником копирования является связанный ключ и при этом объект находится в некорректной позиции, значения свободного ключа будут пустыми (VT_EMPTY).

Коллекция ключей

Interface: IRSCOMKeyCollection->IDispatch

Coclass: RSCOMKeyCollection

Описание

Интерфейс коллекции ключей объекта. Состав ключей в коллекциях задан в описании типа объекта (см. TypeInfo).

Свойства

Count. Размер.

Возвращает количество ключей в коллекции. Доступно только для чтения.

Type. Тип.

Возвращает RSKEYSCOLLECTION_TYPE (0x80020000). Служебная информация, используется для преобразования указателей на внутренние служебные интерфейсы в указатели на IDispatch. Попытка задать значение этого свойства приведет к ошибке «Функция не реализована».

Owner. Владелец.

Возвращает указатель на IDispatch объекта.

Методы

Item. Ключ по имени/номеру.

По имени ключа или его порядковому номеру, возвращает интерфейс ключа. В первом случае тип параметра Index должен быть VT_BSTR (можно VT_BYREF), во втором — VT_I2, VT_UI2, VT_I4 или VT_UI4 (также можно VT_BYREF). В противном случае вернется ошибка «Некорректный параметр».

Закладка

Interface: IRSCOMBookmark->IRSCOMItem->IDispatch

Coclass: RSCOMBookmark

Описание

Закладки существуют для того, чтобы запоминать позиции в наборе записей объекта и сохранять вместе с каждой позицией некоторую дополнительную информацию. В дальнейшем можно осуществлять быстрое перемещение по закладкам, используя дополнительную информацию для выполнения каких-либо действий. Позиция запоминается путем клонирования первичного ключа текущей записи.

Интерфейс закладки можно получить из коллекции закладок.

Свойства

RSName.

Имена для закладок не используются, поэтому это свойство всегда равно пустой строке. Попытка задать значение для RSName приведет к ошибке «Функция не реализована».

Type. Тип.

Возвращает RSBOOKMARK_TYPE (0x00090000). Служебная информация, используется для преобразования указателей на внутренние служебные интерфейсы в указатели на IDispatch. Попытка задать значение этого свойства приведет к ошибке «Функция не реализована».

Number.

Возвращает значение идентификатора отмеченной записи или 0, если закладка установлена в BOF или EOF. Попытка задать значения этого свойства приведет к ошибке «Функция не реализована».

Owner. Владелец.

Возвращает указатель на IDispatch объекта.

Flags. Флаги.

Не имеет смысла для закладок и всегда возвращает 0.

Key. Ключ.

Возвращает указатель на интерфейс первичного ключа записи, на которой стоит закладка.

Params. Параметры.

Позволяет сохранить и считывать дополнительную информацию для отмеченной записи. Если данных много, можно использовать SAFEARRAY. При этом будет запоминаться нижняя граница этого массива, чтобы сохранить индексацию. Если сохранялся скалярный параметр, то и возвращаться будет скалярный тип.

Коллекция закладок

Interface: IRSCOMBookmarksCollection->IDispatch

Coclass: RSCOMBookmarksCollection

Описание

Интерфейс коллекции закладок хранит информацию по всем закладкам для набора записей, позволяет устанавливать/снимать закладки, перемещаться по закладкам, проверять, отмечена ли закладкой произвольная запись и т. п. Все закладки упорядочены в соответствии с текущей сортировкой в объекте. Смена условий сортировки может привести к переупорядочиванию закладок.

Указатель на интерфейс закладок возвращается свойством Bookmarks в интерфейсе объекта.

Свойства

Count. Размер.

Возвращает количество всех установленных закладок. Доступно только для чтения.

Type. Тип.

Возвращает RSBOOKMARKSCOLLECTION_TYPE (0x80090000). Служебная информация, используется для преобразования указателей на внутренние служебные интерфейсы в указатели на IDispatch. Попытка задать значение этого свойства приведет к ошибке «Функция не реализована».

Owner. Владелец.

Возвращает указатель на IDispatch объекта.

Методы

Item. Закладка по индексу.

По индексу закладки (индекс изменяется от 1 до Count) возвращает ее интерфейс. Индекс может быть только целочисленным, так как у закладки нет наименования. Если тип параметра Index не равен VT_I2, VT_UI2, VT_I4 и VT_UI4, вернется ошибка «Некорректный параметр».

MarkRow. Установить/снять закладку.

Первый вызов этого метода для записи установит, второй — снимет закладку. Нужная запись задается с помощью указателя на интерфейс ключа. По умолчанию этот параметр равен NULL, в этом случае помечается текущая запись. Ключ может быть любой, необязательно первичный. Установить закладку можно только на корректную запись. Попытка поместить закладку в BOF или EOF приведет к соответствующим ошибкам.

ClearAll. Удалить все закладки.

Удаляет все закладки из коллекции.

MoveNext. Переместиться к следующей/предыдущей закладке.

Параметр bDown определяет направление перемещения: если bDown равно VARIANT_TRUE, то ищется следующая закладка, если VARIANT_FALSE — предыдущая. Если закладка найдена (текущая запись установлена на закладку), метод возвращает VARIANT_TRUE, в противном случае — VARIANT_FALSE. Закладки упорядочиваются в соответствии с текущей сортировкой. Если помимо сортировки на набор записей установлен фильтр и следующая закладка не подходит под это условие, ищется следующая подходящая запись.

IsRowMarked. Проверяет, есть ли закладка на записи.

Если на указанной записи установлена закладка, возвращает VARIANT_TRUE, в противном случае — VARIANT_FALSE. Нужная запись задается с помощью указателя на интерфейс ключа. По умолчанию этот параметр равен NULL, в этом случае происходит проверка текущей записи. Ключ может быть любой, необязательно первичный.

GetRowMark. Возвращает закладку для указанной записи.

Если на указанной записи установлена закладка, возвращает VARIANT_TRUE и указатель на интерфейс закладки в параметре ppMark, в противном случае — VARIANT_FALSE и NULL в ppMark. Нужная запись задается с помощью указателя на интерфейс ключа. По умолчанию этот параметр равен NULL, в этом случае происходит проверка текущей записи. Ключ может быть любой, необязательно первичный.

Сессия

Interface: IRSCOMSession->IRSCOMItem->IDispatch

Coclass: RSCOMSession

Описание

Сессия представляет собой соединение с сервером. Каждая новая сессия устанавливает новое соединение с сервером. Сессия хранит целое 32-битное число — описатель соединения с сервером (client handle). В интерфейсе сессии можно прочитать этот описатель с помощью свойства Handle. Для разных объектов сессии значение этого свойства будет разным.

Все объекты создаются в рамках какой-либо сессии. Сессии можно создавать явно (с помощью coclass RSCOMSession) либо неявно использовать сессию по умолчанию. Сессия по умолчанию создается в том случае, когда при обращении к интерфейсу сервера сессия явно не указана.

Пример создания объекта «Пользователь» с использованием сессии по умолчанию (JScript):

var oDS = new ActiveXObject("RSCOMProvider.RSCOMObject");
oDS.ConnectString = "<object><name>Пользователь</name>"
                  +   "<field>Наименование</field>"
                  + "</object>";
var oFldName = oDS.Fields("Наименование");
if ( oDS.Run("GetFirst") ) do
{
  WScript.Echo( "Пользователь:\t" + oFldName.Value );
}
while ( oDS.Run("GetNext") );

В этом примере, если с данным потоком не была связана ни одна сессия, неявно будет создана сессия по умолчанию при задании XML-описания объекта с помощью свойства ConnectString в интерфейсе объекта-источника данных. Пример создания того же объекта с помощью явно созданной сессии (JScript):

var oSession = new ActiveXObject("RSCOMProvider.RSCOMSession");
var oDS = oSession.CreateObject(
                    "<object><name>Пользователь</name>"
                  +   "<field>Наименование</field>"
                  + "</object>" );
var oFldName = oDS.Fields("Наименование");
if ( oDS.Run("GetFirst") ) do
{
  WScript.Echo( "Пользователь:\t" + oFldName.Value );
}
while ( oDS.Run("GetNext") );

Помимо объектов на сервере, с помощью сессии можно создавать динамические объекты. Это объекты, метаданные которых не хранятся постоянно на сервере, а создаются динамически для каких-либо временных целей (например, при формировании параметров отчета). Динамические объекты создаются методом CreateDynamicObject.

Сессия может быть связана с некоторым потоком выполнения. Это может понадобиться для того, чтобы все новые объекты в том же потоке создавались в рамках этой сессии (естественно, если при создании объекта сессия не была указана явно). Таким образом, связанная сессия станет сессией по умолчанию для данного потока. Ясно, что для каждого потока можно задать только одну такую сессию.

Связать сессию с потоком можно с помощью метода SetForThread. Получить сессию по умолчанию для данного потока можно с помощью метода GetForThread.

Первоначально, сессия по умолчанию связана со всеми потоками, отсюда и ее название — она является сессией по умолчанию во всех потоках. Все объекты создаются в рамках этой сессии. Если создать некоторую сессию и связать ее с потоком, эта сессия станет сессией по умолчанию для выбранного потока.

В сессии хранится информация о последней ошибке в работе объектов-источников данных. Любой вызов функции СОМ интерфейса модуля RSCOMProvider приводит к изменению этой информации (кроме, естественно, методов получения информации об ошибке). При возникновении ошибки выполнение метода прерывается, и информация об ошибке сохраняется в сессии. При этом информация о предыдущей ошибке сбрасывается. Из этого следует, что информацию о последней ошибке следует проверять после каждого вызова метода некоторого СОМ интерфейса модуля RSCOMProvider. Однако для этого необязательно использовать интерфейс сессии (см. замечание).

Отметим отличие объекта сессии RSCOMSession от объекта параметров соединения RSCOMConnection. Сессия представляет собой фактическое соединение с RPC-сервером. RSCOMConnection лишь задает параметры этого соединения — имя пользователя, пароль, имя сервера (Для HTTP соединения указывается URL, например: http://217.174.99.202:2000). Эти параметры можно изменять пока нет фактического соединения с сервером, то есть пока не создана ни одна сессия. Как только создается хотя бы одна сессия с данными параметрами, их уже нельзя менять.

Свойства

RSName.

У сессии нет имени, поэтому это свойство всегда равно пустой строке. Попытка задать значение для RSName приведет к ошибке «Функция не реализована».

Type. Тип.

Возвращает RSSESSION_TYPE (0x00060000). Служебная информация, используется для преобразования указателей на внутренние служебные интерфейсы в указатели на IDispatch. Попытка задать значение этого свойства приведет к ошибке «Функция не реализована».

Number. Номер.

Сессия по умолчанию всегда имеет номер 1. Все явно созданные сессии получают номер больший 1. Попытка задать значения этого свойства приведет к ошибке «Функция не реализована».

Owner. Владелец.

У сессии нет владельца, поэтому чтение этого свойства вернет NULL. Попытка задать значения этого свойства приведет к ошибке «Функция не реализована».

Flags. Флаги.

Флаги для сессии не определены, поэтому чтение этого свойства вернет 0. Попытка задать значения этого свойства приведет к ошибке «Функция не реализована».

Handle. Описатель.

Описатель соединения клиента с сервером. Всегда отличен от 0 и уникален для каждой сессии.

LastError. Код последней ошибки.

Числовой код последней ошибки в работе источников данных. Список всех ошибок, разбитых по группам, можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

LastErrorMessage. Сообщение о последней ошибке.

Информационное сообщение о последней ошибке в работе источников данных. Сообщение содержит краткое описание ошибки, предназначенное как для разработчика, так и для пользователя. Список всех ошибок, разбитых по группам, можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

LastErrorInfo. Дополнительная информация о последней ошибке.

Дополнительная информация обычно содержит конкретные сведения об объектах-источниках данных, в которых произошла ошибка. Эта информация затем используется для того, чтобы уточнить стандартное сообщение об ошибке. Например, общее сообщение об ошибке: «В объекте „%s“ нет поля с номером „%s“.» преобразуется в более конкретное: «В объекте „Договор. Участник“ нет поля с номером „112“.» В ошибках синтаксического разбора (например, условий фильтра) дополнительной информацией служит позиция, в которой обнаружена ошибка.

Методы

GetErrorMessage. Получить сообщение по коду ошибки.

Метод позволяет получить информационное сообщение для ошибки с указанным кодом. Здесь имеются в виду только ошибки, определенные в инструменте и прикладных подсистемах. Эта функция-справочник для ошибок программного комплекса.

SetForThread. Установить сессию по умолчанию для потока.

Сессия по умолчанию — это сессия, в которой будут создаваться объекты для данного потока с помощью свойства ConnectString интерфейса объекта. Метод связывает данную сессию с потоком, который задан идентификатором THREADID (для этого входной параметр типа VARIANT преобразуется в VT_I4). Если идентификатор потока не задан, сессия связывается с текущим потоком.

Например:

 var oSession = new ActiveXObject("RSCOMProvider.RSCOMSession");
 oSession.SetForThread();
 
 // Теперь все объекты, которые создаются без явного указания
 // сессии, будут создаваться в рамках сессии oSession
 
 // Например, объект "Пользователь"
 var oDS = new ActiveXObject("RSCOMProvider.RSCOMObject");
 oDS.ConnectString = "<object><name>Пользователь</name>"
                   +   "<field>Наименование</field>"
                   + "</object>";
 var oFldName = oDS.Fields("Наименование");
 if ( oDS.Run("GetFirst") ) do
 {
   WScript.Echo( "Пользователь:\t" + oFldName.Value );
 }
 while ( oDS.Run("GetNext") );

GetForThread. Получить сессию, связанную с данным потоком.

Метод запишет в текущий объект сессии сессию по умолчанию для данного потока. Поток определяется единственным входным параметром — идентификатором потока THREADID (для этого входной параметр типа VARIANT преобразуется в VT_I4). Если идентификатор потока не задан, возвращается сессия по умолчанию для текущего потока.

Например:

 var oSession = new ActiveXObject("RSCOMProvider.RSCOMSession");
 oSession.GetForThread();
 // Теперь объект oSession представляет собой сессию по умолчанию 
 // для данного потока (если ни одной сессии еще не было создано,
 // будет создана сессия по умолчанию и сохранена в oSession)
 
 var oDS = oSession.CreateObject(
                     "<object><name>Пользователь</name>"
                   +   "<field>Наименование</field>"
                   + "</object>" );
 var oFldName = oDS.Fields("Наименование");
 if ( oDS.Run("GetFirst") ) do
 {
   WScript.Echo( "Пользователь:\t" + oFldName.Value );
 }
 while ( oDS.Run("GetNext") );

CreateObject. Создать новый объект на сервере.

Метод создает объект, описание метаданных которого хранится на сервере. Единственный параметр метода — строка описания объекта, аналогичная по формату свойству ConnectString интерфейса объекта-источника данных. Созданный объект передается в возвращаемом значении метода.

 var oSession = new ActiveXObject("RSCOMProvider.RSCOMSession");
 var oDS = oSession.CreateObject(
                     "<object><name>Пользователь</name>"
                   +   "<field>Наименование</field>"
                   + "</object>" );
 var oFldName = oDS.Fields("Наименование");
 if ( oDS.Run("GetFirst") ) do
 {
   WScript.Echo( "Пользователь:\t" + oFldName.Value );
 }
 while ( oDS.Run("GetNext") );

CreateDynamicObject. Создать новый динамический объект.

Метод создает объект, описание метаданных которого не хранится на сервере. В связи с этим первый параметр метода (типа BSTR) представляет собой XML-описание типа объекта. Второй параметр задает описание объекта и аналогичен по формату свойству ConnectString интерфейса объекта-источника данных. Созданный объект передается в возвращаемом значении метода.

В описании типа можно не указывать его атрибуты, например идентификатор (GUID), имя, модуль, флаги, таблицу в базе, кодировку и назначение. Кроме того, можно не указывать методы (будут добавлены все стандартные методы).

Пример создания динамического объекта, содержащего одно поле «Код» типа FT_String и поле-ссылку на объект типа «Валюта» (JScript):

 // Получаем сессию для данного потока
 var oSession = new ActiveXObject("RSComProvider.RSCOMSession");
 oSession.GetForThread();
 
 // Создаем динамический объект со строковым кодом и ссылкой на валюту
 var oDS = oSession.CreateDynamicObject(
   // Описание типа объекта
   "<object>"
  +  "<Field Number = '1' Name = 'Идентификатор' Type = 'FT_Int32' "
  +   "Flags = '0x13'/>"
  +  "<Field Number = '2' Name = 'Код' Type = 'FT_String' "
  +   "Size = '10' Flags = '0x1'/>"
  +  "<Field Number = '3' Name = 'Валюта' Type = 'FT_Int32' "
  +    "Flags = '0x203' "
  +    "RefObjTypeGUID = '2E65D62B-D904-4BC6-B18A-99111BD2E093'/>"
  +  "<Key Number = '1' Name = 'Первичный' Flags = '0'>"
  +    "<KeyField Number = '1'/>"
  +  "</Key>"
  +"</object>",
 
   // описание объекта
   "<object all_fields='yes'\>" 
  +  "<name>Test</name>"
  +  "<classifier><name>Валюта</name>"
  +    "<field>Буквенный код</field>"
  +    "<field>Род (целая часть)</field>"
  +    "<classifier><name>Пользователь</name>"
  +      "<field>Наименование</field>"
  +    "</classifier>"
  +  "</classifier>"
  +"</object>" );
 
 // Сохраняем интерфейсы полей
 var oFldCode = oDS.Fields("Код");
     oFldCurrencyCode = oDS.Fields("Валюта\\Буквенный код");
     oFldCurrencyUserName = oDS.Fields("Валюта\\Пользователь\\Наименование");
 
 // Заполняем объект данными
 for ( i = 1; i<=10; ++i )
 {
   oDS.Run("AddNew");
   oFldCode.Value = "Test" + i;
   oFldCurrencyCode.Value = i % 2 == 0 ? "RUR" : "USD";
   oDS.Run("Update");
 }
 
 // Выводим заполненные данные
 if ( oDS.Run("GetFirst") ) do
 {
   var sRecord = "Код:\t\t" + oFldCode.Value + "\n"
               + "Валюта:\t\t" + oFldCurrencyCode.Value + "\n"
               + "Польз. вал.:\t" + oFldCurrencyUserName.Value;
   WScript.Echo( sRecord );
 }
 while( oDS.Run("GetNext") );

Коллекция объектов

Interface: IRSCOMObjectsCollection->IDispatch

Coclass: RSCOMObjectsCollection

Описание

Интерфейс коллекции объектов используется для работы с подобъектами объекта. Указатель на интерфейс коллекции возвращается свойством SubObjects в интерфейсе объекта.

Все возможные подобъекты для данного типа заданы в его описании (см. TypeInfo). При создании конкретного объекта можно указать подмножество подобъектов и определить их порядок (см. ConnectString).

Свойства

Count. Размер.

Возвращает количество объектов в коллекции. Доступно только для чтения. Размер коллекции подобъектов определяется числом выбранных подобъектов в ConnectString

Type. Тип.

Возвращает RSOBJECTSCOLLECTION_TYPE (0x80050000). Служебная информация, используется для преобразования указателей на внутренние служебные интерфейсы в указатели на IDispatch. Попытка задать значение этого свойства приведет к ошибке «Функция не реализована».

Owner. Владелец.

Возвращает указатель на IDispatch объекта.

Методы

Item. Объект по имени/номеру.

По имени подобъекта или его порядковому номеру, возвращает интерфейс соответствующего объекта. В первом случае тип параметра Index должен быть VT_BSTR (можно VT_BYREF), во втором — VT_I2, VT_UI2, VT_I4 или VT_UI4 (также можно VT_BYREF). В противном случае вернется ошибка «Некорректный параметр». Порядок подобъектов в коллекции определяется описанием конкретного объекта — ConnectString.

Объект (СОМ-объект)

Interface: IRSCOMObject->IRSCOMItem->IDispatch

Coclass: RSCOMObject

Описание

Представляет собой объектно-ориентированный интерфейс доступа к данным, хранящимся на сервере. Каждый объект принадлежит к некоторому типу, описанному в TypeInfo. Список всех типов и их описание можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

Прежде, чем работать с объектом, необходимо его открыть, то есть описать данные, которые требуется считать с сервера и задать режим работы. Это делается с помощью свойства ConnectString. Попытка обращаться к методам интерфейса IRSCOMObject для закрытого объекта приведет к ошибке «Объект не инициализирован».

У каждого типа объекта могут быть экземпляры — записи в таблице. Эти записи могут быть сгруппированы в один (в случае списка) или несколько (в случае дерева) наборов записей. В каждом наборе есть текущая позиция, которую можно менять с помощью методов перемещения по набору записей: GetFirst, GetLast, GetNext, GetPrev, GetData для списка и, дополнительно, GetRoot, GetParent и GetChild для дерева. Чтение данных из текущей позиции осуществляется с помощью коллекции полей. Значения полей можно прочитать только для корректной позиции. Методы, проверяющие корректность текущей позиции — ValidPosition, EOF, BOF, Root.

Найти определенную запись по значению полей можно, используя метод Search. Состав набора записей можно изменять, задавая условия фильтра (условия отбора записей) с помощью методов SetFilter, ApplyFilter, GetFilter. Порядок записей в наборе можно определять с помощью условий сортировки методами SetSort, GetSort.

Данные объекта можно изменять, добавляя новые экземпляры методом AddNew, удаляя существующие экземпляры методом Delete и сохраняя измененные значения полей с помощью Update. Изменения в данных объекта можно откатить методом CancelUpdate.

Свойства

RSName. Имя объекта.

Возвращает имя объекта в соответствии с описанием типа объекта (см. TypeInfo). Имена глобальных (самостоятельных) типов уникальны. Имена подобъектов уникальны только в рамках данного типа объекта. Для получения полного имени используйте свойство FullName. Попытка задать значение свойства RSName приведет к ошибке «Функция не реализована».

Type. Тип.

Возвращает RSOBJECT_TYPE(0x00050000) с некоторыми дополнительными флагами: OT_GLOBAL (0x1) для глобальных объектов (имеющих собственное соединение с сервером); OT_SUBOBJ (0x2) для подобъектов; OT_TREE (0x8) для объектов-деревьев. Служебная информация, используется для преобразования указателей на внутренние служебные интерфейсы в указатели на IDispatch. Попытка задать значение этого свойства приведет к ошибке «Функция не реализована».

Number. Номер.

Порядковый номер объекта в коллекции подобъектов или 0, если объект не является подобъектом. Попытка задать значения этого свойства приведет к ошибке «Функция не реализована».

Owner. Владелец.

Для подобъектов возвращает указатель на IDispatch основного объекта. Для остальных объектов возвращает NULL.

Flags. Флаги.

Возвращает флаги объекта в соответствии с описанием типа объекта (см. TypeInfo). Попытка задать значения этого свойства приведет к ошибке «Функция не реализована». Для объектов определены следующие флаги:

ConnectString. XML-описание объекта

Это свойство определяет, какие именно данные и каким образом будут читаться с сервера. Часто для работы с объектом не нужны все его поля и подобъекты. Например, чтобы показать список выбора для некоторого классификатора, не нужно считывать ни одного подобъекта и достаточно показать только одно-два поля (например, строковый код и наименование). Так как по умолчанию визуальный элемент списка показывает поля (колонки) в том порядке, в котором они выбраны в источнике данных, в ConnectString имеет смысл указывать порядок полей. Кроме этого, ConnectString позволяет задать и более специфичную информацию: размер локального буфера записей, признак того, что нужна функциональность дерева и т. п.

Изменение значения этого свойства приводит к закрытию текущего объекта и открытию нового. При этом меняется структура объекта (коллекции полей, подобъектов, список доступных методов и т. п.). Следует отметить, что «старый» объект необязательно будет сразу отсоединен от сервера и разрушен в памяти: этого не произойдет, пока на него имеются ссылки (например, пока не истечет время жизни переменных-указателей на интерфейсы полей, подобъектов, коллекций и пр.).

Описание объекта задается в формате XML. Ниже приведена спецификация описания объекта и краткий комментарий.

  <?xml version="1.0" encoding="utf-8" ?> 
  <xsd:schema targetNamespace="http://softlab.ru/balance" elementFormDefault="qualified" xmlns:tns="http://softlab.ru/balance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <!-- 
 FILE         :   OpenHandle.xsd
 COPYRIGHT    :   R~Style, 2002
 DESCRIPTION  :   Описание командной строки для OpenHandle
 PROGRAMMED BY:   Kuznetsov Alexander
 CREATION DATE:   18.10.2002
  --> 
  <xsd:element name="object">
  <xsd:complexType>
  <xsd:sequence>
  <xsd:element ref="tns:name" /> 
  <xsd:element name="sub_object">
  <xsd:complexType>
  <xsd:sequence>
  <xsd:element ref="tns:name" /> 
  <xsd:element ref="tns:field" minOccurs="0" maxOccurs="unbounded" /> 
  <xsd:element ref="tns:classifier" minOccurs="0" maxOccurs="unbounded" /> 
  </xsd:sequence>
  <xsd:attribute name="include" type="tns:YesNo" default="yes" /> 
  <xsd:attribute name="all_fields" type="tns:YesNo" default="yes" /> 
  </xsd:complexType>
  </xsd:element>
  <xsd:element ref="tns:field" minOccurs="0" maxOccurs="unbounded" /> 
  <xsd:element ref="tns:classifier" minOccurs="0" maxOccurs="unbounded" /> 
  </xsd:sequence>
  <!--  Атрибуты объекта   -->
  <xsd:attribute name="all_fields" type="tns:YesNo" default="no" /> 
  <xsd:attribute name="all_subobjects" type="tns:YesNo" default="no" /> 
  <xsd:attribute name="tree" type="tns:YesNo" default="no" /> 
  <xsd:attribute name="rec_count" type="xsd:unsignedInt" use="optional" /> 
  <xsd:attribute name="language" type="xsd:unsignedInt" use="optional" />
  </xsd:complexType>
  </xsd:element>
  <!--  наименование  --> 
  <xsd:element name="name" type="xsd:string" /> 
  <!--  классификатор  --> 
  <xsd:element name="classifier">
  <xsd:complexType>
  <xsd:sequence>
  <xsd:element ref="tns:name" /> 
  <xsd:element ref="tns:field" minOccurs="0" maxOccurs="unbounded" /> 
  <xsd:element ref="tns:classifier" minOccurs="0" maxOccurs="unbounded" /> 
  </xsd:sequence>
  <xsd:attribute name="tree" type="tns:YesNo" default="no" /> 
  </xsd:complexType>
  </xsd:element>
  <!--  поле объекта/подобъекта  --> 
  <xsd:element name="field">
  <xsd:complexType>
  <xsd:attribute name="include" type="tns:YesNo" default="yes" /> 
  <xsd:attribute name="delayed" type="tns:YesNo" default="no" /> 
  </xsd:complexType>
  </xsd:element>
  <!--  клиент  --> 
  <xsd:element name="client">
  <xsd:complexType>
  <xsd:sequence>
  <xsd:element ref="tns:name" /> 
  <xsd:element name="password" type="xsd:string" /> 
  </xsd:sequence>
  <xsd:attribute name="default" type="tns:YesNo" default="no" /> 
  </xsd:complexType>
  </xsd:element>
  <!--  Тип флага  --> 
  <xsd:simpleType name="YesNo">
  <xsd:restriction base="xsd:string">
  <xsd:enumeration value="yes" /> 
  <xsd:enumeration value="no" /> 
  </xsd:restriction>
  </xsd:simpleType>
  </xsd:schema>

С помощью атрибутов all_fields (all_subobjects) элемента object и sub_object можно включить в описание объекта (подобъекта) все поля (подобъекты), а затем выкинуть ненужные, используя элементы field (sub_object). Или, наоборот, сначала исключить все поля (подобъекты), а потом явно указать те из них, которые нужны.

Атрибут tree элементов object и classifier указывает на то, что объекту (классификатору) требуется функциональность дерева. Если объект поддерживает такую функциональность, его он будет открыт в режиме дерева (его можно также открыть и в режиме списка).

Атрибут rec_count определяет размер локального буфера записей. Буфер кэширует записи для того, чтобы не считывать их с сервера. Если нужно читать список или дерево, обычно используется буфер из 100 записей.

Атрибут delayed для полей задает возможность «отложенного чтения». Это значит, что поле будет читаться с сервера не сразу при чтении всего объекта, а по первому запросу. Это сделано для оптимизации работы с полями, содержащими объемные данные, например, текст документа, картинки, видео и т. д. Читать такие данные с сервера сразу не имеет смысла, так как обычно для их показа необходим вызов отдельного приложения и данные можно считать по факту такого вызова.

Например, открыть реестр настроек в виде дерева и запросить определенные поля (в том числе и поле с отложенным чтением «значение настройки») можно с помощью следующего описания:

 <object all_fields="No" all_subobjects="No" rec_count="100" tree ="Yes">
  <name>Общесистемные настройки</name>
  <field>Наименование</field>
  <field>Системный</field>
  <field>Папка</field>
  <field>Глобальный</field>
  <field delayed="Yes">Значение</field>
 </object>

Для чтения одной настройки можно использовать следующее описание:

 <object all_subobjects="No" rec_count="1">
  <name>Общесистемные настройки</name>
  <field delayed="Yes">Значение</field>
  <sub_object all_fields="Yes">
   <name>Пользовательские настройки</name>
   <field include="No">Идентификатор</field>
   <classifier>
    <name>Операционист</name>
    <field>Наименование</field>
   </classifier>
  <sub_object>
 </object>

FullName. Полное имя объекта.

Свойство позволяет получить полное имя объекта. Для глобального объекта значение этого свойства совпадает с RSName. Для подобъекта полное имя включает имя основного объекта, отделенное символом точки: «Имя объекта. Имя подобъекта». (свойство RSName в этом случае будет иметь значение «Имя подобъекта»).

IsTree. Объект открыт в режиме дерева.

Возвращает VARIANT_TRUE, если объект открыт в режиме дерева. Это можно проверить также по наличию флага OT_TREE в свойстве Flags.

Sort. Сортировка.

Свойство на чтение и запись. Позволяет получить и задать условия сортировки набора записей (экземпляров объектов). Альтернативным методом получения/задания сортировки является вызов методов GetSort и SetSort. Сортировка задается строкой следующего формата (БНФ):

        sort ::= sort, condition | condition
   condition ::= field [ASC | DESC]
       field ::= name | 'complex_name' | "complex_name"
        name ::= w+ | name\w+
complex_name ::= (w| )+ | complex_name\(w| )+
           w ::= [A-Za-zА-Яа-я0-9_]

Пример: «Валюта оплаты\Код ISO», Сумма DESC.

Если направление сортировки не задано, по умолчанию предполагается ASC. Сортировка по некоторым видам полей не поддерживается. Сюда входят временные метки, поля, добавленные сервером (которые не выбраны явно в ConnectString), вычисляемые поля в глобальных объектах.

Filter. Фильтр

Свойство на чтение и запись. Позволяет получить и определять условия фильтрации набора записей (экземпляров объекта). Чтение значения свойства Filter аналогично вызову метода GetFilter, запись — вызову метода SetFilter с единственным параметром — условие фильтра. Иными словами, задание фильтра через свойство Filter изменяет условие системного фильтра и НЕ ПРИМЕНЯЕТ это условие. Для того, чтобы применить или снять текущее условие фильтра, используйте метод ApplyFilter. Фильтр задается строкой следующего формата (БНФ):

       <filter> ::= <or_condition>
 <or_condition> ::= <or_condition> <or> <and_condition>
                  | <and_condition>
<and_condition> ::= <and_condition> <and> <term> 
                  | <term>
         <term> ::= <not> <term>
                  | (<filter>) 
                  | <condition>
    <condition> ::= <field> <oper> <value> 
                  | <value> <less> <field> <less> <value>
                  | <value> <greater> <field> <greater> <value>
           <or> ::= <spaces> <lex_or> <spaces>
          <and> ::= <spaces> <lex_and> <spaces>
          <not> ::= <spaces> <lex_not> <spaces>
       <lex_or> ::= OR|ИЛИ
      <lex_and> ::= AND|И
      <lex_not> ::= NOT|НЕ
         <oper> ::= <less>
                  | <greater>
                  | [<spaces>] = [<spaces>]
                  | [<spaces>] != [<spaces>]
                  | <like>
         <less> ::= [<spaces>] < [<spaces>]
                  | [<spaces>] <= [<spaces>]
      <greater> ::= [<spaces>] > [<spaces>]
                  | [<spaces>] >= [<spaces>]
         <like> ::= <spaces> <lex_like> <spaces>
     <lex_like> ::= LIKE|ТИПА
        <field> ::= <spaces> <token> <spaces>
        <value> ::= <spaces> <token> <spaces>
        <token> ::= <word>|'<word>'|"<word>"|'<string>'|"<string>"
         <word> ::= <letter>|<letter><word>
       <letter> ::= <char>||""
       <string> ::= <symbol>|<symbol><string>
       <symbol> ::= [^'"#0]||""
       <spaces> ::= <space>|<space><spaces>
        <space> ::= #9|#10|#13|#32
        <break> ::= #0|<space>|(|)|<|>|=|!|'|"
         <char> ::= ^<break>

Пример: 100 <= Сумма < 500 and (“Валюта\Код ISO” = “RUR” or “Валюта\Код ISO” = “USD”) and not “Контрагент\Наименование” like “%R-Style%”.

Фильтр по некоторым видам полей не поддерживается. Сюда входят временные метки, поля, добавленные сервером (которые не выбраны явно в ConnectString), вычисляемые поля в глобальных объектах.

Session. Сессия.

Возвращает указатель на интерфейс сессии, в которой был создан данный объект. Если объект еще не был открыт, вернется указатель на сессию по умолчанию.

Fields. Коллекция полей.

Возвращает указатель на интерфейс коллекции полей. Для открытого объекта всегда не NULL.

SubObjects. Коллекция подобъектов.

Возвращает указатель на интерфейс коллекции подобъектов. Для открытого объекта всегда не NULL.

Keys. Коллекция ключей.

Возвращает указатель на интерфейс коллекции ключей. Для открытого объекта всегда не NULL.

Bookmarks. Закладки.

Возвращает указатель на интерфейс коллекции закладок. Для открытого объекта всегда не NULL.

UpdateFlag. Флаг операции Update для текущей записи.

Флаг операции Update для текущей записи. Имеет тип перечисляемого типа EupdateFlag:

В перечислении флагов не хватает флага «текущая запись помечена для удаления», но он опущен намеренно: записи, помеченные для удаления, пропускаются при итерации по набору записей, поэтому это значение никогда бы не возвращалось.

Методы

Run. Вызов методов объекта.

Основной метод интерфейса объекта. Все доступные для данного типа объекта методы вызываются через метод Run. Список всех доступных методов можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

Первый параметр Run определяет имя метода, второй – параметры метода, третий – возвращаемое значение.

У каждого метода – свой набор параметров (количество, тип значения, тип передачи – по ссылке или по значению и т.д.). Возможность передавать разное (в том числе и нулевое) число параметров достигается использованием указателя на, возможность разнообразия типов – использованием VARIANT в качестве элемента массива. Если в типе параметра установлен флаг VT_BYREF, считается, что параметр передан по ссылке (соответственно, учитывается возможность изменения значения параметра). Если флага VT_BYREF считается, что параметр передан по значению. Все параметры считаются входными и выходными одновременно. Это значит, в том числе и то, что в процессе обработки вызова методов число параметров не должно меняться: если на вход было передано 3 параметра, то ровно столько же параметров будет и на выходе из метода.

Возвращаемое значение имеет тип VARIANT. Для методов, сигнатура которых не подразумевает явного возвращаемого значения, принято соглашение, что они возвращают VARIANT_TRUE в случае успешной работы и VARIANT_FALSE – в случае возникновения ошибок.

Помимо специфичных для каждого конкретного типа методов, существуют стандартные методы, обеспечивающие общую функциональность. Поэтому эти методы определены практически во всех типах. Ниже приведен список стандартных методов. Если в описании метода ничего не говорится о параметрах, значит их нет.

GetFirst

Установить текущую позицию на первую запись в наборе записей (выбрать первый объект данного типа). При этом учитывается текущая сортировка и фильтр, т.е. искомая запись будет первой в упорядоченном и отфильтрованном наборе записей. Если записей нет, установит флаги BOF и EOF. Возвращает VARIANT_TRUE, если удалось успешно встать на первую запись.

GetLast

Установить текущую позицию на последнюю запись в наборе записей (выбрать последний объект данного типа). При этом учитывается текущая сортировка и фильтр, т.е. искомая запись будет последней в упорядоченном и отфильтрованном наборе записей. Если записей нет, установит флаги BOF и EOF. Возвращает VARIANT_TRUE, если удалось успешно встать на последнюю запись.

GetNext

Сдвинуть текущую позицию на следующую запись в наборе записей (выбрать следующий объект данного типа). При этом учитывается текущая сортировка и фильтр, т.е. искомая запись будет следующей в упорядоченном и отфильтрованном наборе записей. Если текущая позиция стоит на последней записи, устанавливает позицию в EOF. Если набор записей находился в BOF, встает на первую запись. Возвращает VARIANT_TRUE, если удалось успешно встать на следующую запись.

GetPrev

Сдвинуть текущую позицию на предыдущую запись в наборе записей (выбрать следующий объект данного типа). При этом учитывается текущая сортировка и фильтр, т.е. искомая запись будет предыдущей в упорядоченном и отфильтрованном наборе записей. Если текущая позиция стоит на первой записи, устанавливает позицию в BOF. Если набор записей находился в EOF, встает на последнюю запись. Возвращает VARIANT_TRUE, если удалось успешно встать на предыдущую запись.

BOF

Представляет собой (виртуальную) позицию перед первой записью. Сигнализирует, что при перемещении по набору записей к его началу, записи кончились. Эта позиция не является корректной, т.е. находясь в этой позиции нельзя читать или задавать значения полей объекта. Свойство BOF принимает значение VARIANT_TRUE, если текущая позиция набора записей находится перед первой записью. В противном случае, возвращает VARIANT_FALSE. В случае если записей нет, флаг BOF установлен одновременно с флагом EOF.

EOF

Представляет собой (виртуальную) позицию за последней записью. Сигнализирует, что при перемещении по набору записей к его концу, записи кончились. Эта позиция не является корректной, т.е. находясь в этой позиции нельзя читать или задавать значения полей объекта. Свойство EOF принимает значение VARIANT_TRUE, если текущая позиция набора записей находится за последней записью. В противном случае, возвращает VARIANT_FALSE. В случае если записей нет, флаг EOF установлен одновременно с флагом BOF.

ValidPosition

Метод возвращает VARIANT_ TRUE, если текущая позиция корректна и VARIANT_FALSE в противном случае. Некорректными считаются позиции BOF или EOF, а также позиция Root для объектов, открытых в режиме дерева.

GetData

Найти запись по ключу. Единственный параметр метода – ключ, по значению которого ищется текущая позиция. Ключ должен относиться к объекту того же типа, иначе вернется ошибка «Неправильный GUID объекта». Это может быть как первичный ключ (по идентификатору), так и альтернативный ключ. Если ключ найден, и текущая позиция установлена, возвращает VARIANT_TRUE. В противном случае – VARIANT_FALSE. Если выборка записей по значениям некоторых полей производится достаточно часто, рекомендуется создать для этого типа объекта физический (нелогический) ключ и использовать метод GetData, вместо метода Search.

Refresh

Обновление данных в наборе записей. Если объект имеет соединение с сервером, данные будут заново перечитаны с сервера. Для всех объектов заново применяются условия фильтра и сортировки, отменяются все текущие изменения. После обновления данных метод попытается восстановить текущую позицию: если до вызова Refresh текущая позиция была корректной, будет предпринята попытка снова найти эту запись. Если текущая позиция была некорректной – она останется некорректной. Метод возвращает VARIANT_TRUE в случае успешного обновления данных и восстановления текущей позиции и VARIANT_FALSE – в противном случае.

SavePosition

Сохраняет/восстанавливает текущую позицию. Если параметр метода равен VARIANT_TRUE – сохранят текущую позицию (сохраняется значение первичного ключа). Если VARIANT_FALSE – восстанавливает позицию (вызывается метод GetData по сохраненному ключу). Сохранение/восстановление позиции происходит в том числе и рекурсивно для всех подобъектов. При этом позиции сохраняются в стеке: очередная позиция сохраняется в вершине стека. Восстанавливаемая позиция также всегда берется из вершины стека. Метод возвращает VARIANT_FALSE при попытке сохранить некорректную позицию, либо восстановить позицию, если стек сохраненных позиций пуст.

GetFilter

Возвращает текущее условие системного или пользовательского фильтра и состояние фильтра («применен» – «не применен»).

Системный фильтр задается только программно, его нельзя редактировать с помощью диалога редактирования фильтра. Пользовательский фильтр задается как программно, так и из диалога редактирования фильтра. Разделение условий фильтра существует только для программы клиента: перед установкой фильтра на сервере условия объединяются по «и».

Строка-условие фильтра возвращается в первом параметре, флаг «установлен»-«не установлен» – во втором (типа VARIANT_BOOL). Если статус фильтра не нужен, второй параметр можно не задавать. Третий необязательный параметр типа VARIANT_BOOL определяет тип фильтра. Если он равен VARIANT_FALSE, возвращаются сведения о системном фильтре. В противном случае – о пользовательском фильтре. По умолчанию метод возвращает сведения о системном фильтре.

См. также свойство Filter объекта.

SetFilter

Метод задает текущее условие системного или пользовательского фильтра.

Системный фильтр задается только программно, его нельзя редактировать с помощью диалога редактирования фильтра. Пользовательский фильтр задается как программно, так и из диалога редактирования фильтра. Разделение условий фильтра существует только для программы клиента: перед установкой фильтра на сервере условия объединяются по «и».

Первый параметр задает строку условия. Второй необязательный параметр – флаг «Применить» (по умолчанию – VARIANT_FALSE). Если он равен VARIANT_TRUE, фильтр применяется к набору записей, т.е. записи, не удовлетворяющие условию, исключаются из набора записей.

Вызов метода SetFilter без второго параметра (или с параметром «Применить», равным VARIANT_FALSE) эквивалентен заданию фильтра через свойство Filter.

Вызов SetFilter с пустой строкой очищает текущее условие фильтра. Если при этом параметр «Применить» равен VARIANT_FALSE, записи останутся отфильтрованными в соответствие с прежним условием, если VARIANT_TRUE – набор записей будет включать все возможные записи (т.е. фильтр будет отменен).

Третий необязательный параметр типа VARIANT_BOOL определяет тип фильтра. Если он равен VARIANT_FALSE, устанавливается системный фильтр. В противном случае – пользовательский фильтр. По умолчанию метод устанавливает системный фильтр.

В случае успешного применения условий фильтра метод вернет VARIANT_TRUE.

ApplyFilter

Применить/снять текущее условие системного или пользовательского фильтра.

Системный фильтр задается только программно, его нельзя редактировать с помощью диалога редактирования фильтра. Пользовательский фильтр задается как программно, так и из диалога редактирования фильтра. Разделение условий фильтра существует только для программы клиента: перед установкой фильтра на сервере условия объединяются по «и».

Первый параметр имеет тип VT_BOOL. Если он равен VARIANT_TRUE условие фильтра применяется к набору записей, в противном случае – снимается с набора записей. По умолчанию (если параметр не задан) метод применяет условие фильтра. Если условие фильтра не задано, никакого эффекта от этого метода нет.

Второй необязательный параметр типа VARIANT_BOOL определяет тип фильтра. Если он равен VARIANT_FALSE, устанавливается системный фильтр. В противном случае – пользовательский фильтр. По умолчанию (если параметр не задан) метод устанавливает системный фильтр.

В случае успешного применения условий фильтра метод вернет VARIANT_TRUE.

GetSort

Метод возвращает в первом параметре строку условий текущей сортировки или пустую строку, если сортировка не задан. См. также свойство Sort объекта.

SetSort

Метод задает текущее условие сортировки посредством параметра – строки условия. См. также свойство Sort объекта.

m_dsData.RSObject.Run("SetSort", "'Документ\\Дата документа' DESC");

Возможна сортировка по нескольким полям:

dsWare.Run("SetSort", "'Наименование краткое' ASC 'Код' DESC");
Search

Поиск записи. Обязательные параметры – поле (наименование или порядковый номер) и значение поля. Для строк есть необязательный параметр «Искать по полной строке» (по умолчанию – VARIANT_TRUE). Для других типов задавать этот параметр нельзя. Дальше снова может идти пара поле+значение (с необязательным параметром «Искать по полной строке»). Число таких пар произвольно. Последний необязательный параметр – «Искать вверх» (по умолчанию – VARIANT_FALSE), определяющий направление поиска от текущей позиции.

Пример на VBScript:

 ' Допустим, есть гипотетический тип, имеющий поле-ссылку на тип «Валюта»,
 ' строковое поле «Номер» и поле-ссылку на операциониста
 
 ' Тогда поиск вверх от текущей записи долларовой записи
 ' с номером, начинающимся на В331 и операционистом 9999
 Call dsContract.Run("Search", "Валюта\Код", "USD", _
                     "Номер", "В331", False, _	
                     "Операционист\Имя", "9999", True)

Если запись найдена, она становится текущей и метод возвращает VARIANT_TRUE. Следует отметить, что поиск идет от текущей позиции включительно, поэтому, чтобы найти следующую подходящую запись, нужно сместиться с текущей позиции вверх или вниз (MovePrev или MoveNext)

AddNew

Добавить новую запись. Запись добавляется после текущей (если стояли в BOF – в начало, если в EOF – в конец набора записей). После вызова метода AddNew текущая позиция становится на новой записи.

Новой записи автоматически присваивается временный уникальный идентификатор (который является уникальным только для данного набора записей в его текущем состоянии). Временный идентификатор представляет собой счетчик с начальным значением 0x80000000 (при создании объекта), который для каждой новой записи увеличивается на единицу. Постоянный идентификатор запись получит после сохранения на сервере, и он уже будет гарантированно уникальным среди объектов данного типа.

Поля новой записи автоматически заполняются значениями по умолчанию. Значение по умолчанию для поля данного типа объекта задается в описании типа. Его можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

Новая запись помечается флагом «Новая запись» и помещается в буфер отката (см. CancelUpdate). При вызове метода CancelUpdate запись будет удалена. Чтобы запись была окончательно добавлена, нужно вызвать метод Update.

Если объект открыт в режиме «дерево», у метода есть параметр «Добавить в качестве дочернего узла». Если этот параметр равен VARIANT_TRUE, новая запись добавляется первой в список непосредственных потомков текущего узла. В противном случае, запись добавляется на тот же уровень дерева. При попытке вызвать этот метод для объекта, у которого в поле Flags установлен флаг TI_READONLY, вернется ошибка «Несовместимый режим работы».

Наличие более одного параметра в режиме дерева или наличие хотя бы одного параметра в остальных режимах приводит к тому, что метод AddNew будет вызван на сервере (обычно, все необходимые действия осуществляются программой-клиентом). При этом серверу будет передана текущая (новая) запись и после возвращения серверного метода, данные новой записи будут прочитаны с сервера.

Update

Сохранить все изменения. Для локального объекта просто очищает буфер отката (см. CancelUpdate) как для этого объекта, так и для всех его подобъектов. Для серверного объекта помимо этого сохраняет данные на сервере (как в наборе записей самого объекта, так и во всех подобъектах).

Записи, помеченные флагом UPDATE_FLAG_INSERT добавляются на сервере. При этом временные идентификаторы новых записей заменяются постоянными. Записи, помеченные флагом UPDATE_FLAG_UPDATE сохраняются, а UPDATE_FLAG_DELETE – удаляются. После этого обновленные записи возвращаются клиентскому приложению уже без каких-либо флагов.

При вызове метода Update текущая позиция может находиться в любом месте набора записей, в том числе и в BOF и EOF, т.к. метод Update сохраняет все измененные записи.

Delete

Удалить текущую запись. При попытке вызвать этот метод для некорректной позиции, вернется соответствующая ошибка. В случае локального объекта физически удаляются только новые записи (т.е. записи, добавленные методом AddNew и еще не сохраненные на сервере), прочие записи просто помечаются для удаления (см. CancelUpdate) и будут удалены физически только после вызова метода Update для соответствующего серверного объекта. В случае серверного объекта, запись будет удалена сразу же на сервере. Таким образом, вызов метода Delete сразу изменяет данные объекта (подобъекта) и не требует, в отличие от метода AddNew, последующего вызова Update для того же объекта.

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

При попытке вызвать этот метод для объекта, у которого в поле Flags установлен флаг TI_READONLY, вернется ошибка «Несовместимый режим работы».

CancelUpdate

Отменить все изменения с момента последнего вызова Update или Refresh. Все изменения хранятся в буфере отката.

Буфер отката создается для каждого объекта или подобъекта и рассчитан на неограниченное число записей. В буфере отката регистрируются все изменения данных объекта или его подобъектов: добавление новых записей (методом AddNew), изменение значений полей (через коллекцию полей объекта) существующих записей и, наконец, удаление существующих записей в подобъектах (методом Delete).

Таким образом, если в объекте один или несколько раз вызывался метод AddNew, изменялись значения полей для одной или нескольких записей, и при этом не вызывался метод Update, тогда вызов метода CancelUpdate откатит все эти изменения.

Еще раз подчеркнем, метод Delete не регистрирует изменений в буфере отката самого объекта, а только в буфере отката его контекста (первичного или вторичного). Т.е. удаление записи нельзя отменить вызовом метода CancelUpdate в самом объекте. Отмена удаления записи возможна только вызовом метода CancelUpdate у его контекста. Таким образом, удаление записей серверных объектов (у которых контекста нет) необратимо.

Буфер отката организован иерархически для подобъектов. Серверный объект (первичный контекст) регистрирует в своем буфере отката все изменения в его подобъектах. Если один подобъект открыт в контексте другого, т.е. является подобъектом подобъекта, тогда его контекст регистрирует в своем буфере отката все изменения в этом подобъекте. Таким образом, вызов Update для подобъекта подобъекта можно откатить вызовом CancelUpdate для подобъекта (вторичного контекста) или вызовом CancelUpdate для серверного объекта (первичного контекста).

Буфер отката очищается при вызове метода Update или Refresh. После вызова метода CancelUpdate буфер отката также будет пуст.

IsDirty

Данные объекта были изменены. Возвращает VARIANT_TRUE, если менялось состояние набора записей (включая подобъекты). Фактически, объект считается измененным, если буфер отката для этого объекта непуст.

GetRoot

Переместиться в корень дерева. Устанавливает текущую позицию в корень дерева и возвращает VARIANT_TRUE, если объект открыт в соответствующем режиме (tree = “yes”). В противном случае, вернет ошибку «Несовместимый режим работы».

Root

Признак корня дерева. Возвращает VARIANT_TRUE, если текущая позиция находится в корне дерева. Для объекта, открытого в другом режиме (tree = “no”) вернет ошибку «Несовместимый режим работы».

GetParent

Переместиться в родительский узел. Устанавливает текущую позицию в узел, являющийся родительским для текущего узла. Если текущая позиция находится в корне дерева, вернет ошибку «Корень дерева». Метод работает и в том случае, когда текущая позиция находится в BOF или EOF. Для объекта, открытого в другом режиме (tree = “no”) вернет ошибку «Несовместимый режим работы».

GetChild

Переместиться в дочерний набор записей. Меняет текущий набор записей на дочерний, возвращает VARIANT_TRUE в случае успеха. Если у текущего набора нет потомков, возвращает VARIANT_FALSE. Если текущая позиция находится в BOF или EOF, возвращается соответствующая ошибка. У метода есть необязательный параметр «Встать на первую запись», который по умолчанию равен VARIANT_TRUE. Он определяет, нужно ли автоматически вызывать метод GetFirst в дочернем наборе записей. Если в дочернем наборе метод GetFirst возвращает ошибку, текущим снова станет родительский набор записей и метод вернет VARIANT_FALSE. Если значение параметра равно VARIANT_FALSE, текущая позиция в дочернем наборе записей останется без изменений (BOF, если навигации по набору еще не было). Для объекта, открытого в другом режиме (tree = “no”) вернет ошибку «Несовместимый режим работы».

HasChild

Признак наличия потомков. Возвращает VARIANT_TRUE, если у текущего узла дерева есть дочерние узлы. Если текущая позиция находится в корне дерева, в BOF или в EOF набора записей некоторого уровня, тогда вернет соответствующую ошибку. Для объекта, открытого в другом режиме (tree = “no”) вернет ошибку «Несовместимый режим работы».

HasAncestor

Проверяет, является ли некоторый узел предком текущего узла. Проверяемый узел задается с помощью одного из своих ключей. Переданный ключ преобразуется к первичному, из него читается значение идентификатора, затем это значение ищется в цепочке родителей. Если предок с таким значением идентификатора найден, возвращается VARIAN_TRUE. Метод работает и в том случае, когда текущая позиция находится в BOF или EOF. Для объекта, открытого в другом режиме (tree = “no”) вернет ошибку «Несовместимый режим работы».

EnclosedLevel

Возвращает высоту дерева до текущего набора записей. Значение для корня равно 0, для прямых потомков корня равно 1 и т.д. Метод работает и в том случае, когда текущая позиция находится в BOF или EOF.

SetMode

Включает/отключает один из режимов работы объекта. Первый параметр – название режима, второй параметр – типа bool, является признаком включения/отключения режима. Список доступных режимов:

Пример:

 dsDoc.Run("SetMode", "SetDefaultValuesInAddNew", false);

ShowFindDialog. Показать диалог поиска по полю.

Показывает модальный диалог поиска по полю, номер или имя которого передается в качестве 1-го параметра. Родительским окном диалога становится активное окно, имеющее заголовок (title bar). Метод возвращает VARIANT_TRUE, если пользователь нажал кнопку «OK» и запись была найдена. В противном случае вернется VARIANT_FALSE.

ShowFilterDialog. Показать диалог фильтра.

Показывает модальный диалог задания условий фильтра. Родительским окном диалога становится активное окно, имеющее заголовок (title bar). Метод возвращает VARIANT_TRUE, если пользователь нажал кнопку «OK» и условия фильтра были успешно заданы и применены к набору записей. В противном случае вернется VARIANT_FALSE.

ShowSortDialog. Показать диалог сортировки.

Показывает модальный диалог задания условий сортировки. Родительским окном диалога становится активное окно, имеющее заголовок (title bar). Метод возвращает VARIANT_TRUE, если пользователь нажал кнопку «OK» и условия фильтра были успешно заданы и применены к набору записей. В противном случае вернется VARIANT_FALSE.

Объект (ActiveX-элемент)

Interface: IRSObjectCtrl->IDispatch

Coclass: RSObjectCtrl

Описание

Визуальный элемент источника данных (data source). Помещается в контейнер и используется для визуальной настройки описания объекта (см. ConnectString), сохранения этого описания на жестком диске, а также для подключения к источникам данных визуальных элементов управления (data-aware controls).

На этапе разработки (design-time) для редактирования доступно лишь свойство ConnectString. Описание объекта задается с помощью вспомогательных диалогов, в которых разработчик задает состав и порядок полей и подобъектов, режим работы объекта (список или дерево), количество записей в буфере и пр. То есть фактически указывает элементы и атрибуты XML-описания объекта. После завершения работы с диалогами формируется XML-строка, которую можно сохранить на жесткий диск стандартными методами сериализации контейнера.

Кроме того, на этапе разработки можно связать источник данных с визуальными элементами, отображающими эти данные (RSFieldCtrl , RSGridCtrl и RSTreeCtrl). Привязка осуществляется по имени конкретного RSObjectCtrl, которое устанавливается в качестве значения свойства RsObjectName управляющего элемента. Привязку можно задать и для подобъектов (на один уровень вложенности). При этом имя подобъекта нужно указать через «\», например: dsContract\Участник. Более глубокая вложенность не предусмотрена.

На этапе выполнения (run-time) каждый визуальный источник данных начинает искать в том же контейнере визуальные элементы, поддерживающие интерфейс IRSDataAwareCtrl и проверяет у них свойство RsObjectName. Если оно совпадает с именем этого источника, либо одного из его подобъектов, RSObjectCtrl устанавливает указатель на свой источник данных (либо источник данных подобъекта) в качестве значения свойства RsObject управляющего элемента. «Наши» управляющие элементы отличаются от «чужих» тем, что поддерживают интерфейс IRSDataAwareCtrl.

На этапе выполнения интерфейс источника данных для RSObjectCtrl может задаваться извне (см. свойство RSObject). Так же можно явно задать XML-строкой свойство ConnectString. Смена источника данных одним из этих способов освободит ссылку на старый источник со стороны RSObjectCtrl, и, если других ссылок на тот же источник больше нет, приведет к его уничтожению.

RSObjectCtrl является видимым только на этапе разработки. На этапе выполнения источник данных невидим.

Свойства

RSObject. Источник данных.

Позволяет получить и задать интерфейс источника данных. Доступно только на этапе выполнения (run-time). Задание нового источника данных приведет к освобождению ссылки на старый источник, обновлению свойств ConnectString и FullName, и привязыванию заново к соответствующим элементам управления.

ConnectString. XML-описание объекта.

Соответствует свойству ConnectString своего источника данных. На этапе разработки редактируется с помощью вспомогательных диалогов. Сохраняется на жесткий диск методами контейнера.

FullName. Полное имя объекта.

Соответствует свойству FullName своего источника данных. Нередактируемое (составляется на основании TypeInfo объекта). Сохраняется на жесткий диск методами контейнера.

Интерфейс визуального элемента

Interface: IRSDataAwareCtrl->IDispatch

Описание

Представляет собой базовый интерфейс, который реализуют все визуальные элементы управления, связанные с данными — RSFieldCtrl, RSGridCtrl и RSTreeCtrl.

Свойства

RsObjectName. Наименование источника данных.

Привязка визуальных элементов управления к источникам данных осуществляется на этапе разработки (design-time) с помощью этого свойства. Представляет собой имя визуального элемента источника данных в контейнере, например dsCurrency. Это основной способ задать связь элементов управления с источниками данных.

RsObject. Источник данных.

Привязка визуальных элементов управления к источникам данных может осуществляться и на этапе выполнения (run-time) с помощью свойства RsObject. Представляет собой интерфейс объекта, к которому можно обращаться на этапе выполнения. Кроме того, элемент управления можно связать с другим источникам данных, задав его интерфейс с помощью этого свойства.

Параметры соединения с сервером

Interface: IRSCOMConnection->IDispatch

Coclass: RSCOMConnection

Описание

Интерфейс IRSCOMConnection служит для задания параметров соединения с сервером. Реализуется отдельным СОМ-объектом — RSCOMConnection. Пример использования (JavaScript):

// Создаем класс соединения с сервером
var oConnection = new ActiveXObject("RSComProvider.RSCOMConnection");
 
// Проверяем, есть ли уже открытое соединение
if ( oConnection.IsConnected )
{
  // Выводим текущие параметры соединения
  WScript.Echo( "Server=\"" + oConnection.Server + "\"; "+
                 "UserName=\"" + oConnection.UserName + "\"" );
}
else
{
  // Заполняем параметры соединения
  oConnection.Server="";
  oConnection.UserName="Admin";
  oConnection.Password="123";
  oConnection.Connect();
}

Свойства

Server

Имя компьютера, на котором установлен сервер программного комплекса. Сервер должен быть запущен. Для локальной установки имя компьютера можно задавать пустой строкой.

UserName

Login зарегистрированного пользователя. Список всех зарегистрированных пользователей можно посмотреть в программе «Утилита администратора».

Password

Пароль для зарегистрированного пользователя. Задать пароль для пользователя можно в программе «Утилита администратора». Свойство только для записи.

WindowsLogin

Windows Login текущего пользователя.

WindowsAuth

Входить в систему с помощью Windows-аутентификации. Если свойство задано, то UserName и Password игнорируются.

IsConnected

Если соединение установлено. Имеет значение VARIANT_TRUE, если соединение с сервером уже установлено и VARIANT_FALSE в противном случае.

Методы

Connect

Установить соединение с сервером. Если параметры соединения не заданы, показывает диалог соединения с сервером. После того, как все параметры заданы, устанавливает соединение с сервером.

Disconnect

Разорвать соединение с сервером.

Диалог задания фильтра

Interface: IRSCOMFilterDlg->IDispatch

Coclass: RSCOMFilterDlg

Описание

Интерфейс IRSCOMFilterDlg позволяет программно вызывать диалог редактирования условий фильтра. Диалог задания фильтра можно привязать к типу объекта (по наименованию или идентификатору) или к экземпляру объекта. Причем, если диалог связан с конкретным объектом, это условие будет применено к объекту, то есть данные объекта будут отфильтрованы. Если диалог фильтра не привязан ни к типу, ни к экземпляру объекта, при попытке открыть диалог будет выдана соответствующая ошибка.

В следующем примере (JScript) в первых двух случаях формируется строка условия фильтра для типа объекта, в третьем случае — для конкретного экземпляра:

// Создаем объект вызова диалога фильтра
var oFilterDlg = new ActiveXObject( "RSCOMProvider.RSCOMFilterDlg" );
 
// Редактировать фильтр для типа объекта "Базовый документ"
oFilterDlg.RSObjTypeName = "Базовый документ";
// Первоначальное условие фильтра
oFilterDlg.Filter = "'Валюта\\Буквенный код'='RUR'";
oFilterDlg.DoModal();
WScript.Echo( "Условие фильтра: " + oFilterDlg.Filter );
 
// Редактировать фильтр для типа объекта "Валюта"
oFilterDlg.RSObjTypeGUID = "2E65D62B-D904-4BC6-B18A-99111BD2E093";
// Первоначальное условие фильтра
oFilterDlg.Filter = "'Буквенный код' = 'USD'";
oFilterDlg.DoModal();
WScript.Echo( "Условие фильтра: " + oFilterDlg.Filter );
 
// Редактировать фильтр для объекта "Валюта"
var oDS = new ActiveXObject( "RSCOMProvider.RSCOMObject" );
oDS.ConnectString = "<object all_fields='yes'><name>Валюта</name></object>";
oFilterDlg.RSObject = oDS;
oFilterDlg.DoModal();
WScript.Echo( "Условие фильтра: " + oFilterDlg.Filter );

Свойства

Filter. Условие фильтра.

Строка условия фильтра. Синтаксис условий фильтра см. в описании свойства Filter интерфейса объекта.

RSObject. Интерфейс экземпляра объекта.

Интерфейс объекта-источника данных. Если задан, описания полей берутся из строки соединения этого объекта, а результирующее условие будет установлено для данного объекта (см. метод SetFilter).

RSObjTypeGUID. Идентификатор типа объекта.

Представляет собой GUID типа, для которого нужно сформировать условие фильтра. Описания полей берутся непосредственно из описания типа. Список всех типов объектов и их описание можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

RSObjTypeName. Наименование типа объекта.

Представляет собой строку-имя типа, для которого нужно сформировать условие фильтра. Описания полей берутся непосредственно из описания типа. Список всех типов объектов и их описание можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

ID. Идентификатор фильтра

Идентификатор фильтра в объекте "История фильтра"

Name. Наименование фильтра

Наименование фильтра в объекте "История фильтра"

Методы

DoModal. Показать диалог редактирования фильтра.

Метод не имеет параметров. Перед его вызовом необходимо задать либо тип объекта (с помощью свойств RSObjTypeGUID или RSObjTypeName) или интерфейс объекта (с помощью свойства RSObject).

Конструктор свободных полей

Interface: IRSCOMFreeFieldsCreator->IDispatch Coclass: RSCOMFreeFieldsCreator

Описание

Конструктор свободных полей предназначен для создания реализации интерфейса поля, не привязанного к конкретному экземпляру или типу объекта. Свободные поля можно создавать, например, если нужно вводить данные на форме или в отчете, используя стандартный визуальный интерфейс поля ввода (FieldControl.dll), но эти данные не содержатся ни в одном источнике данных. Например, эти данные вводятся временно как параметры для промежуточных расчетов или настройки для формирования отчета.

Если нужно скопировать поле из описания некоторого типа объекта, используйте методы CreateByObjTypeGUID и CreateByObjTypeName. Эти методы позволяют создавать свободные поля любого типа (в том числе и типа FT_Enum и поля-ссылки любого уровня) при условии, что они есть в описании типа объекта.

Если нужно скопировать поле из существующего экземпляра объекта, используйте метод CreateByObject. Этот метод позволяют создавать свободные поля любого типа (в том числе и типа FT_Enum и поля-ссылки любого уровня) при условии, что они есть в описании типа и в коллекции запрошенных полей экземпляра объекта.

Если нужно создать свободное обыкновенное поле (не перечисляемое поле и не поле-ссылку) заданного типа и размера, используйте метод CreateByFieldType. Размер поля учитывается только для полей типа FT_String.

Если нужно создать свободное перечисляемое поле, используйте методы CreateByEnumGUID и CreateByEnumName.

Если нужно создать свободное поле-ссылку на тип объекта (ссылка может быть любого уровня), используйте методы CreateByClassifierGUID и CreateByClassifierName.

Если нужно создать свободное поле-ссылку на экземпляр объекта (ссылка может быть любого уровня), используйте метод CreateByClassifier.

Методы

CreateByObjTypeGUID. Создать поле по GUID типа объекта и полному имени поля.

Этот метод создает свободное поле, которое есть в описании некоторого типа объекта. При этом тип объекта задается с помощью идентификатора. Список всех типов объектов и их описание можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe). Например:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
 "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Идентификатор типа «Валюта»
 // Допустим, в этом типе определены поля
 // (1) «Буквенный код» типа FT_String
 // (2) «Пользователь» - ссылка на тип «Субъект»,
 //     в котором определено поле «Наименование»
 var guidCurrency = "2E65D62B-D904-4BC6-B18A-99111BD2E093";
 
 // Создать свободное поле копию поля 
 // «Буквенный код» в типе «Валюта»
 var oField1 = oFieldsCreator.CreateByObjTypeGUID(
    guidCurrency,"Буквенный код" );
 
 // Создать свободное поле копию поля
 // «Пользователь\Наименование» в типе «Валюта»
 var oField2 = oFieldsCreator.CreateByObjTypeGUID(
    guidCurrency,"Пользователь\\Наименование" );

В этом примере переменные oField1 и oField2 имеют тип интерфейса поля, причем многие их свойства (наименование, размер, тип, флаги и т. д.) совпадают со свойствами соответствующих полей из описания типа «Валюта». Для этих полей можно задавать и читать значение, но это значение не будет установлено для какого-либо экземпляра типа «Валюта», а будет храниться в памяти в течение времени жизни переменной поля.

CreateByObjTypeName. Создать поле по имени типа объекта и полному имени поля.

Этот метод создает свободное поле, которое есть в описании некоторого типа объекта. При этом тип объекта задается с помощью имени. Список всех типов объектов и их описание можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe). Например:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
 "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Допустим, что в типе «Валюта» определены поля
 // (1) «Буквенный код» типа FT_String
 // (2) «Пользователь» - ссылка на тип «Субъект»,
 //     в котором определено поле «Наименование»
 
 // Создать свободное поле копию поля
 // «Буквенный код» в типе «Валюта»
 var oField1 = oFieldsCreator.CreateByObjTypeName(
    "Валюта","Буквенный код" );
 
 // Создать свободное поле копию поля
 // «Пользователь\Наименование» в типе «Валюта»
 var oField2 = oFieldsCreator.CreateByObjTypeName(
    "Валюта","Пользователь\\Наименование" );

В этом примере переменные oField1 и oField2 имеют тип интерфейса поля, причем многие их свойства (наименование, размер, тип, флаги и т. д.) совпадают со свойствами соответствующих полей из описания типа «Валюта». Для этих полей можно задавать и читать значение, но это значение не будет установлено для какого-либо экземпляра типа «Валюта», а будет храниться в памяти в течение времени жизни переменной поля.

CreateByObject. Создать поле по экземпляру объекта и полному имени поля.

Метод создает свободное поле-копию поля в коллекции некоторого экземпляра объекта. Указывая имя поля, нужно учитывать, что оно должно присутствовать не только в описании типа, но и в коллекции запрошенных полей данного экземпляра объекта (см. свойство ConnectString в интерфейсе объекта). В качестве объекта-источника данных может выступать как глобальный (самостоятельный) объект, так и подобъект. Например:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
    "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Создаем объект-источник данных (типа "Типовая операция")
 var oDS = new ActiveXObject("RSCOMProvider.RSCOMObject");
 oDS.ConnectString=
   "<object all_fields=\"yes\" all_subobjects=\"yes\" rec_count=\"1\">"
 +  "<name>Типовая операция</name>"
 +  "<sub_object all_fields=\"yes\">"
 +     "<name>Типовые проводки</name>"
 +     "<classifier><name>Валюта</name>"
 +       "<field>Буквенный код</field>"
 +       "<field>Род (целая часть)</field>"
 +       "<classifier><name>Пользователь</name>"
 +         "<field>Наименование</field>"
 +       "</classifier>"
 +     "</classifier>"
 +  "</sub_object>"
 + "</object>"
 
 // Создаем свободное поле копию обыкновенного поля «Номер проводки»
 // в подобъекте «Типовые проводки» объекта «Типовая операция»
 var oFldNumber = oFieldsCreator.CreateByObject(
    oDS.SubObjects("Типовые проводки"), "Номер проводки"); 
 
 // Создаем свободное поле копию поля-ссылки первого рода 
 // «Валюта\Буквенный код» в подобъекте 
 // «Типовые проводки» объекта «Типовая операция»
 var oFldCurrency = oFieldsCreator.CreateByObject(
    oDS.SubObjects("Типовые проводки"), "Валюта\\Буквенный код");
 
 // Создаем свободное поле копию поля-ссылки второго рода 
 // «Валюта\Пользователь\Наименование» в подобъекте 
 // «Типовые проводки» объекта «Типовая операция»
 var oFldCurrencyUser = oFieldsCreator.CreateByObject(
    oDS.SubObjects("Типовые проводки"), "Валюта\\Пользователь\\Наименование");

CreateByFieldType. Создать поле данного типа и размера.

Создает свободное поле, которого нет в описании ни одного типа объекта. Входными параметрами является тип поля и его размер (для типа FT_String). Таким образом можно создавать только обычные поля не типа FT_Enum. Перечисляемые поля создаются методами CreateByEnumGUID и CreateByEnumName. Поля-ссылки могут создаваться всеми методами, кроме CreateByFieldType, CreateByEnumGUID и CreateByEnumName.

Например, нужно поместить на форму окно ввода даты. Для этого можно создать свободное поле типа FT_Date:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
 "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Константы для типов полей
 var FT_String = 6, FT_Date = 8;
 
 // Создаем свободное поле даты
 var oDate = oFieldsCreator.CreateByFieldType( FT_Date );
 
 // Создаем свободное поле строки длиной 100 символов
 var oStr100 = oFieldsCreator.CreateByFieldType( FT_String, 100 );

CreateByEnumGUID. Создать перечисляемое поле по GUID перечислителя.

Метод создает поле типа FT_Enum, то есть поле, значения которого задаются перечисляемым типом. При этом перечисляемый тип задается идентификатором. Все перечисляемые типы можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe). Например:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
 "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Идентификатор перечисляемого типа «Период»
 var guidPeriod = "35846990-873D-11D5-93B1-0060080B7F7D";
 
 // Создать свободное поле перечисляемого типа «Период»
 var oField = oFieldsCreator.CreateByEnumGUID( guidPeriod );

CreateByEnumName. Создать перечисляемое поле по имени перечислителя.

Метод создает поле типа FT_Enum, то есть поле, значения которого задаются перечисляемым типом. При этом перечисляемый тип задается наименованием. Все перечисляемые типы можно посмотреть в утилите «Редактор метаданных» (RSTypeInfoEditor.exe). Например:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
 "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Создать свободное поле перечисляемого типа «Период»
 var oField = oFieldsCreator.CreateByEnumName("Период");

CreateByClassifierGUID. Создать поле классификатора по GUID классификатора и имени поля в классификаторе.

Метод создает свободное поле-ссылку на некоторый тип объекта. Тип объекта задается идентификатором, значение которого передается первым параметром. Второй параметр задает имя поля-ссылки. Если имя поля не задано, создается поле-ссылка на идентификатор типа объекта. Если имя поля задано, оно должно быть описано в коллекции полей типа объекта. Если передать составное имя (включающее последовательно имена нескольких полей-ссылок, разделенные символом «\»), то можно создавать поля-ссылки второго и более уровней. Пример:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
 "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Идентификатор типа «Валюта»
 // Допустим, что в типе «Валюта» определены поля
 // (1) «Буквенный код» типа FT_String
 // (2) «Пользователь» - ссылка на тип «Субъект»,
 //     в котором определено поле «Наименование»
 var guidCurrency = "{2E65D62B-D904-4BC6-B18A-99111BD2E093}";
 
 // Создать поле-ссылку на идентификатор типа «Валюта»
 var oFldCurrencyID = oFieldsCreator.CreateByClassifierGUID(
    guidCurrency );
 
 // Создать поле-ссылку на «Буквенный код» типа «Валюта»
 var oFldCurrencyCode = oFieldsCreator.CreateByClassifierGUID(
    guidCurrency, "Буквенный код" );
 
 // Создать поле-ссылку второго уровня на «Наименование» типа 
 // «Пользователь», на который ссылается тип «Валюта»
 var oFldCurrencyUser = oFieldsCreator.CreateByClassifierGUID(
    guidCurrency, "Пользователь\\Наименование" );

CreateByClassifierName. Создать поле классфикатора по имени классификатора и имени поля в классификаторе.

Метод создает свободное поле-ссылку на некоторый тип объекта. Тип объекта задается наименованием, значение которого передается первым параметром. Второй параметр задает имя поля-ссылки. Если имя поля не задано, создается поле-ссылка на идентификатор типа объекта. Если имя поля задано, оно должно быть описано в коллекции полей типа объекта. Если передать составное имя (включающее последовательно имена нескольких полей-ссылок, разделенные символом «\»), то можно создавать поля-ссылки второго и более уровней. Пример:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
 "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Допустим, что в типе «Валюта» определены поля
 // (1) «Буквенный код» типа FT_String
 // (2) «Пользователь» - ссылка на тип «Субъект»,
 //     в котором определено поле «Наименование»
 
 // Создать поле-ссылку на идентификатор типа «Валюта»
 var oFldCurrencyID = oFieldsCreator.CreateByClassifierName(
    "Валюта" );
 
 // Создать поле-ссылку на «Буквенный код» типа «Валюта»
 var oFldCurrencyCode = oFieldsCreator.CreateByClassifierName(
    "Валюта", "Буквенный код" );
 
 // Создать поле-ссылку второго уровня на «Наименование» типа 
 // «Пользователь», на который ссылается тип «Валюта»
 var oFldCurrencyUser = oFieldsCreator.CreateByClassifierName(
    "Валюта", "Пользователь\\Наименование" );

CreateByClassifier. Создать поле-ссылку по интерфейсу объекта и имени поля в объекте.

Метод создает свободное поле-ссылку на некоторый экземпляр объекта. Экземпляр объекта задается указателем на интерфейс объекта, который передается первым параметром. Второй параметр задает имя поля-ссылки. Если имя поля не задано, создается поле-ссылка на идентификатор объекта. Если имя поля задано, оно должно быть описано в коллекции полей типа объекта и запрошено с сервера в коллекцию полей экземпляра (см. свойство ConnectString в интерфейсе объекта). Если передать составное имя (включающее последовательно имена нескольких полей-ссылок, разделенные символом «\»), то можно создавать поля-ссылки второго и более уровней. Пример:

 // Создаем объект-конструктор свободных полей
 var oFieldsCreator = new ActiveXObject( 
 "RSCOMProvider.RSCOMFreeFieldsCreator" );
 
 // Создаем объект-источник данных (типа "Типовая операция")
 var oDS = new ActiveXObject("RSCOMProvider.RSCOMObject");
 oDS.ConnectString=
   "<object all_fields=\"yes\" all_subobjects=\"yes\" rec_count=\"1\">"
 +  "<name>Типовая операция</name>"
 +  "<sub_object all_fields=\"yes\">"
 +     "<name>Типовые проводки</name>"
 +     "<classifier><name>Валюта</name>"
 +       "<field>Буквенный код</field>"
 +       "<field>Род (целая часть)</field>"
 +       "<classifier><name>Пользователь</name>"
 +         "<field>Наименование</field>"
 +       "</classifier>"
 +     "</classifier>"
 +  "</sub_object>"
 + "</object>"
 
 // Создать поле-ссылку на идентификатор объекта «Типовая операция»
 var oFldTypeOperID = oFieldsCreator.CreateByClassifier( oDS );
 
 // Создать поле-ссылку на идентификатор подобъекта 
 // «Типовая операция.Типовые проводки»
 var oFldTypeTransID = oFieldsCreator.CreateByClassifier( 
    oDS.SubObjects("Типовые проводки") );
 
 // Создать поле-ссылку на «Валюта\Буквенный код» подобъекта
 // «Типовая операция.Типовые проводки»
 var oFldCurrencyCode = oFieldsCreator.CreateByClassifier(
    oDS.SubObjects("Типовые проводки"), "Валюта\\Буквенный код" );
 
 // Создать поле-ссылку второго уровня на «Валюта\Пользователь\Наименование» 
 // подобъекта «Типовая операция.Типовые проводки»
 var oFldCurrencyUser = oFieldsCreator.CreateByClassifier(
    oDS.SubObjects("Типовые проводки"), 
    "Валюта\\Пользователь\\Наименование" );

Замечание об описании типа (TypeInfo)

Программный комплекс обеспечивает объектно-ориентированный доступ к базе данных. Вообще, вся функциональность системы реализована с помощью некоторого набора объектов. Каждый объект имеет свой тип. Поддерживается наследование типов. Описание типа объекта включает в себя:

  1. Описание полей. Поля представляют собой именованные атомарные свойства объекта, относящиеся к одному из встроенных типов. Помимо полей скалярных типов (логическое поле, строка, целые, дробные числа и т. п.) поддерживаются поля с перечисляемыми значениями и поля-ссылки. У каждого типа есть поле-идентификатор, представляющее собой 4-байтовое целое число, значение которого уникально для каждого экземпляра объекта.
  2. Описание ключей. Ключи представляют собой комбинации полей, по которым можно осуществлять быструю выборку данных с помощью методов GetData. У каждого типа объекта есть первичный ключ (первый в коллекции ключей), который построен по полю-идентификатору.
  3. Описание методов. Если поля представляют собой данные объекта, то методы реализуют функциональность (поведение) объектов данного типа. Иными словами, метода предоставляют программный интерфейс для работы с объектом данного типа. Существуют некоторое количество стандартных методов, обеспечивающих функциональность, не зависящую от конкретной предметной области (например, навигацию по списку или дереву объектов, изменение данных объекта, удаление объекта, добавление объекта, фильтрация, сортировка списка объектов, поиск объекта и т. д.). С другой стороны, есть методы, специфичные только для объектов определенного типа.
  4. Описание подобъектов. Типы объектов разделяются на глобальные (самостоятельные) и локальные (подобъекты) типы объектов. Экземпляры глобальных типов объектов создаются и существуют не зависимо от других типов, хотя и могут на них ссылаться. Подобъекты создаются и существуют только в контексте своего основного объекта. Можно воспринимать подобъекты, как сложные свойства объектов, в отличие от полей, представляющих собой простые атомарные свойства.

Список всех типов объектов, разделенный на модули, можно увидеть и редактировать в утилите «Редактор метаданных» (RSTypeInfoEditor.exe).

Замечание об обработке ошибок

Все реализации интерфейсов модуля RSComProvider используют стандартный механизм обработки ошибок, принятый для объектов автоматизации (Automation Objects). В случае возникновения ошибки, ее номер, описание и источник сохраняются в общем объекте последней ошибки (реализующем интерфейс IErrorInfo). Для ошибок операционной системы сообщение об ошибке будет запрошено у операционной системы, для ошибок программного комплекса — сформировано программным комплексом.

Для получения сообщения о последней ошибке можно использовать стандартную функцию Windows API — GetErrorInfo. Обычно, макро-языки имеют встроенные средства работы со стандартными ошибками автоматизации. Например, в JScript это реализовано с помощью исключений:

 // Сохраняем изменения на сервере
 try { ds.Run("Update"); }
 catch ( x )
 {
   WScript.Echo( x.description + " (" + x.number + ")." );
 }

В VBScript — конструкция On Error:

 ' Сохраняем изменения на сервере
 On Error Resume Next
 Call ds.Run("Update")
 If Err.Number <> 0 Then
   Call WScript.Echo( Err.Description + " (" + CStr(Err.Number) + ")." )
 End If
Личные инструменты
Пространства имён
Варианты
Действия
Навигация
Для разработки
Инструменты