Управление серверами Domino на IBM i при помощи программных интерфейсов

В данной статье описывается набор программных интерфейсов (API), которые обеспечивают программный доступ к серверам Domino на системе IBM i и управление ими. Статья содержит примеры исходного кода, демонстрирующие использование интерфейсов для выполнения этих задач.

Бин Ян, инженер-программист, IBM

Бин Ян (Bin Yang) в настоящее время является членом IBM Lotus Domino for IBM i и занимается главным образом производительностью Lotus Domino. Связаться с ним можно по адресу yangbin@cn.ibm.com. Написал и проверил раздел iSeries данной статьи.



Шуан Хун Ван, программист-консультант, IBM

Шуан Хун Ван (Shuang Hong Wang) – фотографияШуан Хун Ван (Shuang Hong Wang) с 2005 года занимается разработкой и поддержкой клиентов, использующих Lotus Domino на IBM i. В настоящее время является техническим руководителем отдела предложений продуктов Lotus на IBM i.



22.08.2012

Введение

Многие пользователи запускают свои серверы Domino на IBM i. В одном разделе IBM i можно установить несколько версий Domino и настроить несколько разделов (экземпляров) каждой версии Domino, тогда как на других платформах обычно можно установить и настроить только один экземпляр сервера Domino. Это позволяет использовать платформу IBM i на предприятиях, которым необходимо развернуть несколько серверов Domino.

Lotus Domino Administrator является основным средством, предоставляемым IBM для управления и эксплуатации серверов Domino на платформах различного типа, включая IBM i. Учитывая специфику использования Domino на IBM i, IBM предоставляет в распоряжение пользователя несколько команд Domino CL (язык управления Domino). При помощи этих команд можно просматривать информацию обо всех серверах Domino, настроенных в разделе IBM i, запускать и останавливать сервер (серверы), следить за состоянием сервера, просматривать и управлять всеми заданиями сервера, просматривать и редактировать файл Notes.ini, просматривать журнал консоли и т.д. Некоторым ИТ-подразделениям помимо ручного управления при помощи CL-команд требуется программное управление серверами Domino. Например, им может понадобиться автоматически останавливать все активные серверы Domino по пятницам в 5:00 для выполнения резервного копирования и сжатия всех баз данных NSF с целью освобождения дискового пространства. Domino на IBM i предоставляет набор программных интерфейсов для решения подобных задач. Этот набор программных интерфейсов IBM i позволяет просматривать список всех серверов Domino, извлекать информацию с сервера, читать или записывать файл Notes.ini и т.д. Используя программные интерфейсы Domino для IBM i вместе с некоторыми CL-командами Domino, можно легко выполнить вышеперечисленные задачи по автоматическому управлению серверами Domino. Эти уникальные интерфейсы Domino для IBM i отличаются от интерфейсов Lotus C для Notes/Domino, которые используются для создания и удаления баз данных NSF, чтения и редактирования документов в базе данных NSF, создания и использования индексов/представлений и т.д.

В данной статье приводятся краткое описание уникальных интерфейсов Domino для IBM i, несколько примеров их применения и советы по их использованию. Эти специфичные для IBM i интерфейсы включены в базовый вариант лицензионной программы Lotus Domino on IBM i License Program.

Для работы с примерами данной статьи необходимо наличие базовых знаний Lotus Domino; примеры основаны на системе Lotus Domino 8.5.1, выполняющейся на платформе IBM i версии 5 редакции 4 (V5R4).

В таблице 1 перечислены уникальные интерфейсы Domino for IBM i.

