Server and Database Listings
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;
case WM_COMMAND: / message: received a command /
case IDOK: / "OK" box selected? /
EndDialog(hDlg, TRUE); / Exits the dialog box. /
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)
OSLoadString(NULLHANDLE, ERR(sError), String, sizeof(String)-1);
MessageBox (GetFocus(), String, "Notes Error", MB_OK);
* 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.
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) /
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