notes API 8.5

Licensed Materials - Property of IBM CZN2HEN CZN2IEN CZN2JEN (c) Copyright IBM Corporation 1996, 2010 All rights reserved. IBM, the IBM logo, Lotus, Lotus Notes and Domino are trademarks of IBM Corporation in the United States, other countries, or both. PROGRAM ------- Clumon - Advanced Server Cluster Monitor sample program. ENVIRONMENTS ------------ Windows (32-bit) IBM AIX IBM i Note: Currently not support 64-bit UI application on Windows 64-bit FILES ----- clumon.c - Main program for Windows version of sample. clumoncm.c - Main program for character mode version (AIX) of sample. clumon.h - Local function prototypes and data definitions for clumon.c. clumon.rc - Resource compiler file for this sample. clfunc.c - Service routines for the UI-specific event handlers. Organized for platform independence, and contains all relevent API function calls. clfunc.h - External function prototypes for routines defined in clfunc.c. clumon.ico - Program Icon mswin32.def - Windows 32-bit definition file for this sample. mswin32.mak - Make file for 32 bit Windows. aix.mak - Make file for IBM AIX. aix64.mak - Make file for IBM AIX64. readme.txt - This file. Descibes the sample and specifies how to use it. clumoni5.c - Main program for IBM i version of sample. mk_cluster_i.clp - Make file (CL Program) for IBM i using ILE C with the source code being an IFS file. mk_cluster_p.clp - Make file (CL Program) for IBM i using ILE C with the source code being in a source physical file. DESCRIPTION ----------- This program illustrates cluster administration through the Advanced Server cluster API. The sample program capabilities include: 1) displaying a Domino server's cluster information; including cluster name, availability index, and other servers that are cluster members, 2) displaying a Domino server database's current mark options associated with a cluster; specifically marked in service, marked out of service, and marked for delete, 3) modifying a Domino server database's current mark options, 4) restricting a Domino server to facilitate database open failover, 5) shutting down a Domino server to facilitate database open failover, 6) setting the Domino server availability threshold to facilitate database open failover, 7) creating and copying replica databases to other Domino servers. NOTES OPERATING ENVIRONMENT REQUIREMENTS ---------------------------------------- I) Cluster Information In order to fully illustrate the capabilities of this sample program, you must have access to at least one server that is configured in a Advanced Server Cluster. For information on how to configure a Domino server within a cluster, refer to the R8 Release Notes and Administrator's Guide databases that were installed with the Domino server. If you specify the name of a server that is not a member of a Domino cluster, an error will be returned by the program when trying to obtain the server's cluster information. Additionally, your Notes Workstation's location record must be configured as follows: 1) The "Mail domain" must be set to the domain name for the server(s) in the cluster. 2) The "Home/mail server" must be set to a server in this domain. Refer to the Notes V8 Administrator's Guide for more information on configuring location records. The sample may not work properly if you are trying to obtain cluster information for a cluster/server in a domain other than that specified in your location record. II) Database Mark Option Management You can specify any database on the server when viewing the current database mark options from the sample. When managing/modifying the database mark options from the sample, it is highly recommended that you use the supplied sample database file, MarkTest.nsf. Copy this file from the NOTEDATA subdirectory of the toolkit into the data directory of the Domino servers in the cluster. Note that if you supply your own database, then you must have at least "Designer" access in order to mark the database in/out of service, and "Manager" access to mark the database for deletion. III) Database Replicas In order to successfully create replica databases to the servers in your cluster, you must have privileges to create replica databases on the targeted servers. This information can be configured via the N&A book of the server domain. IV) Server Configuration Management The CLUMON sample programatically uses remote server console commands to manage the server configuration information related to server restriction, threshold manipulation, shutdown. As such, you must have administrative privileges on each server that you plan to remotely manage. This information can be configured via the N&A book of the server domain. RUNNING Clumon -------------- Before you run the sample program (clumon.exe), verify that you have met the requirements specified for accessing the exposed features of a clustered Domino server, as described in the previous section. Windows ------- From the File-Run dialog of Windows NT, or the Program-Run dialog of Windows95, or the DOS command prompt, run the program executable CLUMON.EXE. A simple Windows interface will appear with the following three menu options: File, Information, Administration. AIX --- From the command shell, run the program executable clumon. The Main Menu for the the sample program will be displayed. I5OS ---- RUNDOMCMD SERVER(<servername>) CMD(CALL PGM(QNTCSDK/CLUMONI5)) BATCH(*NO) USING Clumon ------------ The following describes the menu item options for the Windows program version. The relevant Character Mode program menu items are referenced in parentheses below the Windows items. Instead of using Windows dialogs, the Character Mode program prompts the user for the information. Information-Cluster... (Main Menu-1. Cluster Information) ---------------------------------- This menu item displays a modal dialog box, titled "Cluster Information". When a server name is entered in the "Server Name:" editbox, clicking on the "Info" button (or hitting <Enter>) will display the Cluster Name, Availability, the number of Cluster Mates, and a list of Cluster Mates for that server in the relevant "Cluster Information" group text fields and listbox. If the server cannot be found, is not a member of a cluster, or does not have any clustermates, the sample will display an appropriate messagebox. Likewise, all API errors and their appropriate descriptions will be displayed. Clicking the "Done" button will end the dialog box and return focus to the main window. NOTE: The server's availability index is a value (between 0 and 100) that is computed based on the current activity occurring on the server, for example session and database activity. The server availability index works in conjunction with the configured server availability threshold (also a value from 0 to 100). When the availability drops below the threshold, the server is in a "busy" state, meaning that it will not accept any new session activity. This is true until the availability index rises above the threshold. Refer to the "Administration-Server Availability Threshold" section below for information on configuring this threshold value. Information-Database Mark Options... (Main Menu-2. Cluster Administration) ------------------------------------- This menu item displays a modal dialog box, titled "DB Mark Options Information". After a server/domain name is entered in the "Server Name:" editbox and a database name (e.g. MarkTest) is entered in the "Database Name:" editbox, clic