使用 API 管理您的 IBM i Domino 服务器

本文介绍一组 API,它们支持对 IBM i 上的 Domino 服务器进行编程方式访问和管理。本文将利用代码示例来展示如何使用 API 执行这些任务。

Bin Yang, 软件工程师, IBM

照片Bin Yang 于 2005 年加入 Lotus Domino for IBM i 团队,目前致力于 Lotus Domino on IBM i 的开发和客户支持工作。



Shuang Hong Wang, 咨询软件工程师, IBM

Wang 的照片Shuang Hong Wang 从 2005 年便开始从事 Lotus Domino on IBM i 的开发和客户支持方面的工作。他目前是 IBM i 上的 Lotus 产品的技术领导。



2011 年 10 月 13 日

简介

许多客户在 IBM i 上运行其 Domino 服务器。Domino 在 IBM i 上与在其他平台的不同之处在于,您可以在一个 IBM i 分区上安装多个版本的 Domino,并配置每个 Domino 版本的多个 Domino 分区(实例),而在其他平台上您在每台服务器上,通常只能安装和配置一台 Domino 服务器实例。这使得 IBM i 成为需要部署多台 Domino 服务器的企业的天然平台。

Lotus Domino Administrator 是 IBM 用于管理和操作不同平台(包括 IBM i)上的 Domino 服务器的主要工具。鉴于 IBM i 上 Domino 的一些具体特征,IBM 为您提供几个 Domino CL(Control Language) 命令。通过使用 Domino CL 命令,您可以查看在 IBM i 分区上配置的所有 Domino 服务器,启动或停止 Domino 服务器、监视 Domino 服务器的状态、查看并管理 Domino 服务器的所有作业、查看并编辑 Domino 服务器的 Notes.ini 文件、查看 Domino 服务器控制台日志,等等。除了使用 Domino CL 命令手动管理 Domino 服务器之外,一些 IT 部门需要通过编程方式管理 Domino 服务器。例如,IT 部门可能要求所有运行的 Domino 服务器在每个周六下午 5 点时自动关闭,以便执行备份并压缩所有 NSF 数据库来释放磁盘存储。IBM i 上的 Domino 提供了一组 API 来应对这类需求。这一组 API 允许您列出所有 Domino 服务器,从服务器检索信息,获取或设置 Domino 服务器的 Notes.ini,等等。通过结合使用 Domino for IBM i API 和一些 Domino CL 命令,您可以轻松满足自动管理 Domino 服务器的需求。这组只存在于Domino for IBM i上的API与Lotus C APIs for Notes/Domino不同,后者用于创建或删除 NSF 数据库、读取或编辑 NSF 数据库中的文档、创建和使用数据库索引/视图,等等。

在本文中,我们简要介绍了这组只存在于 Domino for IBM i 上的 API,提供了关于如何使用它们的一些示例以及技巧。这些 API 是 IBM i 特有的,包含在 Lotus Domino on IBM i License Program 的基本选项中。

本文中的示例需要具备 Lotus Domino 的基础知识,且基于 IBM i 系统 Version 5 Release 4 (V5R4) 上运行的 Lotus Domino 8.5.1。

表 1 列出了 Domino for IBM i 的独特 API。

表 1. API 函数列表
API 函数名说明
QnninListDominoServers 获取系统上的 Domino 服务器列表。
QnninRtvDominoServerI 获取 Domino 服务器的具体信息。
QnninRtvDominoServerAttr 检索 Domino 服务器的具体信息。该 API 程序可以基于参数的格式格式类型检索 QnninRtvDominoServerI 提供的所有信息以及其他信息。
QnninSetDominoEnv 将当前作业的工作环境设置为这样一个状态,即允许为特定 Domino 服务器调用 NotesInitExtended API。这样可以消除调用方的负担,使其在初始化 Notes API 环境时无需知道这类具体信息。
QnninGetDominoEnv 获取关于当前作业的 Domino 服务器环境的信息。
QnninListDominoRlsI 获取当前系统上所有已安装 Domino 的版本信息。
QnninGetIniValue 和 QnninGetIniValuez 从 Domino 服务器的 notes.ini 文件中获取 ini 变量的值。
QnninSetIniValue 和 QnninSetIniValuez 在 Domino 服务器的 notes.ini 文件中设置 ini 变量的值。
QnninGetServerDocItem 和 QnninGetServerDocItemz 从 Domino 地址本中的服务器文档中获取项目值。 。
QnninSetServerDocItem 和 QnninSetServerDocItemz 在 Domino 地址本中的 服务器文档中更改或设置项目值。

如何使用 Domino for IBM i 独特的 API