Таблица 1. Список функций интерфейсов
Имя функции интерфейсаОписание
QnninListDominoServers Получить список серверов Domino, установленных на системе.
QnninRtvDominoServerI Получить специфичную информацию о сервере Domino.
QnninRtvDominoServerAttr Извлечь специфичную информацию о сервере Domino. Эта функция может извлечь всю информацию, предоставляемую QnninRtvDominoServerI, и дополнительную информацию на основании имени формата параметра.
QnninSetDominoEnv Установить текущую рабочую среду выполнения заданий в состояние, позволяющее вызывать интерфейс NotesInitExtended для конкретного сервера Domino. Это избавляет вызывающую сторону от необходимости знать специфичную информацию о каждом сервере Domino при инициализации среды Notes API.
QnninGetDominoEnv Получить информацию о текущей среде заданий сервера Domino.
QnninListDominoRlsI Получить всю информацию о версии Domino, установленной на данной системе.
QnninGetIniValue и QnninGetIniValuez Получить значение переменной ini из файла notes.ini сервера Domino.
QnninSetIniValue и QnninSetIniValuez Установить значение переменной ini в файле notes.ini сервера Domino.
QnninGetServerDocItem и QnninGetServerDocItemz Получить значение элемента из документа сервера Domino, найденного в каталоге Domino.
QnninSetServerDocItem и QnninSetServerDocItemz Изменить или установить значение элемента в документе сервера Domino, найденного в каталоге Domino.

Использование уникальных программных интерфейсов Domino для IBM i

В данном разделе рассматриваются некоторые из уникальных интерфейсов Domino для IBM i и приводятся примеры программ на языке C, демонстрирующих использование этих интерфейсов. Эти интерфейсы размещаются в сервисной программе QNNINLDS.SRVPGM библиотеки QNOTES. Большинство этих интерфейсов не имеет аналогов среди CL-команд, за исключением интерфейса QnninSetDominoEnv, который имеет аналогичную команду под названием SETDOMENV.

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

Листинг 1. Основные команды компиляции
ADDLIBLE QNOTES
CRTCMOD lib_name/mod_name lib_name/QCSRC output(*PRINT)
CRTPGM  lib_name/mod_name

Список серверов Domino (QnninListDominoServers)

Для управления серверами Domino важно знать их имена. Интерфейс QnninListDominoServers позволяет легко извлечь имена всех серверов Domino, настроенных в системе. Имея этот список имен, можно управлять серверами Domino или получать к ним доступ посредством других интерфейсов.

Параметры QnninListDominoServers:

  1. Output;Char(*). Этот буфер хранит список серверов Domino. Имена серверов возвращаются в CCSID текущего задания. Формат выходного буфера определяется третьим параметром (Format name).
  2. Длина буфера данных
    Input; Binary(4). Длина буфера данных. Если длина достаточно велика, список настроенных серверов Domino будет помещаться в область буфера данных. В противном случае будут возвращаться ошибки или неполные данные.
  3. Имя формата
    Input;Char(8). Имя формата, используемого для возврата всех настроенных серверов Domino. В настоящее время единственным поддерживаемым форматом является DSRV0100 (см. таблицу 2).
  4. Код ошибки
    I/O;Char(*). Возвращает информацию об ошибке. Если этот параметр опущен, в приложение будут выдаваться диагностические сообщения.
Таблица 2. Формат DSRV0100
СмещениеТипПолеОписание поля
0x00 Binary(4) Возвращаемое число байтов Длина данных, которые могут быть возвращены
0x04 Binary(4) Доступное число байтов Длина данных, возвращаемых в этой структуре
0x08 Binary(4) Смещение записи сервера Смещение начала первой записи сервера
0x0C Binary(4) Число возвращенных записей сервера Число возвращенных записей сервера в поле "Записи сервера".
0x10 Binary(4) Длина записи сервера Длина каждой возвращенной записи сервера. Она должна быть равна 255 байтам
0x14 Char(*) Записи сервера Начало возвращенных записей сервера

QnninListDominoData_t – это предопределенная структура данных в заголовке файла H/QNNINLDS библиотеки QNOTES, которая может использоваться при вызове QnninListDominoServers API.

