Gerencie seus servidores IBM i Domino usando APIs

Este artigo descreve um conjunto de APIs que permite o acesso e o gerenciamento programáticos de servidores Domino no IBM i. O artigo inclui exemplos de código para demonstrar o uso de APIs na realização dessas tarefas.

Bin Yang, Staff Software Engineer, IBM

Bin Yang photoBin Yang passou a fazer parte da equipe Lotus Domino para IBM i em 2005. Atualmente, trabalha no desenvolvimento e no suporte ao cliente do Lotus Domino no IBM i.



Shuang Hong Wang, Advisory Software Engineer, IBM

Wang photoShuang Hong Wang trabalha no desenvolvimento e no suporte ao cliente do Lotus Domino no IBM i desde 2005. Atualmente, ele é líder técnico das ofertas de produtos Lotus no IBM i.



31/Ago/2011

Introdução

Muitos clientes executam seus servidores Domino no IBM i. O Domino no IBM i diferencia-se de outras plataformas pelo fato de que é possível instalar diversas versões do Domino em uma única partição do IBM i e configurar várias partições (instâncias) do Domino de cada versão do produto, enquanto que, em outras plataformas, normalmente só é possível instalar e configurar uma instância do servidor do Domino em cada servidor. Isto possibilita que o IBM i seja a plataforma ideal para empresas que precisam implementar diversos servidores do Domino.

O Lotus Domino Administrator é a principal ferramenta fornecida pela IBM para gerenciar e operar os servidores Domino em diferentes tipos de plataformas, incluindo IBM i. Devido à característica específica do Domino no IBM i, a IBM fornece a você alguns comandos da CL (Control Language) do Domino. Ao usar os comandos da CL do Domino, é possível visualizar todos os servidores Domino configurados em uma partição do IBM i, iniciar ou parar servidor(es) Domino, monitorar o status do servidor Domino, visualizar e gerenciar todas as tarefas de um servidor Domino, visualizar e editar o arquivo Notes.ini do servidor Domino, visualizar o registro do console do servidor Domino, entre outros. Além das etapas manuais para gerenciar servidores Domino usando os comandos da CL do Domino, alguns departamentos de TI têm a necessidade de gerenciar servidores Domino programaticamente. Por exemplo, o departamento de TI pode requerer que todos os servidores Domino ativos sejam encerrados automaticamente aos sábados às 17h, para que os backups possam ser realizados e todos os bancos de dados NSF sejam compactados, liberando armazenamento em disco. O Domino no IBM i fornece um conjunto de APIs para tratar este tipo de requisitos. Este conjunto de APIs do IBM i permite listar todos os servidores Domino, recuperar informações de um servidor, obter ou definir o arquivo Notes.ini do servidor Domino, entre outros. Ao usar as APIs do Domino para IBM i com alguns dos comandos da CL do Domino, é possível atender facilmente aos requisitos acima de gerenciamento automático dos servidores Domino. Essas APIs exclusivas do Domino para IBM i são diferentes das APIs do Lotus C para Notes/Domino, usadas para criar ou excluir bancos de dados NSF, ler ou editar documentos no banco de dados NSF, criar e usar índices/visualizações de banco de dados, entre outros.

Neste artigo, apresentaremos as APIs exclusivas do Domino para IBM i, além de alguns exemplos e dicas de como usá-las. Essas APIs são específicas para o IBM i e estão incluídas na opção básica do programa de licença do Lotus Domino no IBM i.

Os exemplos neste artigo assumem que o leitor possui conhecimento básico do Lotus Domino e são baseados no Lotus Domino 8.5.1 em execução em um sistema IBM i de Versão 5 Release 4 (V5R4).

A Tabela 1 lista as APIs exclusivas do Domino para IBM i.