本节介绍 Domino for IBM i 的一些独特的 API,并给出了关于如何使用这些 API 的一些 C 程序示例。这些 API 来自 QNOTES 库下的服务程序 QNNINLDS.SRVPGM。这些 API 中的大部分没有相似的命令,除了 QnninSetDominoEnv API 有一个名为 SETDOMENV 的相似的 CL 命令。

要编译本文中的程序并获取 PGM 对象,可以参考清单 1 中的以下命令。

清单 1. 常用编译命令
ADDLIBLE QNOTES
CRTCMOD lib_name/mod_name lib_name/QCSRC output(*PRINT)
CRTPGM  lib_name/mod_name

列出 Domino 服务器 (QnninListDominoServers)

要管理 Domino 服务器,首先需要知道 Domino 服务器的名称。QnninListDominoServers API 提供了检索系统上已配置的所有 Domino 服务器的名称的一种简单方法。有了名称列表,我们可以通过其他 API 管理或访问 Domino 服务器。

QnninListDominoServers 参数:

  1. Domino 服务器的数据缓冲区
    Output;Char(*) 该缓冲区存储 Domino 服务器的列表。且以当前作业的 CCSID 格式返回服务器名称。输出缓冲区的格式由 3rd 参数(格式名称)定义。
  2. 数据缓冲区长度
    Input; Binary(4) 数据缓冲区的长度。如果长度足够用,则会将已配置 Domino 服务器的列表放入数据缓冲区中,否则会引发返回错误或不完整的数据。
  3. 格式名称
    Input;Char(8) 用于检索所有已配置 Domino 服务器的格式的名称。目前,唯一受支持的格式名是 DSRV0100。请参见表 2。
  4. 错误代码
    I/O;Char(*) 返回错误信息。如果省略该参数,会将诊断和逃逸型消息发给应用程序。
表 2. “DSRV0100” 格式
偏移量类型字段字段说明
0x00 Binary(4) Bytes returned 可返回的数据的长度。
0x04 Binary(4) Bytes available 在该结构中返回的数据的长度。
0x08 Binary(4) Offset to server entry 第一个服务器条目初始的偏移量。
0x0C Binary(4) Number of server entries returned 所返回的 “Server entries” 字段中的服务器条目的数量
0x10 Binary(4) Length of server entry 所返回的每个服务器条目的长度,应为 255。
0x14 Char(*) Server entries 返回的服务器条目的开头。

QnninListDominoData_t 是 QNOTES 库下头文件 H/QNNINLDS 中的一个预定义数据结构,在调用 QnninListDominoServers API 时可使用该数据结构。

清单 2. QnninListDominoData 结构
typedef struct QnninListDominoData {                                 
     int      BytesReturned;         /* Bytes returned             */
     int      BytesAvailable;        /* Bytes available to return  */
     int      OffsetToServers;       /* Offset to server entries   */
     int      NumberOfServers;       /* Number of server entries   */
     int      LengthOfEntry;         /* Length of each server entry*/
}  QnninListDominoData_t;

下面的示例代码给出一个示例,列出了当前系统上所有 Domino 服务器的名称。首先,我们定义了一个 my_sturct_t 结构,该结构包含 QnninListDominoData_t 以及用于保存 Domino 服务器名称的字符串数组。变量 svr_list 被定义为 my_struct_t 类型,它是 QnninListDominoServers API 的第一个参数。在调用该 API 之后,可以将服务器名称返回给 svr_list。请注意,所返回服务器名称的长度是 255,且不以空字符结尾。如果小于 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)  /* Check the 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++)  /* List all of the domino servers. */
  {
     svr_ptr = ((char *)&svr_list) + lcl_OffsetToServers + lcl_LengthOfEntry*(i-1) + 254;
     svr_entry = svr_ptr-254;
     j=254;
     while(*svr_ptr == ' '&& j>=0)  /* Remove the blank from the returned server name. */
     {
         *svr_ptr = '\0';
         j--;
         svr_ptr--;
     }
     printf("Server names: %s\n", svr_entry);

  }
  return(0);
}

检索 Domino 服务器属性 (QnninRtvDominoServerAttr)

有了 Domino 服务器的名称之后,我们可以使用 QnninRtvDominoServerAttr API 从该服务器检索更多属性,比如服务器状态、数据目录路径、可执行目录路径、Domino 版本,等等。

