Мельница данных  (05.12.2024)
Интерфейс IContext
01  IContext = interface(IDispatch)
02    ['{79847D79-A3BE-408F-B59F-662B91BC6350}']
03    function Handle: Integer;
04    function getName(ID: OleVariant): WideString;
05    function getDescription(ID: OleVariant): WideString;
06    function createDataSet(const TargetClassName: WideString):
07      IContextDataSet;
08    function executeMethod(const ClassName: WideString;
09      const MethodName: WideString;
10      Params: OleVariant): OleVariant;
11    function executeReport(const ClassName: WideString;
12      const TemplateName: WideString;
13      Params: OleVariant): IDispatch;
14    function getPropValue(const ClassName: WideString;
15      const PropName: WideString;
16      const ID: OleVariant): OleVariant;
17    procedure setPropValue(const ClassName: WideString;
18      const PropName: WideString;
19      const ID: OleVariant; Value: OleVariant);
20    function select(const ClassName: WideString;
21      QueryItems: OleVariant): IDispatch;
22    function enumerationItem(ItemIdentifier: OleVariant): WideString;
23    function getClass(const ClassName: WideString): WideString;
24    function createGUID: WideString;
25    procedure processStart(const Description: WideString;
26      ItemCount: Integer);
27    procedure processStep;
28    procedure processStop;
29    function PlaceDataSet(const Range: IDispatch;
30      const DataSet: IContextDataSet;
31      ShiftRows: WordBool; ShiftColumns: WordBool): Integer;
32    procedure DebugString(const Message: WideString);
33    procedure ExportObject(var Document: OleVariant; const ID: WideString;
34      const ClassID: WideString);
35    function callRoutine(const ClassName, RoutineName: WideString;
36      var RetValue: OleVariant; const ScriptPart: OleVariant): WordBool;
37    function getOleObject(const ClassID, AccessibleFileName: WideString): IDispatch;
38    function getResource(const Name: WideString): WideString;
39    function getTempFileName(const Extension: WideString): WideString;
40    function selectVaue(const ClassDomain: WideString;
41      const ExpressionContext: IContextExpressionInfo;
42      var Value: OleVariant): WordBool;
43    procedure raiseManagedException(const ExceptionMessage: WideString);
44    function getCRC(Data: OleVariant): WideString;
45    function downloadData(const Host: WideString; const Url: WideString;
46      const UserName: WideString; const Password: WideString;
47      NegotiateAuth: WordBool; PostData: OleVariant;
48      const PostContentType: WideString; PostDataIsBinary: WordBool;
49      CanCache: WordBool; NewSession: WordBool; TimeOut: Integer): OleVariant;
50    function createBinaryData: IDispatch;
51    function BinaryToBitmap(const Data: IDispatch): IDispatch; safecall;
52    function editValues(const ValuesList: WideString; const Title: WideString;
53      UseTabs: WordBool; HideOKButton: WordBool;
54      const ScriptPart: OleVariant): WordBool;
55    function MsgBox(const Prompt: WideString; Buttons: LongWord;
56      const Title: WideString;
57      const HelpFile: WideString; Context: LongWord): Integer;
58    function ShowMsgBox(const Prompt: WideString; Buttons: LongWord;
59      const Title: WideString;
60      const HelpFile: WideString; Context: LongWord): Integer;
61    function buildNamedFile(const Data: IDispatch; const StoredFileName: WideString;
62                            Propmpt: WordBool; Compress: WordBool): IDispatch;
63    procedure parseNamedFile(const NamedFile: IDispatch; out FileName: OleVariant;
64                             out Data: OleVariant);
65    procedure showView(const ViewName: WideString; Key: OleVariant;
66                       const DetailPropertyName: WideString);
67    procedure showDataSet(const DataSet: ContextDataSet; const Caption: WideString;
68                          ColumnCaptions: OleVariant; ColumnOnChangeHandlers: OleVariant;
69                          TakeActionsFromView: OleVariant);
70    function executeConsoleProcess(const CommandLine: WideString; MaxDuration: Integer;
71                                   const OutputData: OleVariant): Integer;
72    function createRaster: IDispatch;
73    function createZIPArchive: IDispatch;
74    function ConvertExcel(Source: OleVariant; const Format: WideString): IDispatch;
75    property ContextObject: IDispatch;
76    property Language: WideString;
77    property UserName: WideString;
78    property NegotiateAuth: WordBool;
79    property Variable[const Name: WideString; Persistent: WordBool]: OleVariant;
80  end;

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

  • Функция Handle возвращает дескриптор главного окна приложения.
  • Функция getName возвращает имя объекта по его идентификатору.
  • Функция getDescription возвращает наименование объекта по его идентификатору.
  • Функция createDataSet создает набор данных, основанный на экземплярах класса, имя которого передано как параметр. Возвращаемый объект реализует интерфейс IContextDataSet.
  • Функция executeMethod осуществляет вызов метода с параметрами. Имя класса передается в параметре ClassName, имя вызываемого метода - в параметре MethodName. Если вызываемый метод явяется функцией, то результат ее выполнения возвращается как результат вызова executeMethod. Параметры вызова метода передаются через параметр Params следующим образом:
    • Для методов класса без параметров можно передавать любое значение, например, Null.
    • Для методов класса, имеющих один параметр, значение Params есть значение этого единственного параметра.
    • Для методов класса, имеющих более одного параметра, значение Params есть массив значений параметров.
      Пример
      VBScript, VBA LValue = executeMethod("TObject", "Round", Array(10.24, 1))
      JScript LValue = executeMethod("TObject", "Round", new Array(10.24, 1));
      Object Pascal LValue := executeMethod('TObject', 'Round', VarArrayOf([10.24, 1]));
    • Для методов экземпляра без параметров значение Params есть идентификатор объекта, для которого вызывается метод.
    • Для методов экземпляра, имеющих параметры, значение Params есть массив значений параметров. При этом первым элементом массива является идентификатор объекта, для которого вызывается метод.
      Пример
      VBScript, VBA executeMethod "TObject", "MergeTo", Array(LOldObject, LNewObject)
      JScript executeMethod("TObject", "MergeTo", new Array(LOldObject, LNewObject));
      Object Pascal executeMethod('TObject', 'MergeTo', VarArrayOf([LOldObject, LNewObject]));
  • Функция executeReport осуществляет вызов отчета с параметрами. Имя класса передается в параметре ClassName, имя вызываемого метода - в параметре TemplateName. Параметры вызова передаются в параметре Params аналогично вызову executeMethod. В результате вызова функции возвращается ссылка на рабочую книгу Microsoft Excel, документ Microsoft Word и так далее. Судьба приложения, в рамках которого создан возвращенный объект, остается на усмотрение вызывающей стороны. Если вызывающая сторона предполагает взаимодействие объекта с пользователем, то необходимо обеспечить видимость объекта-приложения (Application.Visible := True;). В противном случае необходимо закрыть приложение после освобождения объекта документа (Application.Quit).
  • Функция getPropValue возвращает значение свойства объекта. Имя класса, имя свойства и идентификатор объекта задаются в параметрах.
  • Процедура setPropValue устанавливает значение свойства объекта в значение, заданное параметром Value. Для очистки значения можно использовать пустую строку или значение Null. Имя класса, имя свойства и идентификатор объекта задаются в параметрах.
  • Функция select возвращает ссылку на XML-документ, содержащий в корневом элементе элементы, представляющие собой записи набора данных на основе класса ClassName (с полями, разнесенными по элементам), определяемого структурой параметра QueryItems.
  • Функция enumerationItem возвращает идентификатор элемента перечисления по имени.
    Пример
    VBScript, VBA LItemID = enumerationItem("rsReplicatableMetadata")
    JScript LItemID = enumerationItem("rsReplicatableMetadata");
    Object Pascal LItemID := enumerationItem('rsReplicatableMetadata');
  • Функция getClass возвращает идентификатор объекта типа Класс TClass (Классы) по имени.
    Пример
    VBScript, VBA LClassID = getClass("TDocumentType")
    JScript LClassID = getClass("TDocumentType");
    Object Pascal LClassID := getClass('TDocumentType');
  • функция createGUID является оберткой над функцией Windows API CoCreateGuid. Возвращает сгенерированный глобально-уникальный идентификатор, преобразованный в строку.
  • процедура processStart информирует систему о необходимости показать окно выполнения длительного процесса. Текст, описывающий процесс (он появляется в показываемом окне) задается параметром Description. В случае, если есть возможность определить количество "шагов" процесса, то это количество необходимо передать в параметре ItemCount. В случае, если параметр ItemCount больше нуля, окно выполнения будет снабжено индикатором прогресса. Если значение ItemCount равно нулю, то окно появится без индикатора прогресса. Если значение ItemCount меньше нуля, то решение о появлении окна будет принято системой самостоятельно на основании загрузки процессора и окно процесса не появится, если процесс завершится достаточно быстро.
  • процедура processStep информирует систему о завершении очередного "шага" процесса, что найдет отражение в индикаторе прогресса окна выполнения длительного процесса, если таковые случатся.
  • процедура processStop информирует систему о завершении длительного процесса, что приведет к закрытию окна выполнения длительного процесса, если таковое случится.
  • функция PlaceDataSet осуществляет перенос данных из набора, задаваемого параметром DataSet в некоторое место документа Microsoft Office. Место назначения определяется параметром Range следующим образом:
    Microsoft Word
    • Объект Range. По месту расположения этого объекта будет создана таблица (Table), в которой будут размещены данные из набора.
      Пример
      PlaceDataSet ThisDocument.Bookmarks("BookMarkName").Range, LDataSet
      Пример
      PlaceDataSet Selection.Range, LDataSet
    • Объект Document. В самом начале переданного документа будет создана таблица (Table), в которой будут размещены данные из набора.
      Пример
      PlaceDataSet ThisDocument, LDataSet
    Microsoft Excel
    • Объект Range. По месту расположения этого объекта (диапазона) будут размещены данные из набора. Если параметр ShiftRows задан и равен True, то заданный диапазон будет расширен вниз на необходимое количество строк, и информация, лежащая ниже переданного диапазона, будет по-прежнему лежать ниже. Если нет, то она (скорее всего) будет затёрта данными набора. Если параметр ShiftColumns задан и равен True, то этот диапазон будет расширен вправо на необходимое количество столбцов, и информация, лежащая правее переданного диапазона, будет по-прежнему лежать правее. Если нет, то она (скорее всего) будет затёрта данными набора.
      Пример
      PlaceDataSet Range("C4"), LDataSet
    • Объект WorkSheet. На переданном листе будут размещены данные из набора.
      Пример
      PlaceDataSet WorkSheets("HiddenSheet"), LDataSet
    Функция возвращает количество размещенных записей.
  • процедура DebugString выводит переданную в качестве аргумента строку в отладочный монитор.
  • процедура ExportObject осуществляет экспорт информации об объекте, задаваемом параметром ID в XML-документ, передаваемый в параметре Document. Если объект документа не был создан, то он создается автоматически. Если документ не имеет корневого узла, он будет создан автоматически.
    Пример
    01set LDataSet = CreateDataSet("TSecurityAccount")
    02
    03LDataSet.AddQueryItem qpWhat, "ID"
    04
    05set LDocument = CreateObject("Msxml2.DOMDocument.4.0") 'Не обязательно.
    06
    07while not LDataSet.Eof
    08  ExportObject LDocument, LDataSet.Field("ID")
    09  LDataSet.Next
    10wend
    11
    12LDocument.save "c:\RolesAndUsers.xml"
          
  • Функция callRoutine осуществляет вызов подпрограммы. Параметры будут запрошены у пользователя обычным порядком (с показом формы задания параметров, отработки ее скрипта и т. д.). Имя класса передается в параметре ClassName, имя вызываемой подпрограммы - в параметре RoutineName. Если пользователь разрешил выполнение подпрограммы (либо для выполнения не требовалось разрешения пользователя), функция вернет True, иначе False. Значение, возвращаемое подпрограммой, может быть возвращено через необязательный параметр RetValue. Через значение необязательного параметра ScriptPart можно передать скрипт на языке VBScript, который будет "приклеен" сверху к скрипту формы параметров вызываемой подпрограммы.
  • Функция getOleObject возвращает ссылку на Ole-объект с идентификатором класса, переданном в параметре ClassID. Объект создается на основе библиотеки кода, сохраненной в доступном файле с именем, заданным параметром AccessibleFileName. Регистр символов имени доступного файла важен.
  • Функция getResource возвращает значение ресурсной строки по имени ресурса (элемента перечислимого домена Resource strings или перевода (объекта класса TLanguageTranslation).
    Пример
    MsgBox getResource("rssMyErrorMessage")
          
  • Функция getTempFileName возвращает сгенерированное системой имя временного файла с расширением, переданным в параметре Extension.
  • Функция selectVaue позволяет пользователю выбрать значение на основе ссылочного домена, имя которого передается в параметре ClassDomain. Вызывающая сторона может реализовать интерфейс IContextExpressionInfo, через который передается информация о контексте вызова для интерпретации выражений условий отбора, и передать ссылку на него через параметр ExpressionContext. Выбранное значение передается в обе стороны через параметр Value. Если пользователь подтвердил выбор значения, функция возвращает значение True, и устанавливает значение параметра Value, равное идентификатору выбранного пользователем объекта. Если пользователь отказался от выбора, функция возвращает значение False.
  • Процедура raiseManagedException возбуждает управляемую исключительную ситуацию с сообщением для пользователя, заданным параметром ExceptionMessage.
  • Функция getCRC возвращает шестнадцатиричное представление контрольной суммы переданных в параметре Data данных. Параметр может быть
    • Объектом, реализующим интерфейс IBinaryData
    • Объектом, реализующим интерфейс IStream
    • Объектом, реализующим интерфейс ISequentialStream
    • Объектом, реализующим интерфейс IFile объектной модели FileSystemObject
    • Строкой данных. Строка будет преобразована в байты в соответствии с кодировкой UTF-8.
  • Функция downloadData осуществляет обращение к указанному ресурсу по протоколу http (https), и возвращает ответ сервера в виде объекта, реализующего интерфейс IBinaryData. Параметр Host определяет http-сервер, параметр Url - Url, к которому будет происходить обращение. Параметры UserName и Password определяют имя пользователя и пароль, если http-сервер требует авторизовать пользователя. Параметр NegotiateAuth устанавливает режим аутентификации. (Basic или Negotiate). Параметры PostData, PostContentType и PostDataIsBinary определяют содержимое тела POST-запроса (если не определено, функция отправит GET-запрос). Параметр CanCache позволяет использовать локальный кеш http-ответов. Параметр NewSession требует принудительного создания новой сессии при вызове функции. Параметр TimeOut определяет максимальное время ожидания ответа в секундах.
  • Функция createBinaryData создает пустой объект, реализующий интерфейс IBinaryData.
  • Функция BinaryToBitmap  конвертирует переданный графический файл в формат BMP. Объекты во входном и выходном параметрах должны реализовывать интерфейс IBinaryData.
  • Функция editValues создает и показывает форму редактирования группы значений. Параметр ValuesList содержит идентификатор объекта класса TObjectList. Этот список содержит ссылки на редактируемые значения (объекты класса TTypedValue), и командные кнопки формы (объекты класса TTypedValueButton). Параметр Title определяет заголовок формы, параметр UseTabs определяет, будут ли показаны закладки на форме редактирования. Параметр HideOKButton позволяет скрыть кнопку "OK" на показываемой форме. Параметр ScriptPart определяет скрипт показываемой формы.

    Пример
    01  LValue1 = executeMethod ("TTypedValue", "CreateStrValue", _
    02    Array("Value1", "Первый параметр", Null, Null, _
    03    "TLongString", Null, Null, Null, Null, Null, "Значение по  умолчанию первого параметра"))
    04  LValue2 = executeMethod ("TTypedValue", "CreateStrValue", _
    05    Array("Value2", "Второй параметр", Null, Null, _
    06    "TLongString", Null, Null, Null, Null, Null, "Значение по  умолчанию второго параметра"))
    07
    08  LValues = executeMethod("TObjectList", "CreateFromString", _
    09    LValue1 & ";" & LValue2)
    10
    11  if editValues(LValues, "Введите два строковых значения, друзья", True, False, "") then
    12    MsgBox getPropValue("TTypedValue", "StrValue", LValue1) & _
    13      " " & _
    14      getPropValue("TTypedValue", "StrValue", LValue2)
    15  end if
    16
    17  executeMethod "TObject", "Destroy", LValues
    18  executeMethod "TObject", "Destroy", LValue1
    19  executeMethod "TObject", "Destroy", LValue2
            

    Пример
    01  LScriptPart =  "Buttons(""NextButton"").Enabled = ParentForm.NavigatorCanNext" & Chr(10) & _
    02    "Buttons(""PrevButton"").Enabled = ParentForm.NavigatorCanPrevious"
    03
    04  LValue1 = executeMethod ("TTypedValue", "CreateStrValue", _
    05    Array("Value1", "Первый параметр", Null, Null, "TLongString", Null, Null, Null, Null, Null, _
    06    "Значение по  умолчанию первого параметра"))
    07  LValue2 = executeMethod ("TTypedValue", "CreateStrValue", _
    08    Array("Value2", "Второй параметр", Null, Null, "TLongString", Null, Null, Null, Null, Null, _
    09    "Значение по  умолчанию второго параметра"))
    10
    11  LNextButton = executeMethod ("TTypedValueButton", "Create", Array("NextButton", "Вперед!", _
    12    Null, Null, Null, Null, 0, Null, Null, _
    13    "ParentForm.NavigatorNext"  & Chr(10) & LScriptPart, enumerationItem("scPublic"), 1, Null))
    14
    15  LPrevButton = executeMethod ("TTypedValueButton", "Create", Array("PrevButton", "Назад!", _
    16    Null, Null, Null, Null, 1, Null, Null, _
    17    "ParentForm.NavigatorPrevious" & Chr(10) & LScriptPart, enumerationItem("scPublic"), 1, Null))
    18
    19  LValues = executeMethod("TObjectList", "CreateFromString", _
    20    LValue1 & ";" & LValue2 & ";" & LNextButton & ";" & LPrevButton)
    21
    22  if editValues(LValues, "Введите два строковых значения, друзья", True, True, LScriptPart) then
    23    MsgBox getPropValue("TTypedValue", "StrValue", LValue1) & _
    24      " " & _
    25      getPropValue("TTypedValue", "StrValue", LValue2)
    26  end if
    27
    28  executeMethod "TObject", "Destroy", LValues
    29  executeMethod "TObject", "Destroy", LValue1
    30  executeMethod "TObject", "Destroy", LValue2
    31  executeMethod "TObject", "Destroy", LNextButton
    32  executeMethod "TObject", "Destroy", LPrevButton
            

  • Функции MsgBox и ShowMsgBox (это синонимы одной точки входа) полностью аналогичны функции Basic MsgBox по поведению и набору параметров.
  • Функция buildNamedFile формирует значение типа "Именованный файл" на основе объекта, реализующего интерфейс IBinaryData (параметр Data) и информации об имени и параметрах именованного файла.
  • Процедура parseNamedFile разбирает значение типа "Именованный файл". Выходной параметр FileName будет содержать сохраненное имя файла, выходной параметр Data - объект, реализующего интерфейс IBinaryData и содержащий данные именованного файла.
  • Свойство ContextObject позволяет получить ссылку на этот же самый контекстный объект.
  • Свойство UserName позволяет получить логин текущего пользователя.
  • Свойство NegotiateAuth позволяет получить признак доменной аутентификации пользователя.
  • Свойство Language позволяет получать и устанавливать текущий языковой контекст, в котором будут выполняться обращения к БД. Значение свойства либо пустая строка (используется язык БД по умолчанию), либо имя объекта класса TLanguage
  • Свойство Variable позволяет сохранять и получать произвольные значения, которые могут хранится постоянно (в реестре) или только в текущем сеансе, в зависимости от параметра Persistent.
    Пример
    1'сохранить на время текущего сеанса значение в переменную с именем SameVariableName
    2Variable("SameVariableName", False) = "Value"
    3
    4'получить значение переменной с именем SameVariableName хранимой в текущем сеансе
    5LValue = Variable("SameVariableName", False)
          
  • Процедура showView осуществляет показ в модальном окне представления с именем ViewName. С помощью параметров DetailPropertyName и Key можно наложить на представление дополнительное условие отбора.