Листинг 2. Структура QnninListDominoData
typedef struct QnninListDominoData {                                 
     int      BytesReturned;         /* Возвращаемое число байтов            */
     int      BytesAvailable;        /* Доступное для возврата число байтов  */
     int      OffsetToServers;       /* Смещение записей сервера             */
     int      NumberOfServers;       /* Количество записей сервера           */
     int      LengthOfEntry;         /* Длина каждой записи сервера          */
}  QnninListDominoData_t;

В приведенном ниже исходном коде представлен пример получения списка всех имен серверов Domino данной системы. Сначала мы определяем структуру my_sturct_t, которая содержит QnninListDominoData_t и массив строк для хранения имен серверов Domino. Тип переменной svr_list, являющейся первым параметром интерфейса QnninListDominoServers, определен как my_struct_t. После вызова этого интерфейса имена серверов могут быть возвращены в svr_list. Обратите внимание, что длина возвращаемого имени сервера составляет 255 байтов, и эта строка не завершается значением NULL. Если она меньше 255 байтов, добавляются пробелы. Операторы for в этом примере используются для перечисления всех возвращенных имен серверов Domino без пробелов.

Листинг 3. Пример кода для QnninListDominoServers
#include "QNNINLDS.H"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <qusec.h>

typedef  struct my_struc_t {
  QnninListDominoData_t   hdr;
  char                    server_names[255*100];
}  my_struct_t;

int  main(int argc, char * argv[])
{
  my_struct_t  svr_list;
  Qus_EC_t     error_code;
  int          lcl_NumberOfServers, lcl_LengthOfEntry, lcl_OffsetToServers;
  char         * svr_ptr, * svr_entry;
  int          i,j;

  memset((char *)&error_code, 0, sizeof(error_code));
  error_code.Bytes_Provided  = sizeof(error_code);
  QnninListDominoServers((void *)&svr_list,  sizeof(svr_list), "DSRV0100", &error_code);
  if (error_code.Bytes_Available)  /* Проверить error_code. */
  {
     printf("Error retrieving the list of Domino servers.\n");
     return(-1);
  }

  lcl_NumberOfServers = svr_list.hdr.NumberOfServers;
  lcl_LengthOfEntry = svr_list.hdr.LengthOfEntry;
  lcl_OffsetToServers = svr_list.hdr.OffsetToServers;

  for (i=1; i <= lcl_NumberOfServers; i++)  /* Список всех серверов domino. */
  {
     svr_ptr = ((char *)&svr_list) + lcl_OffsetToServers + lcl_LengthOfEntry*(i-1) + 254;
     svr_entry = svr_ptr-254;
     j=254;
     while(*svr_ptr == ' '& j>=0)  /* Удалить пробел из возвращенного имени сервера. */
     {
         *svr_ptr = '\0';
         j--;
         svr_ptr--;
     }
     printf("Server names: %s\n", svr_entry);

  }
  return(0);
}

Извлечение атрибутов сервера Domino (QnninRtvDominoServerAttr)

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

Параметры QnninRtvDominoServerAttr:

  1. Буфер данных для атрибутов сервера Domino
    Output;Char(*). Этот буфер хранит атрибуты сервера Domino. Формат выходного буфера определяет пятый параметр (Format name).
  2. Длина буфера данных
    Input;Binary(4). Длина буфера данных. Убедитесь в том, что он имеет достаточную длину.
  3. Имя сервера
    Input;Char(255). Имя сервера Domino, которое возвращает интерфейс QnninListDominoServers, для извлечения информации. Это поле дополняется пробелами и не завершается символом null.
  4. Длина имени сервера
    Input;Binary(4). Длина имени сервера. Всегда должно быть равно 255 байтам. Если реальная длина имени сервера меньше 255 байтов, поле дополняется пробелами.
  5. Имя формата
    Input;Char(8). Имя формата для извлечения различных атрибутов сервера Domino. DATR0100, DATR0200. См. таблицу 3 для формата DATR0100.
  6. Код ошибки
    I/O;Char(*). Возвращает информацию об ошибке для вызывающей стороны.