QnninRtvDominoServerAttr 参数:

  1. Domino 服务器属性的数据缓冲区
    Output;Char(*) 该缓冲区存储 Domino 服务器的属性。输出缓冲区的格式由第五参数(格式名称)定义。
  2. 数据缓冲区长度
    Input;Binary(4) 数据缓冲区的长度。请确保长度值足够大。
  3. 服务器名称
    Input;Char(255)Domino 服务器的名称,可由 QnninListDominoServers API 返回来检索信息。该字段用空格填充,且不以空字符结尾。
  4. 服务器名称长度
    Input;Binary(4) 服务器名称的长度。它应当始终为 255。如果实际服务器名称的长度小于 255,会以空格填补。。
  5. 格式名称
    Input;Char(8) 要检索的不同 Domino 服务器属性的格式的名称,比如 DATR0100,DATR0200。参见表 3 中的 DATR0100 格式。
  6. 错误代码
    I/O;Char(*) 返回调用方的错误信息。
表 3. “DATR0100” 属性缓冲
偏移量类型字段
0x00 Binary(4) Bytes returned
0x04 Binary(4) Bytes available
0x08 Binary(4) Primary type of domino server
0x0C Binary(4) Secondary type of Domino server
0x10 Binary(4) Number of active jobs in the subsystem
0x14 Binary(4) Offset to data directory path
0x18 Binary(4) Length of data directory path
0x1C Binary(4) Offset to executable directory path
0x20 Binary(4) Length of executable directory path
0x24 Char(20) Subsystem description
0x38 Char(10) Library name
0x42 Binary(1) Server status
0x43 Binary(1) Auto-Start with TCP/IP Servers
0x44 Binary(4) Partition Number
0x48 Binary(4) Offset to generic information
0x4C Binary(4) Length of generic information
0x50 Char(16) The version of Domino Server(VRM)
* Char(*) Variable data

有关 DATR0100 和 DATR0200 格式的详细信息,您可以参阅 参考资料 部分中的 Lotus Domino for i5/OS Application Development Guide。

QnninRtvDominoData_t 是 QNOTES 下头文件 H/QNNINLDS 中的一个预定义数据库,在调用 QnninRtvDominoserverAttr API 时可使用该库。QnninRtvDominoData_t 包含 DATR0100 格式的数据。

清单 4. QnninRtvDominoData 结构
/*DATR0100 format*/
typedef struct QnninRtvDominoData {
     int      BytesReturned;         /* Bytes returned             */
     int      BytesAvailable;        /* Bytes available to return  */
     int      PrimaryType;           /* Type of Domino server      */
     int      SecondaryType;         /* Secondary type of server   */
     int      ActiveJobsInSbs;       /* Number of active jobs in   */
                                     /* subsystem.                 */
     int      OffsetToPath;          /* Offset to data dir. path   */
     int      LengthOfPath;          /* Length of data dir. path   */
     int      OffsetToRunPath;       /* Offset to run path         */
     int      LengthOfRunPath;       /* Length of run path         */
     char     SubsystemName[20];     /* Subsystem description name */
     char     RunTimeLibrary[10];    /* Library where run time     */
                                     /* routines of the server     */
                                     /* are found.                 */
     char     Status;                /* Status of server.          */
     char     TCPAutoStart;          /* Auto start server on STRTCP*/
     int      PartitionNumber;       /* Partition number of svr    */
     int      OffsetToInfo;          /* Offset to generic info     */
     int      LengthOfInfo;          /* Length of generic info     */
     char     ServerVRM[16];         /* VRM of Domino Server       */
}  QnninRtvDominoData_t;

下面的示例代码给出示例来检索 Domino 服务器的一些信息。在该示例中,我们以“DATR0100”格式调用了QnninRtvDominoServerAttr API,并提取了服务器的子系统名称、运行时库、服务器版本和服务器状态。

清单 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)  /* Check the 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)

该 API 可列出当前系统上安装的所有 Domino 版本。在开发应用程序以支持不同的 Domino 版本时,该 API 很有帮助,可灵活地从系统中检索 Domino 版本信息。您可以从 Work with Licensed Programs 菜单 (Go LICPGM) 手动获取该信息,但该 API 仅检索 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) Bytes returned
0x04 Binary(4) Bytes available
0x08 Binary(4) Offset to release entries
0x0C Binary(4) Number of release entries
0x10 Binary(4) Length of each release entry
表 5. “DRLS0100” 格式
偏移量类型字段
0x00 Binary(4) Length of run path
0x04 Char(256) Run path
0x104 Char(10) Run time library
0x10E Char(16) Release
0x1E Char(7) Product ID
0x125 Char(5) Product Option
0x12A Char(16) Reserved

下面是 QNOTES 库下头文件 H/QNNINLDS 中的预定义数据结构,在调用 QnninListDominoRlsI API 时可使用该数据结构。QnninListDominoRls 定义了版本信息列表,而 DominoRls100 定义了 DRLS0100 所规定的格式

清单 6. 在 QnninListDominoRlsI 中使用的结构
/* DRLS0100 format Rls Info List structure */
typedef struct QnninListDominoRls {
     int      BytesReturned;         /* Bytes returned             */
     int      BytesAvailable;        /* Bytes available to return  */
     int      OffsetToRls;           /* Offset to release entries  */
     int      NumberOfRls;           /* Number of release entries  */
     int      LengthOfEntry;         /* Length of each release entry*/
}  QnninListDominoRls_t;