Tabela 1. Lista de funções das APIs
Nome da função da APIDescrição
QnninListDominoServers Obtém a lista dos servidores Domino no sistema.
QnninRtvDominoServerI Obtém informações específicas do servidor Domino.
QnninRtvDominoServerAttr Recupera informações específicas do servidor Domino. Este programa de API pode recuperar todas as informações fornecidas por QnninRtvDominoServerI, além de informações adicionais, com base no nome do formato do parâmetro.
QnninSetDominoEnv Define o ambiente de trabalho da tarefa atual em um estado que permite que a API NotesInitExtended seja chamada por um servidor Domino específico. Isso diminui a sobrecarga do responsável pela chamada, fazendo com que não seja necessário que ele saiba sobre as informações específicas de cada servidor Domino ao inicializar o ambiente de API do Notes.
QnninGetDominoEnv Obtém as informações sobre o ambiente do servidor Domino da tarefa atual.
QnninListDominoRlsI Obtém todas as informações sobre o release do Domino instalado no sistema atual.
QnninGetIniValue e QnninGetIniValuez Obtém um valor da variável ini do arquivo notes.ini do servidor Domino.
QnninSetIniValue e QnninSetIniValuez Definem um valor da variável ini no arquivo notes.ini do servidor Domino.
QnninGetServerDocItem e QnninGetServerDocItemz Obtêm um valor de item de um documento de servidor Domino que se encontra no diretório do Domino.
QnninSetServerDocItem e QnninSetServerDocItemz Alteram ou definem um valor de item no documento do servidor Domino que se encontra no diretório do Domino.

Como usar as APIs exclusivas do Domino para IBM i

Esta seção descreve algumas das APIs exclusivas do Domino para IBM i e fornece alguns exemplos de programa C sobre como usar essas APIs. Essas APIs fazem parte do programa de serviço QNNINLDS.SRVPGM na biblioteca QNOTES. A maioria dessas APIs não possui comandos similares, exceto a API QnninSetDominoEnv, que possui um comando CL similar chamado SETDOMENV.

Para compilar os programas neste artigo e obter os objetos PGM, é possível consultar os comandos abaixo na Listagem 1.

Listagem 1. Comandos gerais de compilação
ADDLIBLE QNOTES
CRTCMOD lib_name/mod_name lib_name/QCSRC output(*PRINT)
CRTPGM  lib_name/mod_name

Listar servidores Domino (QnninListDominoServers)

Para gerenciar um servidor Domino, é essencial ter o nome do servidor Domino. A API QnninListDominoServers fornece uma maneira fácil para recuperar todos os nomes do servidor Domino configurados em um sistema. Com a lista dos nomes, é possível gerenciar ou acessar os servidores Domino por meio de outras APIs.

Parâmetros de QnninListDominoServers:

  1. Buffer de dados para servidores Domino
    Output;Char(*)Este buffer armazena a lista de servidores Domino. Os nomes do servidor são retornados no CCSID da tarefa atual. O formato do buffer de saída é definido pelo parâmetro 3 (nome do formato).
  2. Tamanho do buffer de dados
    Input; Binary(4)O tamanho do buffer de dados. Se o tamanho for suficiente, a lista de servidores Domino configurados será colocada na área de buffer de dados. Caso contrário, isto resultará em erros ou dados incompletos sendo retornados.
  3. Nome do formato
    Input;Char(8)O nome do formato usado para recuperar todos os servidores Domino configurados. Atualmente, o único nome de formato suportado é DSRV0100. Consulte a Tabela 2.
  4. Código do erro
    I/O;Char(*)Informações do erro retornado. Se este parâmetro for omitido, mensagens de diagnóstico e escape serão enviadas ao aplicativo.
Tabela 2. Formato “DSRV0100”
DeslocamentoTipoCampoDescrição do campo
0x00 Binary(4) Bytes retornados O tamanho dos dados que deverão ser retornados.
0x04 Binary(4) Bytes disponíveis O tamanho dos dados retornados nesta estrutura.
0x08 Binary(4) Deslocamento para a entrada do servidor O deslocamento para o início da primeira entrada do servidor.
0x0C Binary(4) Número de entradas de servidor retornadas O número de entradas de servidor no campo "Server entries" retornado.
0x10 Binary(4) Tamanho da entrada do servidor O tamanho de cada entrada de servidor retornada. Ele deverá ser 255.
0x14 Char(*) Entradas de servidor O início de entradas de servidor retornadas.

QnninListDominoData_t é uma estrutura de dados predefinida no arquivo de cabeçalho H/QNNINLDS na biblioteca QNOTES, que pode ser usada ao chamar a API QnninListDominoServers.

Listagem 2. Estrutura 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;

