Checkpoint Services: Application Program Interface

Checkpoint Service API
ADVANCED HIGH AVAILABILITY SOFTWARE

RELEASE 3.0 (RM05) FOR LINUX
Checkpoint Services
Application Program Interface
May 2002 Edition

VERSION 1.0
Page 1
3.5.3.2 cpsSendFull() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.5.3.3 cpsSendPartial() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.5.4 RECEIVING CHECKPOINT DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.5.4.1 cpsGetDataInAddr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.5.4.2 cpsLockData(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.5.4.3 cpsUnLockData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.5.4.4 cpsInvokeNotification() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.5.5 ON-THE-FLY CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.5.5.1 cpsServerAction() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.5.5.2 cpsBind(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.5.5.3 cpsUnBind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.5.5.4 cpsRemoveBindings(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.5.5.5 cpsBindingsDefault() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.5.5.6 cpsShutDown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4 Writing Applications Using CPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.1 Connect to CPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.2 Register CPS Data Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.3 Perform periodic checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4 Receive checkpoint data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.4.1 Notification Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Page 3
2 CONFIGURING AND STARTING CPS
2.1 INTRODUCTION
This section describes how to get a minimally configured CPS up and running and test it with the
included example file.
2.2 CONFIGURING CPS

The default location for the CPS configuration file is /etc/cps/cps.cfg. This file must be updated
before running CPS. At a minimum the following parameters must be configured in the
configuration file in order to run the accompanying example file. Be sure to run the checkpoint
server and the example file as root user.
1. The LISTEN_PORT parameter must be uncommented and modified if necessary to setup the
TCP port for the checkpoint server. This parameter may be left alone if an entry for CPS is
inserted in the /etc/services file as follows.
ckptserver 1166/tcp # checkpoint services for HA-Linux MCG
2. The CKPT_SCOPE parameter should read as follows so that we may also checkpoint between
local processes.
CKPT_SCOPE = REMOTE, LOCAL
2.1 COMPILING THE EXAMPLE PROGRAMS.

The example programs are found in the /etc/cps/examples directory. If you are not root, copy this
directory to where you have permissions. Compile the program using the provided makefile
Makefile.sample as follows.
make -f Makefile.sample
There will be 3 executables send1, recv1 and hb1.
2.2 RUNNING CPS AND THE EXAMPLE PROGRAM.

Start the CPS by invoking the executable:
/usr/bin/cps
Example programs send1 and recv1 must be run as a pair. send1 is the Sender of CPS data and
recv1 is the receipient of CPS data.
Example program hb1 illustrates how to heartbeat using CPS. Run one instance of this program
as active.
./hb1 a
Run another instance of this program as standby.
./hb1 s
These two instances will be heartbeating with one another.
Page 5
3 HA-LINUX INTER/INTRA PROCESSOR CHECKPOINTING FACILITY
3.1 OVERVIEW
3.1.1 Purpose of Checkpointing

Checkpointing is the periodic (scheduled or asynchronous) saving of state information and status
from one process to another. Typically, this data is required by the receiving process in order to
assume the operations of the sending process in the event that a catastrophic system failure
(hardware or software) prevents it from continuing its function.
3.1.2 The Checkpoint Services API

The CPS API provides a C language based set of functions to the application developer which
controls where and when checkpointing is to occur, and what information is to be checkpointed.
The information to be checkpointed is that which is deemed sufficient for the target process to
perform its intended function when the need arises. Usually, any time critical data is altered, a
checkpoint is requested. This interface supports full or partial (to minimize data exchanges)
checkpoints of data. In most instances, a full checkpoint is performed initially, then partial
checkpoints are used to update periodically changes to that information. If the quantity of
information is relatively small, a full checkpoint can be used for simplicity.
This API allows multiple data objects to be checkpointed and received by the applications. In
order for this to work smoothly, any data item which is to be sent or received must be identified to
the checkpointing services by defining a tag for it and its size. From that point on, checkpointing
simply requires the use of the tag to identify the data object. Alternatively, when receiving
checkpoint data, this tag is passed to the application’s handler as an argument so that it can
differentiate among the data objects it has registered to receive.
3.1.3 Notification of the Application for Incoming Data

Requesting to send checkpoint data is fairly straightforward. The call to do so is performed
whenever the various data changes are significant enough to warrant saving with the target
process. However, the target process must be informed whenever such data is received or updated.
The callback function which the application will use to be notified of this event is specified during
the opening of the checkpoint interface. If no function is specified, then no notifications will
occur. However, the newly received checkpoint data is still available for inspection by the
registered application.
3.1.4 Accessing the CPS API

The software described in this document resides in an static library which is linked with user
applications. A single header file--cpsapi.h-- needs to be #include’d in the application’s
source code for successful compilation. The directory locations of this software are as follows:
• HEADER FILE:cpsapi.h ! /usr/include/cps
• FUNCTION LIBRARY: libcpsapi.a ! /usr/lib
Page 7
RETURN CODE MEANING

cpsNEM No enough memory to perform function.
cpsIOERR An I/O error occurred during checkpoint server communications.
cpsTOERR Checkpoint server communications timed out.
cpsNULARG A required argument has an invalid value of zero(0).
cpsSOCKET Connection lost to checkpoint server.
cpsBMF Invalid message format. Should never happen when using the library
interface.
cpsSHMERR Out of system memory resources. Too much shared memory or too
many shared memory segments have been requested
cpsMNE Returned on failed open if unable to add more clients. Change config-
uration file.
cpsNYI Returned for function which are not yet implemented.
3.3 CPS CONFIGURATION

The CPS is configured through use of a configuration file--cps.cfg. Essentially, this file defines
the operating parameters for the CPS (Checkpoint Server) and the client interfaces. This file is
found by the applications and the CPS using the following technique:
• First, if found, use the file cps.cfg in the current working directory.
• Second, if a local cps.cfg file is not found, use the file path given by the environment
variable CPSCFG if it exists. If the file path is invalid, abort the start-up
• Third, use the file cps.cfg in the /etc/cps directory.
• Otherwise, abort the start up.
Configuration parameters in this file are specified as name and value pairs. Variables are typically
specified beginning in column one of the file and followed by one or more parameters which
provide its value(s). These parameters are separated from the variable name by a space, tab, colon
(:) or equals-sign (=). A variable assignment may span multiple lines by specifying a trailing
backslash (\) on the end of a line. A line beginning with a pound-sign (#) indicates a comment
line. A variable assignment having multiple values will have each of these values separated from
the next value by a comma (,).
A single configuration file is shared by the CPS server and CPS API on a node. This same
configuration file should be replicated to other nodes that are considered to be a part of the CPS
group. The configuration file is divided into two sections. One affects both the CPS API and the
server; the other is for the server only. Variables are specified beneath the section to which they
apply and prior to the next section. The two sections in cps.cfg, as of this writing, are
“SECTION cpsapi” and “SECTION cps local”.
Page 9
• DEBUG extra information which may be useful for support personnel

• ERR all errors which occur regardless of source
The default is that ERR tracing only is enabled.
TRACE_OPTIONS = ERR
Information generated by enabling any of these trace options can be sent to one or more locations
based upon the setting of TRACE_OUTPUT which is described below.
3.3.5 TRACE_OUTPUT
This variable specifies where information from TRACE_OPTIONS is to be sent. The options, all
case insensitive, are standard out (stdout), standard error (stderr) and LOG_FILE. Any or
all of these values may be specified for receiving output. Standard in and standard out may be
redirected when starting a client or server. If no TRACE_OUTPUT is specified, then stderr is
used.
TRACE_OUTPUT stderr, log_file
The above entry will cause TRACE_OPTION output to standard error and a log file. The keyword
LOG_FILE is valid only if the file path to a log file has been provided using the LOG_FILE entry
in the configuration file. The LOG_FILE entry is discussed next.
3.3.6 LOG_FILE
The LOG_FILE value is the path of the file to which TRACE_OPTIONS information will be
written when CPS clients and servers are running. If the keyword LOG_FILE is not provided as a
value to the TRACE_OUTPUT variable, then this path is ignored. There is no default for this
variable.
LOG_FILE /etc/logs/mylogfile
3.3.7 MSGS_DATA
When MSGS is one of the values specified for TRACE_OPTIONS, then the contents of messages
are also dumped as they are tracked. The amount of data dumped (via a hexadecimal print routine)
is controlled by this option. For instance, perhaps only 16 bytes is necessary to provide enough
information when showing a message’s contents to make tracing useful. If messages are
especially large, then this value is of great importance in controlling the amount of time and CPU
used to display message content. If not provided, the default is 0, in which case only the message
headers are displayed or printed.
MSGS_DATA 32
SECTION CPS LOCAL

Items specified under this heading in the configuration file apply to the CPS only.
3.3.8 SHMKEY_BASE
This integer variable represents the base value for keys which will be used to acquire shared
Page 11
CKPT_SCOPE = LOCAL, REMOTE
3.3.14 BIND
One or more BIND’s may be specified to cause one or more outgoing tagged data objects [see
3.5.3.1 on page 17] to be sent to a specific subset of the listed servers. This capability is desirable
in larger server groups when only limited distribution of certain data objects is desired. Once
BIND is used, any outgoing checkpoint data having the tag name specified will be sent only to
those servers specified.
For any particular tagged data object, BIND and UNBIND are mutually exclusive specifications.
The format is:
BIND = <data_object_tag>, <server_name>
BIND = ABCD, alice
BIND = ABCD, sam
BIND = MOTO, pugsly, MOTO, sarah
3.3.15 UNBIND
The opposite of BIND, UNBIND cause one or more outgoing tagged data objects [see 3.5.3.1 on
page 17] to be sent to all servers in a server group except those specified on the UNBIND lines.
This may be simpler than specifying several BIND’s to accomplish the same effect. This
capability is desirable in larger server groups to limit distribution of certain data objects. Once
UNBIND is used, any outgoing checkpoint data having the tag name specified will be sent to all
servers in a server group except those servers specified.
For any particular tagged data object, BIND and UNBIND are mutually exclusive specifications.
The format is:
UNBIND = <data_object_tag>, <server_name>
UNBIND = ABCD, alice, DATA, condo
UNBIND = ABCD, sam
UNBIND = MOTO, pugsly
3.3.16 BINDINGS_DEFAULT
If outgoing data objects have no BIND’s or UNBIND’s specified, then they are by default sent to
all the servers in a CPS’s server group when they are checkpointed. Change that default by using
one of the following two, case insensitive, options:
ALL - bind outgoing data objects to all servers. (default)
NONE - do not bind outgoing data objects to any servers.
The format is:
BINDINGS_DEFAULT = <ALL || NONE>
BINDINGS_DEFAULT = NONE
3.4 SOFTWARE INTERFACES
The CPS API functions fall into five (5) major categories:
Page 13
• cpsSTATUS cpsGetDataOutAddr() [see 3.5.3.1 on page 17]

• cpsSTATUS cpsSendFull() [see 3.5.3.2 on page 18]
• cpsSTATUS cpsSendPartial() [see 3.5.3.3 on page 19]
RECEIVING CHECKPOINT DATA
• cpsSTATUS cpsGetDataInAddr() [see 3.5.4.1 on page 21]
• cpsSTATUS cpsLockData() [see 3.5.4.2 on page 22]
• cpsSTATUS cpsUnLockData() [see 3.5.4.3 on page 24]
• cpsSTATUS cpsInvokeNotification() [see 3.5.4.4 on page 25]
ON-THE-FLY CONFIGURATION
• cpsSTATUS cpsServerAction() [see 3.5.4.4 on page 25]
• cpsSTATUS cpsBind() [see 3.5.4.4 on page 25]
• cpsSTATUS cpsUnBind() [see 3.5.4.4 on page 25]
• cpsSTATUS cpsRemoveBindings() [see 3.5.4.4 on page 25]
• cpsSTATUS cpsBindingsDefault() [see 3.5.5.5 on page 31]
CPS SHUTDOWN
• cpsSTATUS cpsShutDown() [see 3.5.5.6 on page 32]
3.5.1 OPENING THE CPS INTERFACE

The function cpsOpenCkptInterface() must be called prior to attempting any other
checkpoint operations. When an application has completed its session with the CPS, then the
cpsCloseCkptInterface() function must be called.
3.5.1.1 cpsOpenCkptInterface()
NAME
cpsOpenCkptInterface - client application opens the checkpoint interface
SYNOPSIS
#include <cpsapi.h>
cpsSTATUS cpsOpenCkptInterface(void (*notify)(char *tag,
unsigned int offset, unsigned int count))
DESCRIPTION
This function must be called before any other CPS API functions can be used. It opens
and initializes the checkpointing interface by establishing a client link between the
application and the local checkpoint server (CPS).
In addition, if the notify() function address is not NULL (0), it will be invoked with
the tagged name of the data object that has just been received by the server and for
which the application has registered. The two additional arguments provided specify
the offset from the address of the data object at which the update was written and a
count, which is the number of bytes written at that address offset.
This notification address may be left NULL (0) if receipt of checkpointed data is of no
interest to the application (it will be sending data only) or if the application has no need
to be notified each time the checkpointed data arrives.
Page 15
cpsSTATUS cpsCloseCkptInterface(void)
DESCRIPTION
This function closes the program’s connection to the CPS API’s resources. It is
important that this call be made prior to terminating execution in order to disassociate
the application from its shared memory segments.
DIAGNOSTICS
cpsOK is returned if the call is successful.
cpsEOPEN is returned if the application has not previously called
cpsOpenCkptInterface() successfully.
cpsBMF is returned if the checkpointing subsystem detected a bad message
format--this is an internal fault. See your system administrator.
cpsIOERR is returned if the client application suffers a serious I/O error while
communicating with the checkpoint server.
3.5.3 SENDING CHECKPOINT DATA
3.5.3.1 cpsGetDataOutAddr()
NAME
cpsGetDataOutAddr - allocates resources for a data object to be checkpointed.
SYNOPSIS
#include <cpsapi.h>
cpsSTATUScpsGetDataOutAddr(char * tag, int byte_count,
char ** data_addr)
DESCRIPTION
This function acts as the counterpart of the cpsGetDataInAddr() function. This function
takes a string identifier (tag) and length (byte_count) to associate with outgoing
checkpoint data and outputs the memory address (data_addr) of the character buffer
which the application must use to contain this data prior to requesting any
checkpointing. The application can make several calls to this function if it has several
different data objects it wishes to checkpoint. However, each data tag name may be
used only once. The tag is a name supplied by the client to identify the data object to
the CPS for any and all subsequent calls regarding it.
ARGUMENTS
tag - this is a NULL terminated string used to identify the data object. It must be exactly
four characters in length, excluding the NULL terminator.
byte_count - this is the size in bytes of the data object associated with the specified tag.
data_addr - this is the allocated storage address for the data object that is going to be
checkpointed. Its size is byte_count. The application should initialize and use this
Page 17
associates this tag with an allocated buffer for the data object and uses the data in that
buffer for checkpointing.
ARGUMENTS
DIAGNOSTICS

cpsSCP is returned if connecting to the CPS is pending. The client will be
informed when the connection is completed by having its notify routine
invoked with a NULL pointer instead of a four character string. This
only occurs if the CPS is not running when the client process is started
or if the CPS shuts down unexpectedly. Any calls made during this
condition are ignored.
cpsIDT is returned if the tag is NULL (0) or not exactly four characters in
length.
cpsBDS is returned when the size of the data object sent is different from the size
of the same named data object the receiving client expects. This return
code should never arise in a fully debugged application environment.
cpsNST no such tagged data. cpsGetDataOutAddr() not previously or
successfully called for the tag given.
cpsSOCKET is returned if the CPS has aborted operations. In this event, the client
must reopen the CPS interface and respecify the data it wishes to
checkpoint or receive.
communicating with the checkpoint server. In this event, the client must
reopen the CPS interface and respecify the data it wishes to checkpoint
or receive.
3.5.3.3 cpsSendPartial()
NAME
cpsSendPartial - initiates a checkpoint for a subset of data in the specified data
object.
SYNOPSIS
#include <cpsapi.h>
cpsSTATUS cpsSendPartial(char * tag, char *data_addr, int
Page 19
3.5.4 RECEIVING CHECKPOINT DATA
3.5.4.1 cpsGetDataInAddr()
NAME
cpsGetDataInAddr - allocates resources for a data object to receive checkpoint
data.
SYNOPSIS
#include <cpsapi.h>
cpsSTATUS cpsGetDataInAddr(char * tag, int byte_count,
char ** data_addr)
DESCRIPTION
This function acts as the counterpart of the cpsGetDataOutAddr() function. This
function takes a string identifier (tag) and length (byte_count) to associate with
incoming checkpoint data and outputs the memory address (data_addr) of the character
buffer which the application may use to access this data. The application can make
several calls to this function if it has several different data objects it wishes to receive.
However, each data tag name may be used only once. The tag is a name supplied by the
client to identify the data object to the CPS for any and all subsequent calls regarding it.
This function may be called even if there isn’t a sender for the data object, assuming the
sender will be along eventually. The data in the allocated buffer should not be
considered valid until the client has been notified of a checkpoint via the callback
specified in cpsOpenCkptInterface function.
This function must be called to identify each data object the client expects to receive.
If not done, the client application will never be able to receive checkpointed data sent
by another client, whether local or remote.
ARGUMENTS
byte_count - this is the size in bytes of the data object associated with the specified tag.
data_addr - this is the allocated storage address for the data object that is going to be
received. Its size is byte_count. The application should use this buffer to access
received checkpointed data. Data in this buffer should not be considered valid until the
application has been notified via the callback that a full checkpoint has occurred.
DIAGNOSTICS

cpsOKDATA is returned if the call is successful and data for object specified has
already arrived and can be examined immediately. See
cpsInvokeNotification() on page 25 for further detail.
Page 21
the cpsUnLockData() function also is not called by default, and must also be done
explicitly.
The cpsLockData() routine is usable within any section of the client’s code, not
just the notification routine, when a data object’s contents must be protected from
change during its access.
It is important to call cpsUnLockData() as soon as possible after the
cpsLockData() call, so that at a minimum, the CPS can update its contents with
newly arrived updates. The CPS updates this data object immediately upon release by
the client.
ARGUMENTS
direction - this value specifies whether the data object being locked is of type inbound
(DataIn) or outbound (DataOut). It is rare for a client to lock outbound data objects, a
step normally performed by the checkpointing routines to protect the data from being
updated by the client’s threads while it is being copied to the target servers. Direction
accepts the following two values:
• cpsCKPTIN - for data objects which are inbound from other clients and
whose tags were associated using the cpsGetDataInAddr() function.
• cpsCKPTOUT - for data objects which are outbound and whose tags were
associated using the cpsGetDataOutAddr() function.
tries - this value specifies the number of one millisecond waits to be performed before
giving up the lock attempt, should the initial lock request fail. Specifying a value of zero
(0) causes a single, non-delayed attempt to lock this data object before returning with
the request status.
DIAGNOSTICS
cpsOK is returned if the call is successful. This include the case where the client
has previously locked this data object.
cpsDCL is returned if the data object is already locked by another client or by the
CPS. Client must try again.
cpsINVALIDis returned if the tries argument value is less than zero (<0).
cpsIDT is returned if the tag is NULL (0) or not exactly four characters in length.
Page 23

cpsDCU is returned if the data object is already unlocked. non-fatal.
cpsIDT is returned if the tag is NULL (0) or not exactly four characters in length.
cpsINVALIDis returned if the data object specified is not currently locked by the
client making the request to release it.
cpsNST is returned if the tag has never been successfully identified to the system
by the cpsGetDataInAddr() call.
or receive.
3.5.4.4 cpsInvokeNotification()
NAME
cpsInvokeNotification - causes invocation of client’s notification function
SYNOPSIS
#include <cpsapi.h>
cpsSTATUS cpsInvokeNotification(char * tag)
DESCRIPTION
This function is used to explicitly invoke the client’s notification function. It is typically
to be used if either cpsGetDataInAddr() or cpsUnLockData() call provides
a return code of cpsOKDATA. This means that not only was the client’s call successful,
but that new data is present for that object, and can be examined immediately. Invoking
the client’s notification function directly doesn’t enable the proper arguments of offset
and size to be provided, so using this call ensures that those arguments are correct.
ARGUMENTS
Page 25
• If a server’s status is not known, this call can be used to make that determi-
nation.
ARGUMENTS
name - this is the name of the server for which the action is being performed.
actions - these are the actions which are to be performed. They are arithmetically or’d
together, where appropriate, and consist of one or more of the following:
• cpsCREATE - create the named server as if it were in the SERVERS list of
the configuration file.
• cpsACTIVE and cpsSTANDBY - used with cpsCREATE, they specify the
mode in which the server is to be started. Used alone, they specify the new
state to which the server is to be moved.
• cpsREMOVE - remove the named server as if it had never existed.
• cpsGETSTATUS - used alone, the status of the server named is retrieved. It
is superfluous to use this action in conjunction with any other action as it is
always performed after the action completes.
The results for conflicting combinations of actions are undefined.
status - if the status pointer is non-zero, a status for the named server is returned.
Status’s are as follows:
• cpsACTIVE - the server is in the active state.
• cpsQUEUED - the server is scheduled for transition to the active state.
• cpsSTANDBY - the server is in a standby state.
• cpsREMOVE - the server has been removed as a direct result of this call.
• cpsUNKNOWN - the server named does not exist and a cpsCREATE action
was not specified.
• cpsNOROOM - there is no room for adding any additional servers. The
maximum number of servers in a server group is 32.
DIAGNOSTICS
cpsINVALIDis returned if the name provided is NULL or missing.
cpsISN is returned if the server name provided is NULL or missing.
cpsMHCE action not taken because the maximum number of hosts (32) would be
exceeded if the host named were created.
cpsNSS is returned if the server named does not exists and a cpsCREATE was
not one of the actions.
Page 27
or receive.
3.5.5.3 cpsUnBind()
NAME
cpsUnBind - unbinds an outbound data object from a server for checkpointing
SYNOPSIS
#include <cpsapi.h>
cpsSTATUS cpsUnBind(char * tag, char * server)
DESCRIPTION
This function provides the ability to unbind an outbound data object from a server in a
manner fully analogous to the UNBIND option in the configuration file. Upon
successful completion of this call, all current bindings are updated within the CPS.
Note that, as with usage in the configuration file, an unbind cannot be used with a tag
which already has one or more binds.
ARGUMENTS
server - this is the name of the server from which the outbound data object, identified
by tag, is to be unbound. This server does not have to be known or identified at the time
of this call. If and when the server is created by a call to cpsServerAction(), the unbinds
will be updated to reflect this change.
DIAGNOSTICS
cpsOK is returned if the call is successful. This include the case where the client
has previously locked this data object.
cpsIDT is returned if the tag is NULL or not exactly four characters in length.
cpsISN is returned if the server name provided is NULL or missing.
Page 29
or receive.
3.5.5.5 cpsBindingsDefault()
NAME
cpsBindingsDefault - changes the default bindings for all data objects
SYNOPSIS
#include <cpsapi.h>
cpsSTATUS cpsBindingsDefault(int bindings_default)
DESCRIPTION
This function causes all outgoing CPS data objects to be bound either to all servers or
to none of them, by default. This default does not apply to data objects which are, or
will be, BOUND or UNBOUND either in the configuration file or by subsequent
cpsBind() or cpsUnBind() calls.
ARGUMENTS
bindings_default - this value specifies the new binding default to be used for all tags.
It has 2 possible values:
cpsALL - outgoing data objects with no bindings specified will default to all CPS
hosts. That means that they will be sent to all servers in the SERVERS grouping
when checkpointed.
cpsNONE - data objects with no bindings specified will default to none, hence not
be sent to any servers within the server group when checkpointed.
DIAGNOSTICS

cpsINVALIDis returned if the bindings_default value is incorrect.
Page 31
4 WRITING APPLICATIONS USING CPS

There are C example files included with the CPS software that the user may reference, compile
and build when writing applications that use CPS. The following sections describe the basics of
using CPS.
4.1 CONNECT TO CPS

Every application must establish a connection with the CPS server before any other CPS
functionality may be utilized. This is performed using the cpsOpenCkptInterface() API. This
function also allows the application to register a callback function which is invoked whenever
there is new checkpoint data available. If the application doesn’t need to be notified when new
checkpoint data is available, then the parameter to cpsOpenCkptInterface() should be left null.
4.2 REGISTER CPS DATA OBJECTS

Before any data can be passed around using the CPS framework, the application must register data
object(s) with the CPS. A data object is a character buffer of a defined size and is identified with a
globally unique 4 character tag string. The application must define one or more data objects for
sending and receiving checkpoint data.
If the application wants to send checkpoint data, it would typically define a single data object that
is large enough to hold all the data that needs to be checkpointed and identify it with a globally
unique tag. The application may define multiple data objects for sending checkpoint data if there
is a need. The application registers a data object for sending checkpoint data using the
cpsGetDataOutAddr(). This function informs the CPS of the new data object and allocates
resources for the data object. The application must specify the tag and the size of the buffer in the
cpsGetDataOutAddr() function call and it returns a pointer to the buffer that the application must
populate when sending checkpoint data. If there are multiple data objects to be used for sending
checkpoint data then this process must be done for each object.
If the application wants to receive checkpoint data, it would register one or more data objects for
receiving checkpoint data using the cpsGetDataInAddr() function call. Applications can only
receive data that is sent by other applications or itself. Thus the receive data object tag and size
should correspond to a data object that is used for sending checkpoint data. If a receive data object
is defined that doesn’t correspond to a data object defined for sending data, it is still valid. It just
means that no data will arrive for this object until some application defines a corresponding object
to send data.
Multiple applications may register for the same data objects for receiving data however only one
application may register a data object with a given tag and length for sending data. This ability
and restriction allows multiple processes to act as a standby for a given process and prevents
processes from corrupting each others outbound checkpoint data.
4.3 PERFORM PERIODIC CHECKPOINTS

The application may perform periodic checkpoints using the cpsSendFull() and cpsSendPartial()
API’s. As to when an application calls these functions depends entirely on the application.
However, as a general rule a checkpoint should occur when the active application state has
Page 33

Checkpoint Services: Application Program Interface

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Checkpoint Services: Application Program Interface

Загружено:

Авторское право:

Доступные форматы

Checkpoint Service API

ADVANCED HIGH AVAILABILITY SOFTWARE

May 2002 Edition

2 CONFIGURING AND STARTING CPS

2.2 CONFIGURING CPS

2.1 COMPILING THE EXAMPLE PROGRAMS.

2.2 RUNNING CPS AND THE EXAMPLE PROGRAM.

3 HA-LINUX INTER/INTRA PROCESSOR CHECKPOINTING FACILITY

3.1.1 Purpose of Checkpointing

3.1.2 The Checkpoint Services API

3.1.3 Notification of the Application for Incoming Data

3.1.4 Accessing the CPS API

RETURN CODE MEANING

3.3 CPS CONFIGURATION

• DEBUG extra information which may be useful for support personnel

SECTION CPS LOCAL

CKPT_SCOPE = LOCAL, REMOTE

• cpsSTATUS cpsGetDataOutAddr() [see 3.5.3.1 on page 17]

3.5.1 OPENING THE CPS INTERFACE

3.5.3 SENDING CHECKPOINT DATA

cpsOK is returned if the call is successful.

3.5.4 RECEIVING CHECKPOINT DATA

cpsOK is returned if the call is successful.

cpsSCP is returned if connecting to the CPS is pending. The client will be

cpsOK is returned if the call is successful.

4 WRITING APPLICATIONS USING CPS

4.1 CONNECT TO CPS

4.2 REGISTER CPS DATA OBJECTS

4.3 PERFORM PERIODIC CHECKPOINTS

Вам также может понравиться