/* DRLS0100 format Rls Info structure */
typedef struct DominoRls100			
{
     int  LengthOfRunPath;       /* Length of run path         */
     char RunPath[256];          /* Run path                   */
     char RunTimeLibrary[10];
     char Release[16];	          /* Domino Release (n.n.n format) */
     char ProdID[7];
     char Option[5];
     char Reserved[16];
} DominoRls100_t;

以下示例代码给出一个示例,列出系统上已安装的所有 Domino 版本。版本信息包括运行时库、运行路径、版本、产品 ID 和产品选项。

清单 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;       /* Length of run path         */
   char RunPath[256];          /* Run path                   */
   char RunTimeLibrary[11];
   char Release[17];	        /* Domino Release (n.n.n format) */
   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)  /* Check the 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)

这两个 API 用于获取或设置 Domino 服务器的 notes.ini 文件中的值。它提供一种简便方法来通过编程方式更改 notes.ini 文件中的设置。例如,如果客户想对所有其 Domino 服务器启用信号灯 (semaphore) 调试,那么他们可以使用该 API 来检查每台服务器,查看是否已经开启了相关设置。如果没有,则可以通过编程启用 semaphore 调试。因此,客户无需在每台服务器上使用 CL 命令手动检查或设置它。

QnninSetIniValue 参数:

  1. 服务器名称
    Input;Char(255) 您所要设置 notes.ini 参数的 Domino 服务器名称。
  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 和 REMOVE_FROM_LIST。
  7. 错误代码
    I/O; Char(*) 返回的错误信息。

以下示例代码给出一个示例,将获取值并将 notes.ini 变量设为另一个值。在本例中,我们检查了 Domino 服务器的 notes.ini 参数“CONSOLE_LOG_ENABLED” 并将其设置为 “1”。通过使用这两个 API,您可以进行任何其他 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)  /* Check the 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)  /* Check the error_code. */
   {
     printf("Error setting the ini value of Domino server. \n");
     return(-1);
   }

   return(0);
}

QnninGetIniValuez 与 QnninGetIniValue API 一样,只是它输入的字符串参数可以是有字符串结束符的。这与 QnninSetIniValuez 和 QnninSetIniValue 一样。

获取和设置服务器文档项目

我们有 4 个相关的 API,可使用它们来获取或设置服务器文档项目的值。

  • QnninGetServerDocItem
  • QnninGetServerDocItemz
  • QnninSetServerDocItem
  • QnninSetServerDocItemz

服务器文档项是指 Domino 目录数据库(names.nsf)中 Domino 服务器文档中的项目。QnninGetServerDocItemz API 与 QnninGetServerDocItem API 一样,只是它输入的字符串参数是有字符串结束符的。这与 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)  /* Check the error_code. */
     {
        printf("Error setting the item's value of Domino server. \n");
        return(-1);
     }
  
     return(0);
 }

使用这些 API 的技巧

  1. 在编译 C 程序时,您可能会遇到以下错误消息:
    #include 文件 “QNNINLDS.H” 未找到。您应当确保 QNOTES 在您的库列表中。然后再次尝试。
  2. QNOTES 库下的头文件 H/QNNINLDS 包含 API 的 宏定义列表、数据结构列表和 函数原型列表。
  3. 在更改 notes.ini 设置或服务器文档设置时,有一些设置可能需要重启 Domino 服务器才能生效。
  4. 在处理服务器文档项目时,您应当使用正确的项目名称。

结束语

本文介绍了 Domino for IBM i API 的一些基础知识,以及一些示例代码。这些 API 可以很容易的实现通过应用开发程序来管理和操作 IBM i 上的 Domino 服务器,特别适用于有很多 Domino 服务器的客户。我们希望本文是 Domino on IBM i 开发人员在其应用程序中探索和使用这些 API 的第一步。

参考资料

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=IBM i, Lotus
ArticleID=765275
ArticleTitle=使用 API 管理您的 IBM i Domino 服务器
publish-date=10132011