O código de amostra abaixo exemplifica como listar os nomes de servidor Domino no sistema atual. Primeiramente, definimos uma estrutura my_sturct_t que contém um QnninListDominoData_t e um array de cadeia de caractere para conter nomes de servidores Domino. A variável svr_list é definida como do tipo my_struct_t e é o primeiro parâmetro da API QnninListDominoServers. Depois de chamarmos esta API, os nomes do servidor podem ser retornados para a svr_list. Observe que o tamanho do nome do servidor retornado é 255 e não é finalizado por NULL. Se for menor do que 255, será completado com espaços em branco. As instruções "for" nesta amostra são usadas para listar todos os nomes de servidor Domino retornados sem os espaços em branco.

Listagem 3. Código de amostra para 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);
}

Recuperar atributos do servidor Domino (QnninRtvDominoServerAttr)

Quando temos o nome do servidor Domino, é possível usar a API QnninRtvDominoServerAttr para recuperar mais atributos deste servidor, como o status do servidor, caminho do diretório de dados, caminho do diretório executável, versão do Domino, entre outros.

Parâmetros de QnninRtvDominoServerAttr:

  1. Buffer de dados para atributos do servidor Domino
    Output;Char(*)Este buffer armazena os atributos do servidor Domino. O formato do buffer de saída é definido pelo parâmetro 5 (nome do formato).
  2. Tamanho do buffer de dados
    Input;Binary(4)O tamanho do buffer de dados. Certifique-se de que ele tenha tamanho suficiente.
  3. Nome do servidor
    Input;Char(255)O nome do servidor Domino que será retornado pela API QnninListDominoServers para recuperar informações. Este campo é preenchido com espaços em branco e não é finalizado por null.
  4. Tamanho do nome do servidor
    Input;Binary(4)O tamanho do nome do servidor. Ele deverá sempre ser 255. Se o tamanho real do nome do servidor for menor do que 255, ele será preenchido com espaços em branco.
  5. Nome do formato
    Input;Char(8)O nome do formato para recuperar diferentes atributos do servidor Domino. DATR0100, DATR0200. Consulte a Tabela 3 para obter o formato DATR0100.
  6. Código do erro
    I/O;Char(*)Retorna informações do erro para o chamador.
Tabela 3. Buffer de atributos “DATR0100”
DeslocamentoTipoCampo
0x00 Binary(4) Bytes retornados
0x04 Binary(4) Bytes disponíveis
0x08 Binary(4) Tipo principal do servidor Domino
0x0C Binary(4) Tipo secundário do servidor Domino
0x10 Binary(4) Número de tarefas ativas no subsistema
0x14 Binary(4) Deslocamento para o caminho do diretório de dados
0x18 Binary(4) Tamanho do caminho do diretório de dados
0x1C Binary(4) Deslocamento para o caminho do diretório executável
0x20 Binary(4) Tamanho do caminho do diretório executável
0x24 Char(20) Descrição do subsistema
0x38 Char(10) Nome da biblioteca
0x42 Binary(1) Status do servidor
0x43 Binary(1) Autoinicialização com servidores TCP/IP
0x44 Binary(4) Número da partição
0x48 Binary(4) Deslocamento para informações genéricas
0x4C Binary(4) Tamanho das informações genéricas
0x50 Char(16) A versão do Domino Server(VRM)
* Char(*) Dados variáveis

Para ver as informações de detalhes sobre os formatos DATR0100 e DATR0200, consulte o Guia de Desenvolvimento de Aplicativos do Lotus Domino para i5/OS em Recursos.

QnninRtvDominoData_t é uma estrutura de dados predefinida no arquivo de cabeçalho H/QNNINLDS na biblioteca QNOTES, que pode ser usada ao chamar a API QnninRtvDominoserverAttr. QnninRtvDominoData_t contém os dados com o formato DATR0100.

Listagem 4. Estrutura 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;

O código de amostra abaixo exemplifica como recuperar algumas informações do servidor Domino. Nesta amostra, chamamos a API QnninRtvDominoServerAttr com o nome de formato "DATR0100" e extraímos o nome do subsistema do servidor, a biblioteca de tempo de execução, a versão do servidor e o status do servidor.

Listagem 5. Código de amostra para 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);
}

Listar informações sobre o release do Domino (QnninListDominoRlsI)

Esta API pode listar todos os releases instalados do Domino no sistema atual. Ao desenvolver um aplicativo para suportar diferentes releases do Domino, esta API é útil e flexível para recuperar informações de release do Domino a partir do sistema. Estas informações podem ser acessadas manualmente a partir do menu Work with Licensed Programs (Go LICPGM), mas esta API recupera somente as informações do programa Domino licenciado, o que elimina o trabalho de procurar em toda a lista de programas licenciados instalados.

