mgmapi.h 32.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
/* Copyright (C) 2003 MySQL AB

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */

#ifndef MGMAPI_H
#define MGMAPI_H

/**
21
 * @mainpage MySQL Cluster Management API
22
 *
23 24 25 26 27 28
 * The MySQL Cluster Management API (MGM API) is a C language API
 * that is used for:
 * - Starting and stopping database nodes (ndbd processes)
 * - Starting and stopping Cluster backups
 * - Controlling the NDB Cluster log
 * - Performing other administrative tasks
29
 *
30
 * @section  secMgmApiGeneral General Concepts
31
 *
32
 * Each MGM API function needs a management server handle
33
 * of type @ref NdbMgmHandle.
34
 * This handle is created by calling the function 
35 36
 * function ndb_mgm_create_handle() and freed by calling 
 * ndb_mgm_destroy_handle().
37
 *
38 39 40 41
 * A function can return any of the following:
 *  -# An integer value, with
 *     a value of <b>-1</b> indicating an error.
 *  -# A non-constant pointer value.  A <var>NULL</var> value indicates an error;
42
 *     otherwise, the return value must be freed
43 44 45
 *     by the programmer
 *  -# A constant pointer value, with a <var>NULL</var> value indicating an error.
 *     The returned value should <em>not</em> be freed.
46
 *
47
 * Error conditions can be identified by using the appropriate
48 49
 * error-reporting functions ndb_mgm_get_latest_error() and 
 * @ref ndb_mgm_error.
50
 *
51
 * Here is an example using the MGM API (without error handling for brevity's sake).
52 53 54 55 56 57
 * @code
 *   NdbMgmHandle handle= ndb_mgm_create_handle();
 *   ndb_mgm_connect(handle,0,0,0);
 *   struct ndb_mgm_cluster_state *state= ndb_mgm_get_status(handle);
 *   for(int i=0; i < state->no_of_nodes; i++) 
 *   {
58
 *     printf("node with ID=%d ", state->node_states[i].node_id);
59 60 61 62 63 64 65 66
 *     if(state->node_states[i].version != 0)
 *       printf("connected\n");
 *     else
 *       printf("not connected\n");
 *   }
 *   free((void*)state);
 *   ndb_mgm_destroy_handle(&handle);
 * @endcode
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
 *
 * @section secLogEvents  Log Events
 *
 * The database nodes and management server(s) regularly and on specific
 * occations report on various log events that occurs in the cluster. These
 * log events are written to the cluster log.  Optionally a mgmapi client
 * may listen to these events by using the method ndb_mgm_listen_event().
 * Each log event belongs to a category, @ref ndb_mgm_event_category, and
 * has a severity, @ref ndb_mgm_event_severity, associated with it.  Each
 * log event also has a level (0-15) associated with it.
 *
 * Which log events that come out is controlled with ndb_mgm_listen_event(),
 * ndb_mgm_set_clusterlog_loglevel(), and 
 * ndb_mgm_set_clusterlog_severity_filter().
 *
 * Below is an example of how to listen to events related to backup.
 *
 * @code
 *   int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 };
 *   int fd = ndb_mgm_listen_event(handle, filter);
 * @endcode
88 89 90 91 92 93
 */

/** @addtogroup MGM_C_API
 *  @{
 */

94
#include <ndb_types.h>
tomas@poseidon.bredbandsbolaget.se's avatar
tomas@poseidon.bredbandsbolaget.se committed
95 96
#include "mgmapi_config_parameters.h"

