Skip to content

Server and Database Listings

Chapter 9-6
Server and Database Listings

The samples examined in this chapter demonstrate ways for a C API program to obtain a list of the HCL Domino Servers available in the environment and a list of the Domino databases on a HCL Domino Server.

The first sample, SERVLIST, shows how to obtain a list of the known HCL Domino Servers on all network ports. servlist.c is in the directory samples\admin\servlist. SERVLIST is a Windows program that displays a dialog box showing all available servers, similar to the one displayed by File - Database - Open. SERVLIST is a spare but complete example of C API programming for Windows.

The second sample, FIND_DBS, demonstrates how to use the C API function NSFSearch to find all the Domino databases in a subdirectory on a HCL Domino Server. find_dbs.c is in the directory \samples\admin\find_dbs.


Listing All Known Servers

MainWndProc, the main Windows procedure, processes the FILE_GET_SERVER_LIST message by calling the function ServListDlg, which does the real work of the program.

ServListDlg calls the C API function NSGetServerList to obtain a list of all servers available that are listed in the user's home/mail server's Domino Directory.

servlist.c: Obtaining a List of Server Names


BOOL LNPUBLIC ServListDlg(HWND hDlg, WORD message,
                           WPARAM wParam, LPARAM lParam)
{
 STATUS    sError = NOERROR;       / Error return from API routines. /
 char      ServerString[MAXPATH];  / String to hold server names.  /
 LPSTR     szServerString = ServerString;
 USHORT    i;                      / Loop counter. /
 HANDLE    hServerList=NULLHANDLE; / Handle returned by NSGetServerList /
 BYTE far pServerList;            / Pointer to start of Server List /
 WORD      wServerCount;           / Number of servers in list. /
 WORD far pwServerLength;         / Index to array of servername lens /
 BYTE far pServerName;

  switch (message)
 {
   case WM_COMMAND:            / message: received a command      /

      switch (wParam)
     {
       case IDOK:           / "OK" box selected?               /
       EndDialog(hDlg, TRUE);  / Exits the dialog box.        /
       return (TRUE);
      }
     break;

    case WM_INITDIALOG:         / message: initialize dialog box   /

      /
      *  Get the list of available servers. Setting the first parameter
      *  to NULL gets a list of known servers on all ports.
      /

      sError = NSGetServerList( (char far ) NULL, &hServerList);

      if (sError != NOERROR)
     {
       char String[256];
       OSLoadString(NULLHANDLE, ERR(sError), String, sizeof(String)-1);
       MessageBox (GetFocus(), String, "Notes Error", MB_OK);
       return (TRUE);
     }

      /
      *  Lock the handle returned to get the list of servers. The buffer
         returned is in the following format:
     
      *  The first WORD specifies the number of servernames in the buffer.
      *  This is followed by a series of N WORDS (N being the number
      *  of servernames in the buffer), specifying the length of each
      *  servername (without any NULL terminator). This is then
      *  followed by the packed list of servernames.
      /

      /
      *  First, get a pointer to the start of the buffer, and then
      *  get the number of servernames in the list.
      /

      pServerList  = (BYTE far )OSLockObject(hServerList);
     wServerCount = (WORD )pServerList;

      /
      *  Now, get a pointer to the first member in the array of
      *  servername lengths.
      /

      pwServerLength = (WORD )(pServerList + sizeof(WORD));

      /
      *  Now get a pointer to the first servername in the packed list.
      /

      pServerName = (BYTE far ) pServerList + sizeof(wServerCount) +
                         ((wServerCount) * sizeof(WORD));

      /
      *  Copy each servername to a local character buffer, add a null
      *  terminator, then add the server name to the listbox.
      /

      for (i=0; i<wServerCount; pServerName+=pwServerLength[i], i++)
     {
       memmove (szServerString, pServerName, pwServerLength[i]);
       szServerString[pwServerLength[i]] = '\0';
       SendDlgItemMessage(hDlg, SERVLIST_LISTBOX, LB_ADDSTRING,
                                  (WORD) NULL, (LONG)(LPSTR) szServerString);
     }

      /
      *  Unlock and free the memory associated with the server list.
      /

      OSUnlockObject (hServerList);
     OSMemFree (hServerList);

    }

    return (FALSE);                 / Didn't process a message. */
}

ServListDlg calls the function NSGetServerList, specifying NULL as the first parameter. NSGetServerList returns a list of all servers known on the port named in its first parameter. If the first parameter is set to NULL, NSGetServerList returns a list of all servers known on any network port. NSGetServerList gets the list of servers from the Server/Server view of the user's home server Domino Directory. Servers not listed there are not returned from NSGetServerList.

NSGetServerList returns a handle to a buffer containing the list of server names. The buffer has the following format:

  • One WORD containing a number N, the number of server names in the list, followed by
  • An array of N WORDs, each containing the length of the corresponding server name (without null terminator)
  • A packed character list of server names


ServListDlg parses the buffer returned by NSGetServerList, adding each server name to a listbox. When it has processed all server names, ServListDlg returns and the listbox containing the server names is displayed.


Listing All the Databases in a Directory

find_dbs.c finds all the Domino databases in a directory. It works for local or remote databases and also lists any subdirectories it finds. Note the program's use of NSFSearch to find all the databases.

find_dbs.c: Using NSFSearch to Find Databases

/ Call NSFSearch to find files in the directory. For each file found,
call an action routine. /
   if (error = NSFSearch (
     dir_handle,       / directory handle           /
     NULLHANDLE,       / selection formula          /
     NULL,             / title of view in formula   /
     SEARCH_FILETYPE + / search for files           /
     SEARCH_SUMMARY,   / return a summary buffer    /
     FILE_DBANY +      / find any .NS? file         /
     FILE_DIRS +       / find subdirectories        /
     FILE_NOUPDIRS,    / don't find the ".." dir    /
     NULL,             / starting date              /
     file_action,      / call for each file found   /
     NULL,             / argument to action routine /
     NULL))            / returned ending date (unused) /

      {
     NSFDbClose (dir_handle);
     return (ERR(error));
     }
This call to NSFSearch directs it to search for all .ns? files and subdirectories (but not parent directories), return a summary buffer, and call file_action for each target found that matches the selection criteria.

file_action does most of its work by calling print_file_summary. It is a useful routine to step through because it navigates a summary buffer. Here is an example of output from print_file_summary to check while you trace:

find_dbs.c: Output to Use for Stepping Through print_file_summary
     $TITLE:  API_DOC.NSF<br>
     $Path:  API_DOC.NSF<br>
     $Type:  $NOTEFILE<br>
     $Modified:  12/16/91 06:13:32 PM<br>
     $Length:  49152<br>
     $Info:  Notes API Docs