Parâmetros do QnninListDominoRlsI:

  1. Buffer de dados para releases do Domino
    Output;Char(*)Este buffer contém a lista retornada de informações de releases do Domino instaladas com o formato definido exibido na Tabela 4.
  2. Tamanho do buffer de dados
    Input;Binary(4)O tamanho do buffer de dados. O tamanho deve ser suficiente para conter os campos de bytes retornados e bytes disponíveis. Caso não exista espaço suficiente para os dados, o resultado serão erros ou dados incompletos sendo retornados.
  3. Nome do formato
    Input;Char(8)O nome do formato para informações sobre o release do Domino. É possível usar "DRLS0100". Consulte a Tabela 5.
  4. Código do erro
    I/O;Char(*)Retorna informações do erro para o chamador.
Tabela 4. Estrutura do buffer de dados
DeslocamentoTipoCampo
0x00 Binary(4) Bytes retornados
0x04 Binary(4) Bytes disponíveis
0x08 Binary(4) Deslocamento para entradas de release
0x0C Binary(4) Número de entradas de release
0x10 Binary(4) Tamanho de cada entrada de release
Tabela 5. Formato “DRLS0100”
DeslocamentoTipoCampo
0x00 Binary(4) Tamanho do caminho de execução
0x04 Char(256) Caminho de execução
0x104 Char(10) Biblioteca de tempo de execução
0x10E Char(16) Release
0x1E Char(7) ID do produto
0x125 Char(5) Opção do produto
0x12A Char(16) Reservado

Abaixo, estão as estruturas de dados predefinidas no arquivo de cabeçalho H/QNNINLDS na biblioteca QNOTES, que podem ser usadas ao chamar a API QnninListDominoRlsI. QnninListDominoRls define as listas de informações sobre o release e DominoRls100 define as informações sobre o release com o formato DRLS0100.

Listagem 6. Estruturas usadas em 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;

O código de amostra abaixo exemplifica como listar todos os releases do Domino instalados no sistema. As informações sobre o release incluem biblioteca de tempo de execução, caminho de execução, release, ID do produto e opção do produto.

Listagem 7. Código de amostra para 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);
}

Obter e definir o valor de Notes.ini (QnninGetIniValue e QnninSetIniValue)

Essas APIs são usadas para obter ou definir um valor no arquivo notes.ini do servidor Domino. Elas fornecem uma maneira simples de alterar configurações programaticamente no arquivo notes.ini. Por exemplo, se um cliente desejar ativar a depuração de semáforo em todos seus servidores Domino, esta API pode ser usada para verificar cada servidor e conferir se a configuração já está ativada. Se não, é possível ativar programaticamente a depuração de semáforo. Ao fazer isto, o cliente evita a necessidade de verificá-la ou defini-la manualmente em cada servidor usando comandos de CL.

Parâmetros de QnninSetIniValue:

  1. Nome do servidor
    Input;Char(255)O nome do servidor Domino no qual deseja definir o valor de notes.ini.
  2. Tamanho do nome do servidor
    Input:Binary(4)O tamanho do nome do servidor.
  3. Nome da variável Notes.ini
    Input;Char(*)O nome da variável à qual deseja definir um valor.
  4. Tamanho do nome da variável Notes.ini
    Input:Binary(4)O tamanho do nome da variável Notes.ini.
  5. O valor da variável notes.ini
    Input:Char(*)O novo valor para esta variável.
  6. Sinalizador
    Input;Binary(4);REPLACE_LIST, APPEND_TO_LIST e REMOVE_FROM_LIST.
  7. Código do erro
    I/O; Char(*)Informações do erro retornado.

O código de amostra abaixo exemplifica como obter o valor e, a seguir, definir outro valor para a variável notes.ini. Nesta amostra, verificamos a configuração do notes.ini do servidor Domino "CONSOLE_LOG_ENABLED" e a definimos para "1". Ao usar essas APIs, é possível operar com qualquer outra configuração de notes.ini.

Listagem 8. Código de amostra para QnninGetIniValue e 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 é igual à API QnninGetIniValue, exceto pelo fato de que os parâmetros de cadeia de caractere de entrada são inseridos como cadeia de caractere finalizada com null. O mesmo que QnninSetIniValuez e QnninSetIniValue.

Obter e definir o item de documento do servidor