97 98 99 100 101 102 103 104 105 106 107 108 109
#ifdef __cplusplus
extern "C" {
#endif

  /**
   * The NdbMgmHandle.
   */
  typedef struct ndb_mgm_handle * NdbMgmHandle;

  /**
   *   NDB Cluster node types
   */
  enum ndb_mgm_node_type {
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
    NDB_MGM_NODE_TYPE_UNKNOWN = -1  /** Node type not known*/
    ,NDB_MGM_NODE_TYPE_API    /** An application node (API) */
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
    = NODE_TYPE_API
#endif
    ,NDB_MGM_NODE_TYPE_NDB    /** A database node (DB) */
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
    = NODE_TYPE_DB
#endif
    ,NDB_MGM_NODE_TYPE_MGM    /** A mgmt server node (MGM)*/
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
    = NODE_TYPE_MGM
#endif
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
    ,NDB_MGM_NODE_TYPE_REP = NODE_TYPE_REP  /** A replication node */
    ,NDB_MGM_NODE_TYPE_MIN     = 0          /** Min valid value*/
    ,NDB_MGM_NODE_TYPE_MAX     = 3          /** Max valid value*/
#endif
128 129 130 131 132 133
  };

  /**
   *   Database node status
   */
  enum ndb_mgm_node_status {
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
    /** Node status not known*/
    NDB_MGM_NODE_STATUS_UNKNOWN       = 0,
    /** No contact with node*/
    NDB_MGM_NODE_STATUS_NO_CONTACT    = 1,
    /** Has not run starting protocol*/
    NDB_MGM_NODE_STATUS_NOT_STARTED   = 2,
    /** Is running starting protocol*/
    NDB_MGM_NODE_STATUS_STARTING      = 3,
    /** Running*/
    NDB_MGM_NODE_STATUS_STARTED       = 4,
    /** Is shutting down*/
    NDB_MGM_NODE_STATUS_SHUTTING_DOWN = 5,
    /** Is restarting*/
    NDB_MGM_NODE_STATUS_RESTARTING    = 6,
    /** Maintenance mode*/
    NDB_MGM_NODE_STATUS_SINGLEUSER    = 7,
    /** Resume mode*/
    NDB_MGM_NODE_STATUS_RESUME        = 8,
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
    /** Min valid value*/
    NDB_MGM_NODE_STATUS_MIN           = 0,
    /** Max valid value*/
    NDB_MGM_NODE_STATUS_MAX           = 8
#endif
158 159 160 161 162 163
  };

  /**
   *    Error codes
   */
  enum ndb_mgm_error {
164
    /** Not an error */
165 166 167
    NDB_MGM_NO_ERROR = 0,

    /* Request for service errors */
168
    /** Supplied connectstring is illegal */
169
    NDB_MGM_ILLEGAL_CONNECT_STRING = 1001,
170
    /** Supplied NdbMgmHandle is illegal */
171
    NDB_MGM_ILLEGAL_SERVER_HANDLE = 1005,
172
    /** Illegal reply from server */
173
    NDB_MGM_ILLEGAL_SERVER_REPLY = 1006,
174
    /** Illegal number of nodes */
175
    NDB_MGM_ILLEGAL_NUMBER_OF_NODES = 1007,
176
    /** Illegal node status */
177
    NDB_MGM_ILLEGAL_NODE_STATUS = 1008,
178
    /** Memory allocation error */
179
    NDB_MGM_OUT_OF_MEMORY = 1009,
180
    /** Management server not connected */
181
    NDB_MGM_SERVER_NOT_CONNECTED = 1010,
182
    /** Could not connect to socker */
183 184 185
    NDB_MGM_COULD_NOT_CONNECT_TO_SOCKET = 1011,

    /* Service errors - Start/Stop Node or System */
186
    /** Start failed */
187
    NDB_MGM_START_FAILED = 2001,
188
    /** Stop failed */
189
    NDB_MGM_STOP_FAILED = 2002,
190
    /** Restart failed */
191 192 193
    NDB_MGM_RESTART_FAILED = 2003,

    /* Service errors - Backup */
194
    /** Unable to start backup */
195
    NDB_MGM_COULD_NOT_START_BACKUP = 3001,
196
    /** Unable to abort backup */
197 198 199
    NDB_MGM_COULD_NOT_ABORT_BACKUP = 3002,

    /* Service errors - Single User Mode */
200
    /** Unable to enter single user mode */
201
    NDB_MGM_COULD_NOT_ENTER_SINGLE_USER_MODE = 4001,
202
    /** Unable to exit single user mode */
203 204 205
    NDB_MGM_COULD_NOT_EXIT_SINGLE_USER_MODE = 4002,

    /* Usage errors */
206
    /** Usage error */
207
    NDB_MGM_USAGE_ERROR = 5001
208 209
  };

210
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
211 212
  struct Ndb_Mgm_Error_Msg {
    enum ndb_mgm_error  code;
213
    const char *        msg;
214 215 216 217
  };
  const struct Ndb_Mgm_Error_Msg ndb_mgm_error_msgs[] = {
    { NDB_MGM_NO_ERROR, "No error" },

218
    /* Request for service errors */
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
    { NDB_MGM_ILLEGAL_CONNECT_STRING, "Illegal connect string" },
    { NDB_MGM_ILLEGAL_SERVER_HANDLE, "Illegal server handle" },
    { NDB_MGM_ILLEGAL_SERVER_REPLY, "Illegal reply from server" },
    { NDB_MGM_ILLEGAL_NUMBER_OF_NODES, "Illegal number of nodes" },
    { NDB_MGM_ILLEGAL_NODE_STATUS, "Illegal node status" },
    { NDB_MGM_OUT_OF_MEMORY, "Out of memory" },
    { NDB_MGM_SERVER_NOT_CONNECTED, "Management server not connected" },
    { NDB_MGM_COULD_NOT_CONNECT_TO_SOCKET, "Could not connect to socket" },

    /* Service errors - Start/Stop Node or System */
    { NDB_MGM_START_FAILED, "Start failed" },
    { NDB_MGM_STOP_FAILED, "Stop failed" },
    { NDB_MGM_RESTART_FAILED, "Restart failed" },

    /* Service errors - Backup */
    { NDB_MGM_COULD_NOT_START_BACKUP, "Could not start backup" },
    { NDB_MGM_COULD_NOT_ABORT_BACKUP, "Could not abort backup" },
236

237
    /* Service errors - Single User Mode */
238
    { NDB_MGM_COULD_NOT_ENTER_SINGLE_USER_MODE,
239
      "Could not enter single user mode" },
240
    { NDB_MGM_COULD_NOT_EXIT_SINGLE_USER_MODE,
241 242 243 244 245
      "Could not exit single user mode" },

    /* Usage errors */
    { NDB_MGM_USAGE_ERROR,
      "Usage error" }
246
  };
247
  const int ndb_mgm_noOfErrorMsgs =
248
  sizeof(ndb_mgm_error_msgs)/sizeof(struct Ndb_Mgm_Error_Msg);
249
#endif
250 251

  /**
252 253 254 255
   *   Status of a node in the cluster
   *
   *   Sub-structure in enum ndb_mgm_cluster_state
   *   returned by ndb_mgm_get_status()
256 257
   *
   *   @note @ref node_status, @ref start_phase, @ref dynamic_id 
258
   *         and @ref node_group are relevant only for database nodes
259 260
   */
  struct ndb_mgm_node_state {
261
    /** NDB Cluster node ID*/
262 263 264 265 266 267 268
    int node_id;
    /** Type of NDB Cluster node*/
    enum ndb_mgm_node_type   node_type;
   /** State of node*/
    enum ndb_mgm_node_status node_status;
    /** Start phase.
     *
269 270
     *  @note Start phase is only valid if the <var>node_type</var> is
     *        NDB_MGM_NODE_TYPE_NDB and the <var>node_status</var> is 
271 272 273
     *        NDB_MGM_NODE_STATUS_STARTING
     */
    int start_phase;
274
    /** ID for heartbeats and master take-over (only valid for DB nodes)
275 276 277 278 279 280 281 282 283 284
     */
    int dynamic_id;
    /** Node group of node (only valid for DB nodes)*/
    int node_group;
    /** Internal version number*/
    int version;
    /** Number of times node has connected or disconnected to the 
     *  management server
     */
    int connect_count;
285 286 287
    /** IP address of node when it connected to the management server.
     *  @note This value will be empty if the management server has restarted
     *        since the node last connected.
288 289 290 291 292 293
     */
    char connect_address[
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
			 sizeof("000.000.000.000")+1
#endif
    ];
294 295 296
  };

  /**
297
   *   State of all nodes in the cluster; returned from 
298
   *   ndb_mgm_get_status()
299 300
   */
  struct ndb_mgm_cluster_state {
301
    /** Number of entries in the node_states array */
302 303 304 305 306 307 308
    int no_of_nodes;
    /** An array with node_states*/
    struct ndb_mgm_node_state node_states[
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
					  1
#endif
    ];
309 310 311
  };

  /**
312
   *   Default reply from the server (reserved for future use)
313 314
   */
  struct ndb_mgm_reply {
315 316 317 318
    /** 0 if successful, otherwise error code. */
    int return_code;
    /** Error or reply message.*/
    char message[256];
319 320
  };

321
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
322 323 324 325
  /**
   *   Default information types
   */
  enum ndb_mgm_info {
326 327 328 329
    /** ?*/
    NDB_MGM_INFO_CLUSTER,
    /** Cluster log*/
    NDB_MGM_INFO_CLUSTERLOG
330 331 332 333 334 335 336
  };

  /**
   *   Signal log modes
   *   (Used only in the development of NDB Cluster.)
   */
  enum ndb_mgm_signal_log_mode {
337 338 339 340 341 342 343 344
    /** Log receiving signals */
    NDB_MGM_SIGNAL_LOG_MODE_IN,
    /** Log sending signals*/
    NDB_MGM_SIGNAL_LOG_MODE_OUT,
    /** Log both sending/receiving*/
    NDB_MGM_SIGNAL_LOG_MODE_INOUT,
    /** Log off*/
    NDB_MGM_SIGNAL_LOG_MODE_OFF
345
  };
346
#endif
347 348

  /**
349 350 351
   *   Log event severities (used to filter the cluster log, 
   *   ndb_mgm_set_clusterlog_severity_filter(), and filter listening to events
   *   ndb_mgm_listen_event())
352
   */
353 354
  enum ndb_mgm_event_severity {
    NDB_MGM_ILLEGAL_EVENT_SEVERITY = -1,
355
    /*  Must be a nonnegative integer (used for array indexing) */
356 357
    /** Cluster log on */
    NDB_MGM_EVENT_SEVERITY_ON    = 0,
358
    /** Used in NDB Cluster developement */
359
    NDB_MGM_EVENT_SEVERITY_DEBUG = 1,
360
    /** Informational messages*/
361
    NDB_MGM_EVENT_SEVERITY_INFO = 2,
tomas@poseidon.ndb.mysql.com's avatar
Merge  
tomas@poseidon.ndb.mysql.com committed
362
    /** Conditions that are not error condition, but might require handling.
363
     */
364
    NDB_MGM_EVENT_SEVERITY_WARNING = 3,
365
    /** Conditions that, while not fatal, should be corrected. */
366
    NDB_MGM_EVENT_SEVERITY_ERROR = 4,
367
    /** Critical conditions, like device errors or out of resources */
368
    NDB_MGM_EVENT_SEVERITY_CRITICAL = 5,
369 370 371
    /** A condition that should be corrected immediately,
     *  such as a corrupted system
     */
372
    NDB_MGM_EVENT_SEVERITY_ALERT = 6,
373
    /* must be next number, works as bound in loop */
374
    /** All severities */
375
    NDB_MGM_EVENT_SEVERITY_ALL = 7
376 377 378
  };

  /**
379 380
   *  Log event categories, used to set filter level on the log events using
   *  ndb_mgm_set_clusterlog_loglevel() and ndb_mgm_listen_event()
381 382
   */
  enum ndb_mgm_event_category {
383
    /**
384
     * Invalid log event category
385 386
     */
    NDB_MGM_ILLEGAL_EVENT_CATEGORY = -1,
387
    /**
388
     * Log events during all kinds of startups
389 390 391
     */
    NDB_MGM_EVENT_CATEGORY_STARTUP = CFG_LOGLEVEL_STARTUP,
    /**
392
     * Log events during shutdown
393 394 395
     */
    NDB_MGM_EVENT_CATEGORY_SHUTDOWN = CFG_LOGLEVEL_SHUTDOWN,
    /**
396
     * Statistics log events
397 398
     */
    NDB_MGM_EVENT_CATEGORY_STATISTIC = CFG_LOGLEVEL_STATISTICS,
399
    /**
400
     * Log events related to checkpoints
401
     */
402
    NDB_MGM_EVENT_CATEGORY_CHECKPOINT = CFG_LOGLEVEL_CHECKPOINT,
403
    /**
404
     * Log events during node restart
405
     */
406
    NDB_MGM_EVENT_CATEGORY_NODE_RESTART = CFG_LOGLEVEL_NODERESTART,
407
    /**
408
     * Log events related to connections between cluster nodes
409
     */
410
    NDB_MGM_EVENT_CATEGORY_CONNECTION = CFG_LOGLEVEL_CONNECTION,
411
    /**
412
     * Backup related log events
413 414
     */
    NDB_MGM_EVENT_CATEGORY_BACKUP = CFG_LOGLEVEL_BACKUP,
415 416 417 418 419
    /**
     * Congestion related log events
     */
    NDB_MGM_EVENT_CATEGORY_CONGESTION = CFG_LOGLEVEL_CONGESTION,
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
420 421 422
    /**
     * Loglevel debug
     */
423
    NDB_MGM_EVENT_CATEGORY_DEBUG = CFG_LOGLEVEL_DEBUG,
424
#endif
425
    /**
426
     * Uncategorized log events (severity info)
427
     */
428
    NDB_MGM_EVENT_CATEGORY_INFO = CFG_LOGLEVEL_INFO,
429
    /**
430
     * Uncategorized log events (severity warning or higher)
431
     */
432
    NDB_MGM_EVENT_CATEGORY_ERROR = CFG_LOGLEVEL_ERROR,
433
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
434 435
    NDB_MGM_MIN_EVENT_CATEGORY = CFG_MIN_LOGLEVEL,
    NDB_MGM_MAX_EVENT_CATEGORY = CFG_MAX_LOGLEVEL
436
#endif
437
  };
438

439
  /***************************************************************************/
440
  /**
441 442 443 444 445
   * @name Functions: Error Handling
   * @{
   */

  /**
446 447
   *  Get the most recent error associated with the management server whose handle 
   *  is used as the value of <var>handle</var>.
448 449 450 451 452 453 454
   *
   * @param   handle        Management handle
   * @return                Latest error code
   */
  int ndb_mgm_get_latest_error(const NdbMgmHandle handle);

  /**
455
   * Get the most recent general error message associated with a handle
456 457 458 459 460 461 462
   *
   * @param   handle        Management handle.
   * @return                Latest error message
   */
  const char * ndb_mgm_get_latest_error_msg(const NdbMgmHandle handle);

  /**
463
   * Get the most recent error description associated with a handle
464
   *
465
   * The error description gives some additional information regarding
466 467 468 469 470 471 472 473 474
   * the error message.
   *
   * @param   handle        Management handle.
   * @return                Latest error description
   */
  const char * ndb_mgm_get_latest_error_desc(const NdbMgmHandle handle);

#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
  /**
475
   * Get the most recent internal source code error line associated with a handle
476 477 478
   *
   * @param   handle        Management handle.
   * @return                Latest internal source code line of latest error
479
   * @deprecated
480 481 482 483 484
   */
  int ndb_mgm_get_latest_error_line(const NdbMgmHandle handle);
#endif

  /** @} *********************************************************************/
485
  /**
486 487 488 489
   * @name Functions: Create/Destroy Management Server Handles
   * @{
   */

490
  /**
491
   * Create a handle to a management server.
492
   *
493
   * @return                 A management handle<br>
494
   *                         or <var>NULL</var> if no management handle could be created.
495 496
   */
  NdbMgmHandle ndb_mgm_create_handle();
497

498
  /**
499
   * Destroy a management server handle.
500 501 502 503
   *
   * @param   handle        Management handle
   */
  void ndb_mgm_destroy_handle(NdbMgmHandle * handle);
504

505
  /** @} *********************************************************************/
506
  /**
507 508 509 510
   * @name Functions: Connect/Disconnect Management Server
   * @{
   */

511
  /**
512
   * Sets the connectstring for a management server
513 514
   *
   * @param   handle         Management handle
515
   * @param   connect_string Connect string to the management server,
516 517
   *
   * @return                -1 on error.
518 519 520 521 522
   *
   * @code
   * <connectstring> := [<nodeid-specification>,]<host-specification>[,<host-specification>]
   * <nodeid-specification> := nodeid=<id>
   * <host-specification> := <host>[:<port>]
tomas@poseidon.ndb.mysql.com's avatar
Merge  
tomas@poseidon.ndb.mysql.com committed
523
   * <id> is an integer greater than 0 identifying a node in config.ini
524
   * <port> is an integer referring to a regular unix port
525
   * <host> is a string containing a valid network host address
526
   * @endcode
527 528 529 530
   */
  int ndb_mgm_set_connectstring(NdbMgmHandle handle,
				const char *connect_string);

531
  /**
532
   * Gets the connectstring used for a connection
533
   *
534 535
   * @note This function returns the default connectstring if no call to 
   *       ndb_mgm_set_connectstring() has been performed
536 537 538 539 540 541 542
   *
   * @param   handle         Management handle
   *
   * @return                 connectstring
   */
  const char *ndb_mgm_get_connectstring(NdbMgmHandle handle, char *buf, int buf_sz);

543
  /**
544
   * Connects to a management server. Connectstring is set by
545
   * ndb_mgm_set_connectstring().
546 547 548 549
   *
   * @param   handle        Management handle.
   * @return                -1 on error.
   */
550 551
  int ndb_mgm_connect(NdbMgmHandle handle, int no_retries,
		      int retry_delay_in_seconds, int verbose);
552

553
  /**
554
   * Disconnects from a management server
555 556 557 558 559
   *
   * @param  handle         Management handle.
   * @return                -1 on error.
   */
  int ndb_mgm_disconnect(NdbMgmHandle handle);
560 561

  /**
562
   * Gets connection node ID
563 564 565
   *
   * @param   handle         Management handle
   *
566
   * @return                 Node ID; 0 indicates that no node ID has been
567
   *                         specified
568 569 570
   */
  int ndb_mgm_get_configuration_nodeid(NdbMgmHandle handle);

571
  /**
572
   * Gets connection port
573 574 575 576 577 578 579
   *
   * @param   handle         Management handle
   *
   * @return                 port
   */
  int ndb_mgm_get_connected_port(NdbMgmHandle handle);

580
  /**
581
   * Gets connection host
582 583 584 585 586 587 588
   *
   * @param   handle         Management handle
   *
   * @return                 hostname
   */
  const char *ndb_mgm_get_connected_host(NdbMgmHandle handle);

589
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
590
  /** @} *********************************************************************/
591
  /**
592
   * @name Functions: Used to convert between different data formats
593 594 595 596
   * @{
   */

  /**
597
   * Converts a string to an <var>ndb_mgm_node_type</var> value
598 599 600 601 602 603 604
   *
   * @param   type          Node type as string.
   * @return                NDB_MGM_NODE_TYPE_UNKNOWN if invalid string.
   */
  enum ndb_mgm_node_type ndb_mgm_match_node_type(const char * type);

  /**
605
   * Converts an ndb_mgm_node_type to a string
606 607
   *
   * @param   type          Node type.
608
   * @return                <var>NULL</var> if invalid ID.
609 610 611
   */
  const char * ndb_mgm_get_node_type_string(enum ndb_mgm_node_type type);

612
  /**
613
   * Converts an ndb_mgm_node_type to a alias string
614 615
   *
   * @param   type          Node type.
616
   * @return                <var>NULL</var> if the ID is invalid.
617
   */
618 619
  const char * ndb_mgm_get_node_type_alias_string(enum ndb_mgm_node_type type,
						  const char **str);
620

621
  /**
622
   * Converts a string to a <var>ndb_mgm_node_status</var> value
623 624 625 626 627 628 629
   *
   * @param   status        NDB node status string.
   * @return                NDB_MGM_NODE_STATUS_UNKNOWN if invalid string.
   */
  enum ndb_mgm_node_status ndb_mgm_match_node_status(const char * status);

  /**
630
   * Converts an ID to a string
631 632
   *
   * @param   status        NDB node status.
633
   * @return                <var>NULL</var> if invalid ID.
634 635 636
   */
  const char * ndb_mgm_get_node_status_string(enum ndb_mgm_node_status status);

637
  const char * ndb_mgm_get_event_severity_string(enum ndb_mgm_event_severity);
638 639
  ndb_mgm_event_category ndb_mgm_match_event_category(const char *);
  const char * ndb_mgm_get_event_category_string(enum ndb_mgm_event_category);
640
#endif
641

642
  /** @} *********************************************************************/
643
  /**
644
   * @name Functions: Cluster status
645 646 647 648
   * @{
   */

  /**
649
   * Gets status of the nodes in an NDB Cluster
650
   *
651
   * @note The caller must free the pointer returned by this function.
652 653
   *
   * @param   handle        Management handle.
654
   *
655
   * @return                Cluster state (or <var>NULL</var> on error).
656 657 658 659
   */
  struct ndb_mgm_cluster_state * ndb_mgm_get_status(NdbMgmHandle handle);

  /** @} *********************************************************************/
660 661
  /**
   * @name Functions: Start/stop nodes
662 663 664 665
   * @{
   */

  /**
666
   * Stops database nodes
667 668
   *
   * @param   handle        Management handle.
669 670 671
   * @param   no_of_nodes   Number of database nodes to be stopped<br>
   *                          0: All database nodes in cluster<br>
   *                          n: Stop the <var>n</var> node(s) specified in the
672
   *                            array node_list
673
   * @param   node_list     List of node IDs for database nodes to be stopped
674
   *
675
   * @return                Number of nodes stopped (-1 on error)
676
   *
677 678
   * @note    This function is equivalent
   *          to calling ndb_mgm_stop2(handle, no_of_nodes, node_list, 0)
679
   */
680
  int ndb_mgm_stop(NdbMgmHandle handle, int no_of_nodes,
681 682 683
		   const int * node_list);

  /**
684
   * Stops database nodes
685 686
   *
   * @param   handle        Management handle.
687 688 689
   * @param   no_of_nodes   Number of database nodes to stop<br>
   *                          0: All database nodes in cluster<br>
   *                          n: Stop the <var>n</var> node(s) specified in
690
   *                            the array node_list
691 692 693
   * @param   node_list     List of node IDs of database nodes to be stopped
   * @param   abort         Don't perform graceful stop,
   *                        but rather stop immediately
694
   *
695
   * @return                Number of nodes stopped (-1 on error).
696 697 698 699 700 701 702 703
   */
  int ndb_mgm_stop2(NdbMgmHandle handle, int no_of_nodes,
		    const int * node_list, int abort);

  /**
   * Restart database nodes
   *
   * @param   handle        Management handle.
704 705 706
   * @param   no_of_nodes   Number of database nodes to restart<br>
   *                          0: All database nodes in cluster<br>
   *                          n: Restart the <var>n</var> node(s) specified in the
707
   *                            array node_list
708
   * @param   node_list     List of node IDs of database nodes to be restarted
709
   *
710
   * @return                Number of nodes restarted (-1 on error).
711
   *
712
   * @note    This function is equivalent to calling
713 714
   *          ndb_mgm_restart2(handle, no_of_nodes, node_list, 0, 0, 0);
   */
715
  int ndb_mgm_restart(NdbMgmHandle handle, int no_of_nodes,
716 717 718 719 720 721
		      const int * node_list);

  /**
   * Restart database nodes
   *
   * @param   handle        Management handle.
722 723 724
   * @param   no_of_nodes   Number of database nodes to be restarted:<br>
   *                          0: Restart all database nodes in the cluster<br>
   *                          n: Restart the <var>n</var> node(s) specified in the
725
   *                            array node_list
726 727
   * @param   node_list     List of node IDs of database nodes to be restarted
   * @param   initial       Remove filesystem from restarting node(s)
728
   * @param   nostart       Don't actually start node(s) but leave them
729
   *                        waiting for start command
730 731
   * @param   abort         Don't perform graceful restart,
   *                        but rather restart immediately
732
   *
733
   * @return                Number of nodes stopped (-1 on error).
734 735 736 737
   */
  int ndb_mgm_restart2(NdbMgmHandle handle, int no_of_nodes,
		       const int * node_list, int initial,
		       int nostart, int abort);
738

739 740 741 742
  /**
   * Start database nodes
   *
   * @param   handle        Management handle.
743 744 745
   * @param   no_of_nodes   Number of database nodes to be started<br>
   *                        0: Start all database nodes in the cluster<br>
   *                        n: Start the <var>n</var> node(s) specified in
746
   *                            the array node_list
747
   * @param   node_list     List of node IDs of database nodes to be started
748
   *
749
   * @return                Number of nodes actually started (-1 on error).
750
   *
751
   * @note    The nodes to be started must have been started with nostart(-n)
752
   *          argument.
753 754
   *          This means that the database node binary is started and
   *          waiting for a START management command which will
755
   *          actually enable the database node
756 757 758 759 760 761
   */
  int ndb_mgm_start(NdbMgmHandle handle,
		    int no_of_nodes,
		    const int * node_list);

  /** @} *********************************************************************/
762
  /**
763
   * @name Functions: Controlling Clusterlog output
764 765 766 767
   * @{
   */

  /**
768
   * Filter cluster log severities
769 770
   *
   * @param   handle        NDB management handle.
771
   * @param   severity      A cluster log severity to filter.
tomas@poseidon.ndb.mysql.com's avatar
Merge  
tomas@poseidon.ndb.mysql.com committed
772
   * @param   enable        set 1=enable o 0=disable
773
   * @param   reply         Reply message.
774
   *
775 776
   * @return                -1 on error.
   */
777 778 779 780
  int ndb_mgm_set_clusterlog_severity_filter(NdbMgmHandle handle,
					     enum ndb_mgm_event_severity severity,
					     int enable,
					     struct ndb_mgm_reply* reply);
781
  /**
782
   * Get clusterlog severity filter
783
   *
784
   * @param   handle        NDB management handle
785
   *
786
   * @return                A vector of seven elements,
787
   *                        where each element contains
788 789 790
   *                        1 if a severity indicator is enabled and 0 if not.
   *                        A severity level is stored at position
   *                        ndb_mgm_clusterlog_level;
791
   *                        for example the "error" level is stored in position
tomas@poseidon.ndb.mysql.com's avatar
Merge  
tomas@poseidon.ndb.mysql.com committed
792 793 794
   *                        [NDB_MGM_EVENT_SEVERITY_ERROR].
   *                        The first element [NDB_MGM_EVENT_SEVERITY_ON] in 
   *                        the vector signals
795
   *                        whether the cluster log
796 797
   *                        is disabled or enabled.
   */
798
  const unsigned int *ndb_mgm_get_clusterlog_severity_filter(NdbMgmHandle handle);
799 800 801 802 803

  /**
   * Set log category and levels for the cluster log
   *
   * @param   handle        NDB management handle.
804
   * @param   nodeId        Node ID.
805 806 807 808 809
   * @param   category      Event category.
   * @param   level         Log level (0-15).
   * @param   reply         Reply message.
   * @return                -1 on error.
   */
810
  int ndb_mgm_set_clusterlog_loglevel(NdbMgmHandle handle,
811
				      int nodeId,
812
				      enum ndb_mgm_event_category category,
813 814
				      int level,
				      struct ndb_mgm_reply* reply);
815

816
  /** @} *********************************************************************/
817
  /**
818 819 820 821 822
   * @name Functions: Listening to log events
   * @{
   */

  /**
tomas@poseidon.ndb.mysql.com's avatar
Merge  
tomas@poseidon.ndb.mysql.com committed
823
   * Listen to log events. They are read from the return file descriptor
824
   * and the format is textual, and the same as in the cluster log.
825
   *
826
   * @param handle NDB management handle.
827
   * @param filter pairs of { level, ndb_mgm_event_category } that will be
828
   *               pushed to fd, level=0 ends list.
829
   *
tomas@poseidon.ndb.mysql.com's avatar
Merge  
tomas@poseidon.ndb.mysql.com committed
830
   * @return fd    filedescriptor to read events from
831
   */
832
  int ndb_mgm_listen_event(NdbMgmHandle handle, const int filter[]);
833

834
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
835 836 837 838
  /**
   * Set log category and levels for the Node
   *
   * @param   handle        NDB management handle.
839
   * @param   nodeId        Node ID.
840 841 842 843 844 845 846
   * @param   category      Event category.
   * @param   level         Log level (0-15).
   * @param   reply         Reply message.
   * @return                -1 on error.
   */
  int ndb_mgm_set_loglevel_node(NdbMgmHandle handle,
				int nodeId,
847
				enum ndb_mgm_event_category category,
848 849 850 851 852 853 854 855 856 857 858 859
				int level,
				struct ndb_mgm_reply* reply);

  /**
   * Returns the port number where statistics information is sent
   *
   * @param   handle        NDB management handle.
   * @param   reply         Reply message.
   * @return                -1 on error.
   */
  int ndb_mgm_get_stat_port(NdbMgmHandle handle,
			    struct ndb_mgm_reply* reply);
860
#endif
861 862

  /** @} *********************************************************************/
863
  /**
864 865 866 867 868 869 870
   * @name Functions: Backup
   * @{
   */

  /**
   * Start backup
   *
871 872 873 874 875 876 877
   * @param   handle          NDB management handle.
   * @param   wait_completed  0:  Don't wait for confirmation<br>
   *                          1:  Wait for backup to be started<br>
   *                          2:  Wait for backup to be completed
   * @param   backup_id       Backup ID is returned from function.
   * @param   reply           Reply message.
   * @return                  -1 on error.
878
   */
tomas@poseidon.ndb.mysql.com's avatar
tomas@poseidon.ndb.mysql.com committed
879 880
  int ndb_mgm_start_backup(NdbMgmHandle handle, int wait_completed,
			   unsigned int* backup_id,
881 882 883 884 885 886
			   struct ndb_mgm_reply* reply);

  /**
   * Abort backup
   *
   * @param   handle        NDB management handle.
887
   * @param   backup_id     Backup ID.
888 889 890 891 892 893 894 895
   * @param   reply         Reply message.
   * @return                -1 on error.
   */
  int ndb_mgm_abort_backup(NdbMgmHandle handle, unsigned int backup_id,
			   struct ndb_mgm_reply* reply);


  /** @} *********************************************************************/
896
  /**
897 898 899 900 901
   * @name Functions: Single User Mode
   * @{
   */

  /**
902
   * Enter Single user mode
903 904
   *
   * @param   handle        NDB management handle.
905
   * @param   nodeId        Node ID of the single user node
906 907 908 909 910
   * @param   reply         Reply message.
   * @return                -1 on error.
   */
  int ndb_mgm_enter_single_user(NdbMgmHandle handle, unsigned int nodeId,
				struct ndb_mgm_reply* reply);
911

912
  /**
913
   * Exit Single user mode
914 915
   *
   * @param   handle        NDB management handle.
916
   * @param   nodeId        Node ID of the single user node
917
   * @param   reply         Reply message.
918
   *
919 920
   * @return                -1 on error.
   */
921
  int ndb_mgm_exit_single_user(NdbMgmHandle handle,
922
			       struct ndb_mgm_reply* reply);
923

924
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
925
  /** @} *********************************************************************/
926
  /**
927 928
   * @name Configuration handling
   * @{
929
   */
930

931 932 933 934
  /**
   * Get configuration
   * @param   handle     NDB management handle.
   * @param   version    Version of configuration, 0 means latest
935
   *                     (Currently this is the only supported value for this parameter)
936 937 938
   *
   * @return configuration
   *
939
   * @note The caller is responsible for calling ndb_mgm_destroy_configuration()
940 941 942
   */
  struct ndb_mgm_configuration * ndb_mgm_get_configuration(NdbMgmHandle handle,
							   unsigned version);
943
  void ndb_mgm_destroy_configuration(struct ndb_mgm_configuration *);
tomas@poseidon.bredbandsbolaget.se's avatar
tomas@poseidon.bredbandsbolaget.se committed
944 945

  int ndb_mgm_alloc_nodeid(NdbMgmHandle handle,
946
			   unsigned version, int nodetype);
947 948 949 950 951 952 953 954
  /**
   * Config iterator
   */
  typedef struct ndb_mgm_configuration_iterator ndb_mgm_configuration_iterator;

  ndb_mgm_configuration_iterator* ndb_mgm_create_configuration_iterator
  (struct ndb_mgm_configuration *, unsigned type_of_section);
  void ndb_mgm_destroy_iterator(ndb_mgm_configuration_iterator*);
955

956 957 958
  int ndb_mgm_first(ndb_mgm_configuration_iterator*);
  int ndb_mgm_next(ndb_mgm_configuration_iterator*);
  int ndb_mgm_valid(const ndb_mgm_configuration_iterator*);
959
  int ndb_mgm_find(ndb_mgm_configuration_iterator*,
960
		   int param, unsigned value);
961 962

  int ndb_mgm_get_int_parameter(const ndb_mgm_configuration_iterator*,
963 964
				int param, unsigned * value);
  int ndb_mgm_get_int64_parameter(const ndb_mgm_configuration_iterator*,
965
				  int param, Uint64 * value);
966 967
  int ndb_mgm_get_string_parameter(const ndb_mgm_configuration_iterator*,
				   int param, const char  ** value);
968
  int ndb_mgm_purge_stale_sessions(NdbMgmHandle handle, char **);
969
  int ndb_mgm_check_connection(NdbMgmHandle handle);
970 971
#endif

972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001
#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
  enum ndb_mgm_clusterlog_level {
     NDB_MGM_ILLEGAL_CLUSTERLOG_LEVEL = -1,
     NDB_MGM_CLUSTERLOG_ON    = 0,
     NDB_MGM_CLUSTERLOG_DEBUG = 1,
     NDB_MGM_CLUSTERLOG_INFO = 2,
     NDB_MGM_CLUSTERLOG_WARNING = 3,
     NDB_MGM_CLUSTERLOG_ERROR = 4,
     NDB_MGM_CLUSTERLOG_CRITICAL = 5,
     NDB_MGM_CLUSTERLOG_ALERT = 6,
     NDB_MGM_CLUSTERLOG_ALL = 7
  };
  inline
  int ndb_mgm_filter_clusterlog(NdbMgmHandle h,
				enum ndb_mgm_clusterlog_level s,
				int e, struct ndb_mgm_reply* r)
  { return ndb_mgm_set_clusterlog_severity_filter(h,(ndb_mgm_event_severity)s,
						  e,r); }

  inline
  const unsigned int *ndb_mgm_get_logfilter(NdbMgmHandle h)
  { return ndb_mgm_get_clusterlog_severity_filter(h); }

  inline
  int ndb_mgm_set_loglevel_clusterlog(NdbMgmHandle h, int n,
				      enum ndb_mgm_event_category c,
				      int l, struct ndb_mgm_reply* r)
  { return ndb_mgm_set_clusterlog_loglevel(h,n,c,l,r); }
#endif

1002 1003 1004 1005 1006 1007 1008
#ifdef __cplusplus
}
#endif

/** @} */

#endif