Таблица 3. Буфер атрибутов DATR0100
СмещениеТипПоле
0x00 Binary(4) Возвращаемое число байтов
0x04 Binary(4) Доступное число байтов
0x08 Binary(4) Первичный тип сервера Domino
0x0C Binary(4) Вторичный тип сервера Domino
0x10 Binary(4) Количество активных заданий в подсистеме
0x14 Binary(4) Смещение пути к каталогу данных
0x18 Binary(4) Длина пути к каталогу данных
0x1C Binary(4) Смещение пути к каталогу исполняемых файлов
0x20 Binary(4) Длина пути к каталогу исполняемых файлов
0x24 Char(20) Описание подсистемы
0x38 Char(10) Имя библиотеки
0x42 Binary(1) Состояние сервера
0x43 Binary(1) Автоматический запуск с серверами TCP/IP
0x44 Binary(4) Номер раздела
0x48 Binary(4) Смещение обобщенной информации
0x4C Binary(4) Длина обобщенной информации
0x50 Char(16) Версия Domino Server(VRM)
* Char(*) Переменные данные

Подробная информация о форматах DATR0100 и DATR0200 приведена в "Руководстве разработчика приложений Lotus Domino for i5/OS" (см. раздел Ресурсы).

QnninRtvDominoData_t – это предопределенная структура данных в файле заголовка H/QNNINLDS библиотеки QNOTES, которую можно использовать при вызове интерфейса QnninRtvDominoserverAttr. QnninRtvDominoData_t содержит данные в формате DATR0100.

Листинг 4. Структура QnninRtvDominoData
/*Формат DATR0100*/
typedef struct QnninRtvDominoData {
     int      BytesReturned;         /* Возвращаемое число байтов            */
     int      BytesAvailable;        /* Доступное для возврата число байтов  */
     int      PrimaryType;           /* Тип сервера Domino                   */
     int      SecondaryType;         /* Вторичный тип сервера                */
     int      ActiveJobsInSbs;       /* Количество активных заданий в        */
                                     /* подсистеме                           */
     int      OffsetToPath;          /* Смещение пути к каталогу данных      */
     int      LengthOfPath;          /* Длина пути к каталогу данных         */
     int      OffsetToRunPath;       /* Смещение пути исполнения             */
     int      LengthOfRunPath;       /* Длина пути исполнения                */
     char     SubsystemName[20];     /* Имя описания подсистемы              */
     char     RunTimeLibrary[10];    /* Библиотека, в которой найдены        */
                                     /* подпрограммы времени                 */
                                     /* исполнения сервера                   */
     char     Status;                /* Состояние сервера                    */
     char     TCPAutoStart;          /* Автозапуск сервера на STRTCP         */
     int      PartitionNumber;       /* Номер раздела svr                    */
     int      OffsetToInfo;          /* Смещение обобщенной информации       */
     int      LengthOfInfo;          /* Длина обобщенной информации          */
     char     ServerVRM[16];         /* VRM сервера Domino                   */
}  QnninRtvDominoData_t;

Приведенный ниже пример исходного кода извлекает информацию о сервере Domino. В данном примере мы вызываем интерфейс QnninRtvDominoServerAttr с именем формата DATR0100 и извлекаем название подсистемы сервера, библиотеку системы времени исполнения, версию сервера и состояние сервера.

Листинг 5. Пример кода для QnninRtvDominoServerAttr
#include "QNNINLDS.H"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <qusec.h>