Há 4 APIs relacionadas para obter ou definir o valor do item de documento do servidor.

  • QnninGetServerDocItem
  • QnninGetServerDocItemz
  • QnninSetServerDocItem
  • QnninSetServerDocItemz

O item de documento do servidor é um item do documento do servidor Domino no banco de dados do diretório do Domino (names.nsf). A API QnninGetServerDocItemz é idêntica à API QnninGetServerDocItem, exceto pelo fato de que os parâmetros de cadeia de caractere de entrada são inseridos como cadeia de caractere finalizada com null. É o mesmo que QnninSetServerDocItemz e QnninSetServerDocItem.

Abaixo, exemplificamos como usar QnninGetServerDocItemz.

Parâmetros de QnninGetServerDocItemz:

  1. Nome do servidor
    Input:Char(255)O nome do servidor Domino do qual deseja obter informações.
  2. Nome do item de documento do servidor
    Input:Char(*)O nome do item para a entrada no documento do servidor.
  3. Buffer de retorno
    Output:Char(*)O buffer usado para armazenar o valor do item.
  4. Tamanho do buffer de retorno
    Input:Binary(4)O tamanho do buffer de retorno.
  5. Bytes de retorno disponíveis
    Output:Binary(*)O número de bytes retornados no buffer de retorno.
  6. Tipo de dados do buffer de retorno
    Input:Binary(4)Há três tipos de dados diferentes para o valor do item. TEXT_DATA_TYPE é usado para os dados de texto. FLOAT_DATA_TYPE é usado para os dados flutuantes e INTEGER_DATA_TYPE é para dados de número inteiro.
  7. Código do erro
    I/O: Char(*)Informação de erro retornada.

Neste exemplo, o programa recupera o título do servidor do documento do servidor em names.nsf e define-o para "Domino server for API test".

Listagem 9. Código de amostra para QnninGetServerDocItem e 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);
 }

Dicas ao usar essas APIs

  1. Ao compilar seu programa C, você poderá encontrar as mensagens de erro abaixo:
    #include file "QNNINLDS.H" não encontrado. Certifique-se de que QNOTES esteja em sua lista de bibliotecas. Em seguida, tente novamente.
  2. Um arquivo de cabeçalho H/QNNINLDS na biblioteca QNOTES contém as listas Macros, Structures e Function Prototype para as APIs.
  3. Ao alterar as configurações do notes.ini ou as configurações do documento do servidor, algumas poderão não entrar em vigor até que o servidor Domino seja reiniciado.
  4. Ao lidar com o item de documento do servidor, use o nome de item correto.

Conclusão

Este artigo apresentou um conhecimento básico sobre as APIs exclusivas do Domino para IBM i, em conjunto com amostras de código. Essas APIs fornecem uma maneira fácil de desenvolver programas para gerenciar e operar servidores Domino no IBM i, especialmente para clientes que possuem muitos servidores Domino. Esperamos que este artigo sirva como primeiro passo para que desenvolvedores do Domino no IBM i explorem essas APIs em seus aplicativos.


Recursos

Comentários

developerWorks: Conecte-se

Los campos obligatorios están marcados con un asterisco (*).


Precisa de um ID IBM?
Esqueceu seu ID IBM?


Esqueceu sua senha?
Alterar sua senha

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


A primeira vez que você entrar no developerWorks, um perfil é criado para você. Informações no seu perfil (seu nome, país / região, e nome da empresa) é apresentado ao público e vai acompanhar qualquer conteúdo que você postar, a menos que você opte por esconder o nome da empresa. Você pode atualizar sua conta IBM a qualquer momento.

Todas as informações enviadas são seguras.

Elija su nombre para mostrar



Ao se conectar ao developerWorks pela primeira vez, é criado um perfil para você e é necessário selecionar um nome de exibição. O nome de exibição acompanhará o conteúdo que você postar no developerWorks.

Escolha um nome de exibição de 3 - 31 caracteres. Seu nome de exibição deve ser exclusivo na comunidade do developerWorks e não deve ser o seu endereço de email por motivo de privacidade.

Los campos obligatorios están marcados con un asterisco (*).

(Escolha um nome de exibição de 3 - 31 caracteres.)

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


Todas as informações enviadas são seguras.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=80
Zone=Lotus
ArticleID=754926
ArticleTitle=Gerencie seus servidores IBM i Domino usando APIs
publish-date=08312011