int  main(int argc, char * argv[])
{
     QnninRtvDominoData_t   svr_attr;
     Qus_EC_t     error_code;
     char         server[]="D851";
     char *       status;
     char         sbsname[21], runtimelib[11],svrm[17];
     int          i;

   
     memset((char *)&error_code, 0, sizeof(error_code));
     error_code.Bytes_Provided  = sizeof(error_code);
     QnninRtvDominoServerAttr((void *)&svr_attr, sizeof(svr_attr), server, sizeof(server),
     "DATR0100",&error_code);

     if (error_code.Bytes_Available)  /* Проверка error_code */
     {
        printf("Error retrieving the attributes of Domino server. \n");
        return(-1);
     }

     sbsname[20]='\0';
     memcpy(sbsname, svr_attr.SubsystemName,sizeof(svr_attr.SubsystemName));
     runtimelib[10]='\0';
     memcpy(runtimelib, svr_attr.RunTimeLibrary,sizeof(svr_attr.RunTimeLibrary));
     svrm[16]='\0';
     memcpy(svrm, svr_attr.ServerVRM,sizeof(svr_attr.ServerVRM));
   
     switch(svr_attr.Status){
     case 1: { status = "Server ended"; break; }
     case 2: { status = "Server started"; break; }   
     case 3: { status = "Server starting"; break; }
     case 4: { status = "Server ending"; break; }
     case 5: { status = "Server in standby mode"; break; }
     case 99:{ status = "Server in unknown status"; break; }
   
     default:
           printf("Error status\n");
     }
     printf("Server name: %s;\nServer status: %s;\nSubsystemName: %s;\nRunTimeLibrary:
  %s;\nServer version: %s\n", server, status, sbsname, runtimelib, svrm);

     return(0);
}

Информация о списке версий Domino (QnninListDominoRlsI

Этот интерфейс выводит список всех установленных на данной системе версий Domino. Этот интерфейс очень полезен при разработке приложений, поддерживающих различные версии Domino. Информацию о версии Domino можно получить вручную при помощи меню Work with Licensed Programs (Go LICPGM), но этот интерфейс извлекает только информацию о программе лицензирования Domino, что устраняет необходимость поиска всего списка установленных лицензированных программ.

Параметры QnninListDominoRlsI:

  1. Буфер данных для версий Domino
    Output;Char(*). Этот буфер содержит возвращаемый список установленных версий Domino с определенным форматом, как показано в таблице 4.
  2. Длина буфера данных
    Input;Binary(4). Длина буфера данных. Длина должна быть достаточной для хранения поля Bytes returned и поля Bytes available. Отсутствие достаточного места для данных приведет к ошибкам или возврату неполных данных.
  3. Имя формата
    Input;Char(8). Имя формата для информации о версии Domino. Можно использовать DRLS0100 (см. таблицу 5).
  4. Код ошибки
    I/O;Char(*). Возвращает информацию об ошибке для вызывающей стороны.
Таблица 4. Структура буфера данных
СмещениеТипПоле
0x00 Binary(4) Возвращаемое число байтов
0x04 Binary(4) Доступное число байтов
0x08 Binary(4) Смещение записей о версиях
0x0C Binary(4) Число записей о версиях
0x10 Binary(4) Длина каждой записи о версии
Таблица 5. Формат DRLS0100
СмещениеТипПоле
0x00 Binary(4) Длина пути исполнения
0x04 Char(256) Путь исполнения
0x104 Char(10) Библиотека времени исполнения
0x10E Char(16) Версия
0x1E Char(7) Идентификатор продукта
0x125 Char(5) Вариант продукта
0x12A Char(16) Зарезервировано

Ниже приведена предопределенная структура данных в заголовочном файле H/QNNINLDS библиотеки QNOTES, которую можно использовать при вызове интерфейса QnninListDominoRlsI. QnninListDominoRls определяет информацию о списке версий, а DominoRls100 определяет информацию о версии в формате DRLS0100.

Листинг 6. Структуры, используемые в QnninListDominoRlsI
/* Структура Rls Info List формата DRLS0100 */
typedef struct QnninListDominoRls {
     int      BytesReturned;         /* Возвращаемое число байтов           */
     int      BytesAvailable;        /* Доступное для возврата число байтов */
     int      OffsetToRls;           /* Смещение записей о версиях          */
     int      NumberOfRls;           /* Число записей о версиях             */
     int      LengthOfEntry;         /* Длина каждой записи о версии        */
}  QnninListDominoRls_t;

/* DRLS0100 format Rls Info structure */
typedef struct DominoRls100			
{
     int  LengthOfRunPath;       /* Длина пути исполнения       */
     char RunPath[256];          /* Путь исполнения             */
     char RunTimeLibrary[10];
     char Release[16];	         /*Версия Domino (формат n.n.n) */
     char ProdID[7];
     char Option[5];
     char Reserved[16];
} DominoRls100_t;

Приведенный ниже пример кода выводит список всех установленных в системе версий Domino. Информация о версии включает библиотеку времени исполнения, путь исполнения, версию, идентификатор продукта и вариант продукта.

Листинг 7. Пример кода для QnninListDominoRlsI
#include "QNNINLDS.H"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <qusec.h>

int  main(int argc, char * argv[])
{
   char buffer[8192];
   QnninListDominoRls_t * hdr;
   DominoRls100_t   *dom_rls;
   Qus_EC_t     error_code;
   int  lcl_NumberOfRls,lcl_OffsetToRls, lcl_LengthOfEntry;
   int  i;
   int  LengthOfRunPath;       /* Длина пути исполнения        */
   char RunPath[256];          /* Путь исполнения              */
   char RunTimeLibrary[11];
   char Release[17];	       /* Версия Domino (формат n.n.n) */
   char ProdID[8];
   char Option[6];

   memset((char *)&error_code, 0, sizeof(error_code));
   error_code.Bytes_Provided  = sizeof(error_code);
   QnninListDominoRlsI(buffer,  sizeof(buffer), "DRLS0100", &error_code);

   if (error_code.Bytes_Available)  /* Проверка error_code */
   {
      printf("Error retrieving the release information of Domino server. \n");
      return(-1);
   }

   hdr = (QnninListDominoRls_t *)buffer;
   lcl_NumberOfRls = hdr->NumberOfRls;
   lcl_OffsetToRls = hdr->OffsetToRls;
   lcl_LengthOfEntry = hdr->LengthOfEntry;

   for(i=0; i<lcl_NumberOfRls; i++)
   {

      dom_rls = (DominoRls100_t *)(buffer + lcl_OffsetToRls + (i*lcl_LengthOfEntry));

      LengthOfRunPath = dom_rls->LengthOfRunPath;
      RunPath[LengthOfRunPath] = '\0';
      RunTimeLibrary[10] = '\0';
      Release[16] = '\0';
      ProdID[7] = '\0';
      Option[5] = '\0';

      memcpy(RunPath, dom_rls->RunPath, LengthOfRunPath);
      memcpy(RunTimeLibrary, dom_rls->RunTimeLibrary, sizeof(dom_rls->RunTimeLibrary));
      memcpy(Release, dom_rls->Release, sizeof(dom_rls->Release));
      memcpy(ProdID, dom_rls->ProdID, sizeof(dom_rls->ProdID));
      memcpy(Option, dom_rls->Option, sizeof(dom_rls->Option));

      printf("########################################\n");
      printf("RunPath %s\n", RunPath);
      printf("RunTimeLibrary %s\n", RunTimeLibrary);
      printf("Release %s, ProdID %s, Option %s\n", Release, ProdID, Option);

   }

   return(0);
}

Получение и установка значений Notes.ini (QnninGetIniValue и QnninSetIniValue)

Эти два интерфейса используются для получения или установки значения в файле notes.ini сервера Domino. Они предоставляют простой способ программного изменения настроек в файле notes.ini. Например, если пользователь хочет разрешить отладку семафоров на всех своих серверах Domino, он может при помощи этих интерфейсов проверить, включена ли уже эта настройка. Если нет, он может программно включить ее. Таким образом, пользователю не нужно вручную проверять или устанавливать данную настройку на каждом сервере при помощи CL-команд.

Параметры QnninSetIniValue:

  1. Имя сервера
    Input;Char(255). Имя сервера Domino, для которого вы хотите установить значения notes.ini.
  2. Длина имени сервера
    Input:Binary(4). Длина имени сервера.
  3. Имя переменной Notes.ini
    Input;Char(*). Имя переменной, значение которой вы хотите установить.
  4. Длина имени переменной Notes.ini
    Input:Binary(4). Длина имени переменной Notes.ini.
  5. Значение для переменной notes.ini
    Input:Char(*). Новое значение для этой переменной.
  6. Флаг
    Input;Binary(4);REPLACE_LIST, APPEND_TO_LIST and REMOVE_FROM_LIST.
  7. Код ошибки
    I/O; Char(*). Возвращенная информация об ошибке.

Приведенный ниже пример кода получает значение, а затем устанавливает другое значение для переменной notes.ini. В этом примере проверяется настройка переменной CONSOLE_LOG_ENABLED в файле notes.ini сервера Domino, а затем переменная устанавливается в значение "1". Используя два этих интерфейса, можно управлять любыми другими настройками notes.ini.

Листинг 8. Пример кода для QnninGetIniValue и QnninSetIniValue
#include "QNNINLDS.H"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <qusec.h>

int  main(int argc, char * argv[])
{
   char server[]="D851";
   char ini_name[] = "CONSOLE_LOG_ENABLED";
   char ini_value[] = "1";
   char buffer[8192];
   int  buffer_length, buffer_return;
   Qus_EC_t     error_code;

   memset((char *)&error_code, 0, sizeof(error_code));
   error_code.Bytes_Provided  = sizeof(error_code);

   buffer_length = sizeof(buffer);
   QnninGetIniValue(server, sizeof(server), ini_name,  sizeof(ini_name)
           , buffer, buffer_length, &buffer_return, &error_code);

   if (error_code.Bytes_Available)  /* Проверка error_code */
   {
      printf("Error retrieving the ini value of Domino server. \n");
      return(-1);
   }

   if(8192>buffer_return)
   {
      buffer[buffer_return] = '\0';
      printf("CONSOLE_LOG_ENABLED value %s\n",buffer);
     
   }

   memset((char *)&error_code, 0, sizeof(error_code));
   error_code.Bytes_Provided  = sizeof(error_code);

   QnninSetIniValue(server,sizeof(server),ini_name, sizeof(ini_name),
   ini_value, sizeof(ini_value), REPLACE_LIST ,&error_code);

   if (error_code.Bytes_Available)  /* Проверка error_code */
   {
     printf("Error setting the ini value of Domino server. \n");
     return(-1);
   }

   return(0);
}

QnninGetIniValuez идентичен интерфейсу QnninGetIniValue, за исключением того, что входные строковые параметры вводятся как завершенные символом null строки. Это же касается QnninSetIniValuez и QnninSetIniValue.

Получение и установка элемента документа сервера

Существует четыре связанных интерфейса для получения или установки значения элемента документа сервера.

  • QnninGetServerDocItem
  • QnninGetServerDocItemz
  • QnninSetServerDocItem
  • QnninSetServerDocItemz

Элемент документа сервера – это элемент документа сервера Domino в базе данных каталога Domino (names.nsf). QnninGetServerDocItemz идентичен интерфейсу QnninGetServerDocItem, за исключением того, что входные строковые параметры вводятся как завершенные символом null строки. Это же касается QnninSetServerDocItemz и QnninSetServerDocItem.

Ниже приведен пример использования QnninGetServerDocItemz.

Параметры QnninGetServerDocItemz:

  1. Имя сервера
    Input:Char(255). Имя сервера Domino, из которого вы хотите получить информацию.
  2. Имя элемента документа сервера
    Input:Char(*). Имя элемента для записи в документ сервера.
  3. Возвращаемый буфер
    Output:Char(*). Буфер, используемый для хранения значения элемента.
  4. Длина возвращаемого буфера
    Input:Binary(4). Длина возвращаемого буфера.
  5. Доступное число возвращаемых байтов
    Output:Binary(*). Число байтов, возвращаемых в буфере.
  6. Тип данных возвращаемого буфера
    Input:Binary(4). Существует три различных типа данных для значений элементов. TEXT_DATA_TYPE используется для текстовых данных. FLOAT_DATA_TYPE используется для значений с плавающей точкой. INTEGER_DATA_TYPE используется для целочисленных данных.
  7. Код ошибки
    I/O:Char(*). Возвращенная информация об ошибке.

В данном примере программа извлекает заголовок сервера из документа сервера в names.nsf и устанавливает его в значение "Domino server for API test".

Листинг 9. Пример кода для QnninGetServerDocItem и QnninSetServerDocItem
#include "QNNINLDS.H"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <qusec.h>
#include <qusrjobi.h>

int  main(int argc, char * argv[])
{
     char server[]= "D851";
     char item_name[] = "ServerTitle";
     char item_new_value[] = "Domino server for API test";
     char buffer[8192];
     int  buffer_length, buffer_return;
     Qus_EC_t     error_code;

     memset((char *)&error_code, 0, sizeof(error_code));
     error_code.Bytes_Provided  = sizeof(error_code);

     buffer_length = sizeof(buffer);
     QnninGetServerDocItem(server, sizeof(server), item_name,  sizeof(item_name)
               , buffer, buffer_length, &buffer_return, TEXT_DATA_TYPE ,&error_code);

     if (error_code.Bytes_Available)  /* Check the error_code. */
     {
        printf("Error retrieving the item's value of Domino server. \n");
        return(-1);
     }

     if(8192>buffer_return)
     {
        buffer[buffer_return] = '\0';
        printf("ServerTitle %s\n",buffer);
     }

     memset((char *)&error_code, 0, sizeof(error_code));
     error_code.Bytes_Provided  = sizeof(error_code);

     QnninSetServerDocItem(server,sizeof(server),item_name,sizeof(item_name),
     item_new_value, sizeof(item_new_value), REPLACE_LIST, TEXT_DATA_TYPE ,&error_code);

     if (error_code.Bytes_Available)  /* Проверка error_code */
     {
        printf("Error setting the item's value of Domino server. \n");
        return(-1);
     }
  
     return(0);
 }

Советы по использованию этих интерфейсов

  1. При компиляции C-программы возможно появление следующих сообщений об ошибках: #include file "QNNINLDS.H" not found (#include-файл "QNNINLDS.H" не найден). Убедитесь, что QNOTES находится в списке библиотек, а затем повторите компиляцию.
  2. Заголовочный файл H/QNNINLDS библиотеки QNOTES содержит список макросов, список структур и список прототипов функций для интерфейсов.
  3. Изменения некоторых настроек файла notes.ini или документа сервера могут вступать в действие только после перезагрузки сервера Domino.
  4. При работе с элементом документа сервера необходимо использовать корректное имя элемента.

Заключение

В статье приводится базовая информация об уникальных программных интерфейсах Domino для IBM i и приводится несколько примеров исходного кода. Эти интерфейсы обеспечивают удобный способ разработки программ для управления и работы с серверами Domino на IBM i, особенно для пользователей, имеющих несколько серверов Domino. Мы надеемся, что данная статья поможет разработчикам, применяющим Domino на IBM i, сделать первый шаг в исследовании и использовании этих интерфейсов в своих приложениях.


Resources

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



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

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Lotus
ArticleID=831293
ArticleTitle=Управление серверами Domino на IBM i при помощи программных интерфейсов
publish-date=08222012