Sai Ais CKPT B.02.02

Service AvailabilityTM Forum
Application Interface Specification
Checkpoint Service SAI-AIS-CKPT-B.02.02
The Service AvailabilityTM solution is high availability and more; it is the delivery of ultra-dependable
communication services on demand and without interruption.
This Service AvailabilityTM Forum Application Interface Specification document might contain
design defects or errors known as errata, which might cause the product to deviate from
published specifications. Current characterized errata are available on request.
.
Service AvailabilityTM Application Interface Specification
Legal Notice
SERVICE AVAILABILITY™ FORUM SPECIFICATION LICENSE AGREEMENT 1

The Service Availability™ Specification(s) (the "Specification") found at the URL http://www.saforum.org (the "Site")
is generally made available by the Service Availability Forum (the "Licensor") for use in developing products that
are compatible with the standards provided in the Specification. The terms and conditions, which govern the use of
the Specification are set forth in this agreement (this "Agreement"). 5
IMPORTANT – PLEASE READ THE TERMS AND CONDITIONS PROVIDED IN THIS AGREEMENT BEFORE DOWN-
LOADING OR COPYING THE SPECIFICATION. IF YOU AGREE TO THE TERMS AND CONDITIONS OF THIS AGREE-
MENT, CLICK ON THE "ACCEPT" BUTTON. BY DOING SO, YOU AGREE TO BE BOUND BY THE TERMS AND
CONDITIONS STATED IN THIS AGREEMENT. IF YOU DO NOT WISH TO AGREE TO THESE TERMS AND CONDITIONS,
YOU SHOULD PRESS THE "CANCEL"BUTTON AND THE DOWNLOAD PROCESS WILL NOT PROCEED. 10
1. LICENSE GRANT. Subject to the terms and conditions of this Agreement, Licensor hereby grants you a non-
exclusive, worldwide, non-transferable, revocable, but only for breach of a material term of the license granted in
this section 1, fully paid-up, and royalty free license to:
a. reproduce copies of the Specification to the extent necessary to study and understand the Spec-
ification and to use the Specification to create products that are intended to be compatible with the 15
Specification;
b. distribute copies of the Specification to your fellow employees who are working on a project or
product development for which this Specification is useful; and
c. distribute portions of the Specification as part of your own documentation for a product you have
built, which is intended to comply with the Specification. 20
2. DISTRIBUTION. If you are distributing any portion of the Specification in accordance with Section 1(c), your doc-
umentation must clearly and conspicuously include the following statements:
a. Title to and ownership of the Specification (and any portion thereof) remain with Service Avail-
ability Forum ("SA Forum").
25
b. The Specification is provided "As Is." SA Forum makes no warranties, including any implied
warranties, regarding the Specification (and any portion thereof) by Licensor.
c. SA Forum shall not be liable for any direct, consequential, special, or indirect damages (includ-
ing, without limitation, lost profits) arising from or relating to the Specification (or any portion
thereof).
d. The terms and conditions for use of the Specification are provided on the SA Forum website. 30
3. RESTRICTION. Except as expressly permitted under Section 1, you may not (a) modify, adapt, alter, translate,
or create derivative works of the Specification, (b) combine the Specification (or any portion thereof) with another
document, (c) sublicense, lease, rent, loan, distribute, or otherwise transfer the Specification to any third party, or
(d) copy the Specification for any purpose.
35
4. NO OTHER LICENSE. Except as expressly set forth in this Agreement, no license or right is granted to you, by
implication, estoppel, or otherwise, under any patents, copyrights, trade secrets, or other intellectual property by
virtue of your entering into this Agreement, downloading the Specification, using the Specification, or building prod-
ucts complying with the Specification.
5. OWNERSHIP OF SPECIFICATION AND COPYRIGHTS. The Specification and all worldwide copyrights therein 40
are the exclusive property of Licensor. You may not remove, obscure, or alter any copyright or other proprietary
rights notices that are in or on the copy of the Specification you download. You must reproduce all such notices on
all copies of the Specification you make. Licensor may make changes to the Specification, or to items referenced
AIS Specification SAI-AIS-CKPT-B.02.02 3

Legal Notice
therein, at any time without notice. Licensor is not obligated to support or update the Specification. 1
6. WARRANTY DISCLAIMER. THE SPECIFICATION IS PROVIDED "AS IS." LICENSOR DISCLAIMS ALL
WARRANTIES, WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING ANY WARRANTY OF MER-
CHANTABILITY, NONINFRINGEMENT OF THIRD-PARTY RIGHTS, FITNESS FOR ANY PARTICULAR PUR-
POSE, OR TITLE. Without limiting the generality of the foregoing, nothing in this Agreement will be construed as 5
giving rise to a warranty or representation by Licensor that implementation of the Specification will not infringe the
intellectual property rights of others.
7. PATENTS. Members of the Service Availability Forum and other third parties [may] have patents relating to the
Specification or a particular implementation of the Specification. You may need to obtain a license to some or all of
these patents in order to implement the Specification. You are responsible for determining whether any such 10
license is necessary for your implementation of the Specification and for obtaining such license, if necessary.
[Licensor does not have the authority to grant any such license.] No such license is granted under this Agreement.
8. LIMITATION OF LIABILITY. To the maximum extent allowed under applicable law, LICENSOR DISCLAIMS
ALL LIABILITY AND DAMAGES, INCLUDING DIRECT, INDIRECT, CONSEQUENTIAL, SPECIAL, AND INCI-
DENTAL DAMAGES, ARISING FROM OR RELATING TO THIS AGREEMENT, THE USE OF THE SPECIFICA- 15
TION OR ANY PRODUCT MANUFACTURED IN ACCORDANCE WITH THE SPECIFICATION, WHETHER
BASED ON CONTRACT, ESTOPPEL, TORT, NEGLIGENCE, STRICT LIABILITY, OR OTHER THEORY. NOT-
WITHSTANDING ANYTHING TO THE CONTRARY, LICENSOR’S TOTAL LIABILITY TO YOU ARISING FROM
OR RELATING TO THIS AGREEMENT OR THE USE OF THE SPECIFICATION OR ANY PRODUCT MANU-
FACTURED IN ACCORDANCE WITH THE SPECIFICATION WILL NOT EXCEED ONE HUNDRED DOLLARS
($100). YOU UNDERSTAND AND AGREE THAT LICENSOR IS PROVIDING THE SPECIFICATION TO YOU AT 20
NO CHARGE AND, ACCORDINGLY, THIS LIMITATION OF LICENSOR’S LIABILITY IS FAIR, REASONABLE,
AND AN ESSENTIAL TERM OF THIS AGREEMENT.
9. TERMINATION OF THIS AGREEMENT. Licensor may terminate this Agreement, effective immediately upon
written notice to you, if you commit a material breach of this Agreement and do not cure the breach within ten (30)
days after receiving written notice thereof from Licensor. Upon termination, you will immediately cease all use of 25
the Specification and, at Licensor’s option, destroy or return to Licensor all copies of the Specification and certify in
writing that all copies of the Specification have been returned or destroyed. Parts of the Specification that are
included in your product documentation pursuant to Section 1 prior to the termination date will be exempt from this
return or destruction requirement.
10. ASSIGNMENT. You may not assign, delegate, or otherwise transfer any right or obligation under this Agree- 30
ment to any third party without the prior written consent of Licensor. Any purported assignment, delegation, or
transfer without such consent will be null and void.
11. GENERAL. This Agreement will be construed in accordance with, and governed in all respects by, the laws of
the State of Delaware (without giving effect to principles of conflicts of law that would require the application of the
laws of any other state). You acknowledge that the Specification comprises proprietary information of Licensor and 35
that any actual or threatened breach of Section 1 or 3 will constitute immediate, irreparable harm to Licensor for
which monetary damages would be an inadequate remedy, and that injunctive relief is an appropriate remedy for
such breach. All waivers must be in writing and signed by an authorized representative of the party to be charged.
Any waiver or failure to enforce any provision of this Agreement on one occasion will not be deemed a waiver of
any other provision or of such provision on any other occasion. This Agreement may be amended only by binding
written instrument signed by both parties. This Agreement sets forth the entire understanding of the parties relating
40
to the subject matter hereof and thereof and supersede all prior and contemporaneous agreements, communica-
tions, and understandings between the parties relating to such subject matter.
4 SAI-AIS-CKPT-B.02.02 AIS Specification

Table of Contents
Table of Contents Checkpoint Service 1
1 Document Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.1 Document Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5
1.2 AIS Documents Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.1 New Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.2 Clarifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.3 Changes in Return Values of API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
10
1.3.4 Removed Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.5 Other Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5 How to Provide Feedback on the Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.6 How to Join the Service Availability™ Forum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
15
1.7 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.7.1 Member Companies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.7.2 Press Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
20
2.1 Checkpoint Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3 SA Checkpoint Service API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.1 Checkpoint Service Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.1 Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 25
3.1.2 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.3 Checkpoint Replica . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1.4 Checkpoint Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1.5 Synchronous Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.1.6 Asynchronous Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.1.7 Management of Replicas for Collocated and Non-Collocated Checkpoints . . . . . . . . . . . . . . 18 30
3.1.7.1 Collocated Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.1.7.2 Non-Collocated Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.1.8 Persistence of Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2 Unavailability of the Checkpoint Service API on a Non-Member Node . . . . . . . . . . . . . . 20
3.2.1 A Member Node Leaves or Rejoins the Cluster Membership . . . . . . . . . . . . . . . . . . . . . . . . 20 35
3.2.2 Guidelines for Checkpoint Service Implementers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3 Include File and Library Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.4 Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.4.1 Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.4.1.1 SaCkptHandleT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 40
3.4.1.2 SaCkptCheckpointHandleT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.4.1.3 SaCkptSectionIterationHandleT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.4.2 Checkpoint Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Table of Contents
3.4.2.1 SaCkptCheckpointCreationFlagsT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 1
3.4.2.2 SaCkptCheckpointCreationAttributesT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.4.2.3 SaCkptCheckpointOpenFlagsT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.4.3 Section Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.4.3.1 SaCkptSectionIdT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.4.3.2 SaCkptSectionCreationAttributesT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5
3.4.3.3 SaCkptSectionStateT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.4.3.4 SaCkptSectionDescriptorT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.4.3.5 SaCkptSectionsChosenT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.4.4 IoVector Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.4.4.1 SaCkptIOVectorElementT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 10
3.4.5 SaCkptCheckpointDescriptorT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.4.6 SaCkptCallbacksT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.4.7 SaCkptCheckpointStatusT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.4.8 SaCkptStateT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.5 Library Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.5.1 saCkptInitialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
15
3.5.2 saCkptSelectionObjectGet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.5.3 saCkptDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.5.4 saCkptFinalize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.6 Checkpoint Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.6.1 saCkptCheckpointOpen() and saCkptCheckpointOpenAsync() . . . . . . . . . . . . . . . . . . . . . . . 38 20
3.6.2 SaCkptCheckpointOpenCallbackT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3.6.3 saCkptCheckpointClose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.6.4 saCkptCheckpointUnlink() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.6.5 saCkptCheckpointRetentionDurationSet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.6.6 saCkptActiveReplicaSet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 25
3.6.7 saCkptCheckpointStatusGet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.7 Section Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.7.1 saCkptSectionCreate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.7.2 saCkptSectionDelete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
3.7.3 saCkptSectionIdFree() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.7.4 saCkptSectionExpirationTimeSet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
30
3.7.5 saCkptSectionIterationInitialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
3.7.6 saCkptSectionIterationNext() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.7.7 saCkptSectionIterationFinalize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.8 Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.8.1 saCkptCheckpointWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 35
3.8.2 saCkptSectionOverwrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
3.8.3 saCkptCheckpointRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
3.8.4 saCkptIOVectorElementDataFree() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.8.5 saCkptCheckpointSynchronize(), saCkptCheckpointSynchronizeAsync() . . . . . . . . . . . . . . 76
3.8.6 SaCkptCheckpointSynchronizeCallbackT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 40
4 Checkpoint Service UML Information Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
4.1 DN Format for Checkpoint Service UML Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Table of Contents
4.2 Checkpoint Service UML Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 1
5 Checkpoint Service Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6 Checkpoint Service Alarms and Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 5

6.1 Setting Common Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.2 Checkpoint Service Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.2.1 Checkpoint Service Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.2.2 Checkpoint State Change Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.2.2.1 Checkpoint Section Resources Exhausted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 10
6.2.2.2 Checkpoint Section Resources Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7 Checkpoint Service Management Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

7.1 Checkpoint Service MIB (SAF-CKPT-SVC-MIB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
15
Index of Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
20
25
30
35
40

Table of Contents
10
15
20
25
30
35
40

Document Introduction
1 Document Introduction 1
1.1 Document Purpose

This document defines the Checkpoint Service of the Application Interface Specifica- 5
tion (AIS) of the Service AvailabilityTM Forum (SA Forum). It is intended for use by
implementers of the Application Interface Specification and by application developers
who would use the Application Interface Specification to develop applications that
must be highly available. The AIS is defined in the C programming language, and
requires substantial knowledge of the C programming language. 10
Typically, the Service AvailabilityTM Forum Application Interface Specification will be

used in conjunction with the Service AvailabilityTM Forum Hardware Interface
Specification (HPI).
15
1.2 AIS Documents Organization
The Application Interface Specification is organized into several volumes. For a list of
all Application Interface Specification documents, refer to the SA Forum Overview
document ([1]). 20
1.3 History
Previous releases of the Checkpoint Service specification:
25
(1) SAI-AIS-CKPT-A.01.01
(2) SAI-AIS-CKPT-B.01.01
(3) SAI-AIS-CKPT-B.02.01
This section presents the changes of the current release, SAI-AIS-CKPT-B.02.02, 30

with respect to the SAI-AIS-CKPT-B.02.01 release. Editorial changes that do not
change semantics or syntax of the described interfaces are not mentioned.
1.3.1 New Topics

• Chapter 4 contains the Checkpoint Service UML Information Model. This descrip- 35
tion was previously contained in the B.03.01 version of [1].
• Chapter 5 states that no administration APIs are provided for the Checkpoint Ser-
vice in this release.
• Chapter 7 presents the Checkpoint Service management interface. 40
AIS Specification SAI-AIS-CKPT-B.02.02 Section 1 9

1.3.2 Clarifications 1
• The “section identifier descriptor” term has been introduced in Section 3.4.3.1 to
distinguish its usage from the usage of the term “section identifier”. This issue
has no impact on the APIs.
5
• The description of the saCkptDispatch() function (see Section 3.5.3) clarifies
the meaning of the SA_AIS_OK return value.
• The description of the saCkptFinalize() function (see Section 3.5.4)
explains the behavior of the Checkpoint Service if a process that still has an
association with the Checkpoint Service terminates. 10
• The description of the saCkptCheckpointClose() function
(see Section 3.6.3) clarifies that it frees all resources allocated by the Check-
point Service for the invoking process for the specified checkpoint.
1.3.3 Changes in Return Values of API Functions 15
Table 1 Changes in Return Values of API Functions
Change 20
API Function Return Value
Type
All API functions except saCkptFinalize() SA_AIS_ERR_UNAVAILABLE new

and all callback functions1
25
saCkptCheckpointOpen() SA_AIS_ERR_NOT_EXIST clarified
saCkptCheckpointOpenAsync() SA_AIS_ERR_EXIST
SaCkptCheckpointOpenCallbackT
saCkptDispatch() SA_AIS_OK clarified
30
1. The SaCkptCheckpointOpenCallbackT and SaCkptCheckpointSynchronizeCallbackT call-
back functions have the SA_AIS_ERR_UNAVAILABLE return value in the error parameter.
1.3.4 Removed Topics

SA Forum revisited its alarm issuance directives and modified the conditions that 35
determine when an alarm would be produced. As a consequence, AIS Services shall
only generate alarms for situations that require an explicit intervention by an external
agent or operator, provided that the corrective measures to be taken are well defined.
Based on these directives, the alarms generated so far by the AIS Services have
been revised, and it was decided to remove the "service impaired” alarm from the 40
Checkpoint Service B.02.02 version.
10 SAI-AIS-CKTP-B.02.02 Section 1.3.2 AIS Specification

SA Forum does not mandate that Checkpoint Service implementations which also 1
support the B.02.01 version must generate the "service impaired” alarm for the
B.02.01 version.
The "service impaired” alarm has also been removed from the Checkpoint Service 5
MIB.
1.3.5 Other Changes

• In the description of the saCkptInitialize() function (see Section 3.5.1),
the sentence 10
“If the implementation supports the required releaseCode, and a major version
>= the required majorVersion, SA_AIS_OK is returned.”
has been replaced by the sentence
“If the implementation supports the specified releaseCode and
majorVersion, SA_AIS_OK is returned.”. 15
• The parameter named id in the prototype of the saCkptSectionIdFree()
function (see Section 3.7.3) was mistakenly written as Id in the Checkpoint Ser-
vice B.02.01 specification. This issue does not affect compatibility.
• In the description of the saCkptSectionIterationNext() function (see 20
Section 3.7.6 of the B.02.02 release) of the B.02.01 Checkpoint Service specifi-
cation, the reference
”sectionDescriptor->sectionId.id” was mistakenly written
”sectionDescriptor->sectionId.->id”.
25
1.4 References
The following documents contain information that is relevant to the specification:
[1] Service AvailabilityTM Forum, Service Availability Interface, Overview,
SAI-Overview-B.04.01 30
[2] Service AvailabilityTM Forum, Application Interface Specification, Notification
Service, SAI-AIS-NTF-A.02.01
[3] Service AvailabilityTM Forum, Application Interface Specification, Information
Model Management Service, SAI-AIS-IMM-A.02.01 35
[4] Service AvailabilityTM Forum, Application Interface Specification, Cluster Mem-
bership Service, SAI-AIS-CLM-B.03.01
[5] Service AvailabilityTM Forum, SA Forum Information Model in XML Metadata
Interchange (XMI) v2.1 format, SAI-XMI-A.03.01
40
[6] CCITT Recommendation X.733 | ISO/IEC 10164-4, Alarm Reporting Function
AIS Specification SAI-AIS-CKPT-B.02.02 Section 1.3.5 11

References to these documents are made by putting the number of the document in 1
brackets.
1.5 How to Provide Feedback on the Specification

5
If you have a question or comment about this specification, you may submit feedback
online by following the links provided for this purpose on the Service Availability™
Forum website (http://www.saforum.org).
You can also sign up to receive information updates on the Forum or the Specifica- 10
tion.
1.6 How to Join the Service Availability™ Forum

The Promoter Members of the Forum require that all organizations wishing to partici- 15
pate in the Forum complete a membership application. Once completed, a represen-
tative of the Service Availability™ Forum will contact you to discuss your membership
in the Forum. The Service Availability™ Forum Membership Application can be com-
pleted online by following the pertinent links provided on the Forum’s website
(http://www.saforum.org). 20
You can also submit information requests online. Information requests are generally
responded to within three business days.
1.7 Additional Information 25
1.7.1 Member Companies

A list of the Service Availability™ Forum member companies can be viewed online by
using the links provided on the Forum’s website (http://www.saforum.org). 30
1.7.2 Press Materials
The Service Availability™ Forum has available a variety of downloadable resource
materials, including the Forum Press Kit, graphics, and press contact information.
Visit this area often for the latest press releases from the Service Availability™ Forum 35
and its member companies by following the pertinent links provided on the Forum’s
website (http://www.saforum.org).
40
12 SAI-AIS-CKTP-B.02.02 Section 1.5 AIS Specification

Overview
2 Overview 1
This specification defines the Checkpoint Service within the Application Interface
Specification (AIS).
5
2.1 Checkpoint Service
The Checkpoint Service provides a facility for processes to record checkpoint data
incrementally, which can be used to protect an application against failures. When
recovering from fail-over or switch-over situations, the checkpoint data can be 10
retrieved, and execution can be resumed from the state recorded before the failure.
Checkpoints are cluster-wide entities that are designated by unique names. A copy of
the data stored in a checkpoint is called a checkpoint replica; for performance rea-
sons, a checkpoint replica is typically stored in main memory rather than on disk. A 15
checkpoint may have several checkpoint replicas stored on different nodes1 in the
cluster to protect it against node failures.
To avoid accumulation of unused checkpoints in the system, checkpoint replicas

have a retention time. When a checkpoint has not been opened by any process for 20
the duration of the retention time, the Checkpoint Service automatically deletes the
checkpoint.
25
30
35
40
1. The term “node” without a qualifier is used in this document in the sense of a “member node”, as defined in
the Cluster Membership Service specification (see [4]).

Overview
10
15
20
25
30
35
40
14 SAI-AIS-CKPT-B.02.02 Section 2.1 AIS Specification

Checkpoint Service API Specification
3 SA Checkpoint Service API 1
3.1 Checkpoint Service Model

5
3.1.1 Checkpoints
The Checkpoint Service manages a set of entities called checkpoints, which pro-
cesses use to save their state. A process can use one or several checkpoints to save
its state. Checkpoints are cluster-wide entities designated by unique names.
10
A process can dynamically create checkpoints and open existing checkpoints by
invoking the saCkptCheckpointOpen() or the
saCkptCheckpointOpenAsync() functions.
A process can close a checkpoint by invoking the saCkptCheckpointClose()
function and can delete checkpoints by invoking the saCkptCheckpointUnlink() 15
function. The interaction of the open, close, and unlink functions for checkpoints is
similar to the way POSIX treats files and is described in detail in
Section 3.6 on page 38.
To avoid the accumulation of unused checkpoints in the system, checkpoints have a 20

retention duration. When a checkpoint has not been opened by any process for the
retention duration, the Checkpoint Service automatically deletes the checkpoint.
If a process terminates abnormally, the Checkpoint Service automatically closes all of

its open checkpoints. 25
3.1.2 Sections
Each checkpoint is structured to hold up to a maximum number of sections.
Sections contain raw data, which is not encoded by the Checkpoint Service. It is the 30
responsibility of the process to encode the section contents if heterogeneity is a con-
cern.
Within a checkpoint, each section is identified by a unique section identifier. Section

identifiers are unique only within a checkpoint; sections in different checkpoints may 35
have the same identifier. Section identifiers can be specified by the creating process
or can be allocated dynamically by the Checkpoint Service.
The maximum number of sections in a checkpoint is specified when the checkpoint is

created. For details, refer to the saCkptCheckpointOpen() and 40
saCkptCheckpointOpenAsync() API functions. Sections belonging to a check-
point can be dynamically created or deleted as long as the total number of sections
does not exceed this maximum number. Within a checkpoint, sections of different

sizes may coexist. The size of a section can be changed dynamically as the result of 1
the invocation of the saCkptCheckpointWrite() or
saCkptSectionOverwrite() functions.
Sections have an expiration time, which is an absolute time. The Checkpoint Ser- 5
vice automatically deletes a section when its expiration time is reached, regardless of
whether the checkpoint is open by a process or not.
Note that the expiration time of a section is a time, in contrast to the retention duration
of a checkpoint, which is a duration. Both expiration time and retention duration are
defined as SaTimeT. 10
3.1.3 Checkpoint Replica

A copy of the data that is stored in a checkpoint is called a checkpoint replica or
simply a replica. For a particular checkpoint, at most one checkpoint replica may
15
reside on a particular node. A checkpoint may have several checkpoint replicas (or
copies), each residing on another node.
A local replica is a replica located on the node where the checkpoint is opened.
20
The management of checkpoint replicas is for the most part transparent to the appli-
cation programmer.
3.1.4 Checkpoint Data Access

A process can use the handle that the Checkpoint Service returned at open time to 25
perform read and write operations on the checkpoint. A single read or write operation
can access various portions of different sections within a checkpoint simultaneously.
Requirements regarding the consistency of the various replicas associated to a par-

ticular checkpoint can have negative effects on the performance of checkpoint write 30
operations. To give flexibility to implementers of the Checkpoint Service, strong atom-
icity and strong ordering semantics are not required. In particular, if two processes
perform a concurrent write to the same portion of a checkpoint, no global ordering of
replica updates is ensured. After both write operations complete successfully, some
replicas may contain data written by one process while other replicas contain data 35
written by the other process. It is the responsibility of the processes to use proper
synchronization mechanisms (such as the Lock Service) if such global update order-
ing is required.
However, ordering of updates issued by a single writer is required, even in the pres-
ence of faults. For example, assume that a thread within a process writes first D1 in a 40
section of a particular checkpoint and then writes D2 in another section of the same
checkpoint. Later on, if the same process or another process running on another
node reads both sections entirely, and it sees D2, it must also see D1.
16 SAI-AIS-CKPT-B.02.02 Section 3.1.3 AIS Specification

To accommodate different trade-offs between checkpoint update performance and 1

replica consistency, different options are provided when a checkpoint is created.
These options are described below.
3.1.5 Synchronous Update 5

When a checkpoint has been created with the synchronous update option, write
and overwrite calls as well as calls for the creation and deletion of a section return
only when all checkpoint replicas have been updated. In addition, the Checkpoint
Service guarantees that a replica is not partially updated: a replica is either updated
10
with all data specified in the write call or is not updated at all.
In other words, the Checkpoint Service guarantees that all replicas of a checkpoint
created with the synchronous update option are identical if there are no concurrent
overlapping updates to this checkpoint.
15
The Checkpoint Service does not specify from which replica checkpoint data is read.
A checkpoint with the synchronous update option can be created by specifying the
SA_CKPT_WR_ALL_REPLICAS flag at creation time. For details, refer to
Section 3.4.2.1 on page 23.
20
3.1.6 Asynchronous Update
For this update mode, the notion of an active replica is defined. It is a distinguished
checkpoint replica whose properties are described below. At any time, at most one
active replica exists. 25
When a checkpoint has been created with the asynchronous update option, write
and overwrite calls as well as calls for the creation and deletion of a section return
immediately when the active checkpoint replica has been updated. Other replicas are
updated asynchronously. To guarantee that a process does not read stale data, the 30
Checkpoint Service always reads from the active checkpoint replica.
If no active replica exists for a checkpoint created with the asynchronous update
option, each of the section management operations of Section 3.7, except the
saCkptSectionIdFree() function (see Section 3.7.3 on page 57), and each of the 35
data access operations of Section 3.8, except the
saCkptIOVectorElementDataFree() function (see Section 3.8.4 on page 74)
will return an error.
The Checkpoint Service does not guarantee that all replicas of a checkpoint created 40
with the asynchronous update option are always identical. However, a process can
request that the Checkpoint Service synchronizes all checkpoint replicas by invok-
ing the saCkptCheckpointSynchronize() or the

saCkptCheckpointSynchronizeAsync() functions to propagate checkpoint 1

data to all of the checkpoint replicas.
This specification defines two variants of checkpoints with the asynchronous update
option. 5
For the first one, the Checkpoint Service guarantees atomicity when replicas are
updated, that is, a replica is either updated with all section data specified in the write
call or is not updated at all. Such a checkpoint can be created by specifying the
SA_CKPT_WR_ACTIVE_REPLICA flag at creation time. For details, refer t
Section 3.4.2.1 on page 23. 10
The second variant does not provide the atomicity guarantee of the first one, but the
Checkpoint Service marks sections that are modified by the write or overwrite calls as
corrupt when a fault occurs while a checkpoint replica is being updated. Corrupted
sections cannot be accessed by invoking saCkptCheckpointRead() or
saCkptCheckpointWrite(); they can only be overwritten by invoking 15
saCkptSectionOverwrite() or deleted by invoking saCkptSectionDelete().
Checkpoints with this partial update option are created by specifying the
SA_CKPT_WR_ACTIVE_REPLICA_WEAK flag at creation time. For details, refer to
20
The partial update option is intended to be used by applications that may not want to
pay the performance price associated with protection against partial updates.
Note: In the remainder of this document, if the term asynchronous update option is
used without further specification, it refers to checkpoints created with any of 25
the two variants of the asynchronous update option.
3.1.7 Management of Replicas for Collocated and Non-Collocated Checkpoints
3.1.7.1 Collocated Checkpoints

30
When using a checkpoint with the asynchronous update option, optimal performance
for updating the checkpoint is achieved when the active replica is located on the
same node as the process accessing the checkpoint. However, because the process
accessing the checkpoint can change depending on the role assigned by the Avail-
ability Management Framework to it, optimal performance can be achieved only if the 35
application informs the Checkpoint Service about which replica should be active at a
particular time. An application informs the Checkpoint Service about the active replica
for checkpoints having the collocated attribute. Such a checkpoint is named a collo-
cated checkpoint. When a collocated checkpoint is created, no active replica exists
until a local replica is set as the active replica by the saCkptActiveReplicaSet() 40
call. An active replica stays active until the user explicitly sets another replica to
active by calling the saCkptActiveReplicaSet() function, or if the replica is
destroyed (for example if the node where this active replica resides crashes). In the

latter case, no active replica exists until the user sets a new one. 1
When saCkptActiveReplicaSet() returns, the Checkpoint Service guarantees
that the new active replica is completely synchronized with the previous active rep-
lica. Data consistency for replica reads and writes and write ordering are preserved
as though the change of active replica never took place. Replica reads or writes might 5
be blocked until the synchronization completes.
The saCkptActiveReplicaSet() function can be used only for collocated check-

points created with the asynchronous update option.
10
The management of replicas of collocated checkpoints and whether to set the repli-
cas to active or not is mainly the duty of applications. Only applications can create a
replica of a collocated checkpoint on a node. The replica is created by invoking one of
the open calls on this node. If a replica for the checkpoint already exists on the node,
the open call does not create another replica on this node. 15
The Checkpoint Service does not create replicas for collocated checkpoints other
than the ones explicitly created by the applications by invoking an open call.
It is up to the applications to create enough number of replicas to have at any time the
desired level of redundancy (for instance, by creating a replica on another node when 20
a node becomes non-operational due to administrative operations).
3.1.7.2 Non-Collocated Checkpoints

Checkpoints created without the collocated attribute are called non-collocated
25
checkpoints. The management of replicas of non-collocated checkpoints and
whether to set the replicas to active or not (note that the notion “active” applies only to
checkpoints created with the asynchronous update option) is mainly the duty of the
Checkpoint Service.
The processes using the Checkpoint Service are not aware of the location of the
30
active replicas of these checkpoints. The Checkpoint Service may create replicas
other than the ones that may be created when opening a checkpoint. These other
replicas can be useful to enhance the availability of checkpoints. For example, if two
replicas exist at a certain point in time, and the node hosting one of these replicas is
administratively taken out of service, the Checkpoint Service may allocate another
35
replica on another node while this node is not available.
3.1.8 Persistence of Checkpoints

As has been stated in Section 2.1 on page 13, the Checkpoint Service typically stores
checkpoint data in the main memory of the nodes. Regardless of the retention time, a 40
checkpoint and all its sections do not survive if the Checkpoint Service stops running
on all nodes hosting replicas for this checkpoint. The stop of the Checkpoint Service
can be caused by administrative actions or node failures.
AIS Specification SAI-AIS-CKPT-B.02.02 Section 3.1.7.2 19

3.2 Unavailability of the Checkpoint Service API on a Non-Member Node 1
The Checkpoint Service does not provide service to processes on cluster nodes that
are not in the cluster membership (see [4]).
5
The following subsection describes the behavior of the Checkpoint Service under var-
ious conditions that cause the Checkpoint Service to be unavailable on a cluster
node. Section 3.2.2 contains guidelines for Checkpoint Service implementers for
dealing with a temporary unavailability of the service.
10
3.2.1 A Member Node Leaves or Rejoins the Cluster Membership
If the cluster node has left the cluster membership (see [4]) or is being administra-
tively evicted from the cluster membership, the Checkpoint Service behaves as fol-
lows towards processes residing on that cluster node and using or attempting to use
the service: 15
⇒ Calls to saCkptInitialize() will fail with SA_AIS_ERR_UNAVAILABLE.
⇒ All Checkpoint Service APIs that are invoked by the process and that operate on
handles already acquired by the process will fail with
SA_AIS_ERR_UNAVAILABLE with the following exceptions, assuming that the 20
handle ckptHandle has already been acquired, and no other errors occur:
• The saCkptCheckpointOpenAsync() function may return SA_AIS_OK or
SA_AIS_ERR_UNAVAILABLE, depending on the service implementation. If it

returns SA_AIS_OK, the callback SaCkptCheckpointOpenCallbackT will
be called and will also return SA_AIS_ERR_UNAVAILABLE in the error 25
parameter; otherwise, the callback will not be called.
• The saCkptCheckpointSynchronizeAsync() function may return
SA_AIS_OK or SA_AIS_ERR_UNAVAILABLE, depending on the service

implementation. If it returns SA_AIS_OK, the callback
30
SaCkptCheckpointSynchronizeCallbackT will be called and will also
return SA_AIS_ERR_UNAVAILABLE in the error parameter; otherwise, the
callback will not be called.
• The saCkptFinalize() function, which is used to free the library handles
and all resources associated with these handles, will return SA_AIS_OK. 35
⇒ Outstanding callbacks SaCkptCheckpointOpenCallbackT and
SaCkptCheckpointSynchronizeCallbackT will return
SA_AIS_ERR_UNAVAILABLE in the error parameter.
If the cluster node rejoins the cluster membership, processes executing on the cluster 40
node will be able to reinitialize new library handles and use the entire set of Check-
point Service APIs that operate on these new handles; however, invocation of APIs

that operate on handles acquired by any process before the cluster node left the 1
membership will continue to fail with SA_AIS_ERR_UNAVAILABLE (or with the spe-
cial treatment described above for asynchronous calls) with the exception of
saCkptFinalize(), which is used to free the library handles and all resources
associated with these handles. Hence, it is recommended for the processes to final- 5
ize the library handles as soon as the processes detect that the cluster node left the
membership.
When the cluster node leaves the membership, the Checkpoint Service executing on
the remaining nodes of the cluster behaves as if all processes that were using the 10
Checkpoint Service on the leaving cluster node had been terminated. In particular, if
an saCkptCheckpointUnlink() operation is pending because one or more pro-
cesses on the leaving cluster node had the checkpoint open, the unlink operation can
proceed now.
15
3.2.2 Guidelines for Checkpoint Service Implementers
The implementation of the Checkpoint Service must leverage the SA Forum Cluster
Membership Service (see [4]) to determine the membership status of a cluster node
for the case explained in Section 3.2.1 before returning
20
SA_AIS_ERR_UNAVAILABLE. If the Cluster Membership Service considers a cluster
node as a member of the cluster but the Checkpoint Service experiences difficulty in
providing service to its clients because of transport, communication, or other issues, it
must respond with SA_AIS_ERR_TRY_AGAIN.
25
30
35
40

3.3 Include File and Library Names 1
The following statement containing declarations of data types and function prototypes
must be included in the source of an application using the Checkpoint Service API:
5
#include <saCkpt.h>
To use the Checkpoint Service API, an application must be bound with the following
library:
libSaCkpt.so 10
3.4 Type Definitions

The Checkpoint Service uses the types described in the following sections.
15
3.4.1 Handles
3.4.1.1 SaCkptHandleT
typedef SaUint64T SaCkptHandleT;

20
The type of the handle supplied by the Checkpoint Service to a process during initial-
ization of the Checkpoint Service and used by a process when it invokes functions of
the Checkpoint Service API so that the Checkpoint Service can recognize the pro-
cess.
25
3.4.1.2 SaCkptCheckpointHandleT
typedef SaUint64T SaCkptCheckpointHandleT;

The type of the handle of a checkpoint.
30
3.4.1.3 SaCkptSectionIterationHandleT
typedef SaUint64T SaCkptSectionIterationHandleT;

The type of a handle for stepping through the sections in a checkpoint. 35
40

3.4.2 Checkpoint Types 1
3.4.2.1 SaCkptCheckpointCreationFlagsT
#define SA_CKPT_WR_ALL_REPLICAS 0X1 5

#define SA_CKPT_WR_ACTIVE_REPLICA 0X2
#define SA_CKPT_WR_ACTIVE_REPLICA_WEAK 0X4
#define SA_CKPT_CHECKPOINT_COLLOCATED 0X8
typedef SaUint32T SaCkptCheckpointCreationFlagsT; 10
The flags of the SaCkptCheckpointCreationFlagsT type have the following
interpretation:
• SA_CKPT_WR_ALL_REPLICAS - The specification of this flag at creation time
creates a checkpoint with the synchronous update option. Any of the opera- 15
tions that modify the checkpoint (saCkptSectionWrite(),
saCkptSectionOverwrite(), saCkptSectionCreate(), and
saCkptSectionDelete()) will be performed on all of the checkpoint repli-
cas before the operation returns. It also guarantees atomicity for each check-
point replica, that is, either the invocation succeeds, or it fails, and nothing has 20
been written to any of the replicas.
• SA_CKPT_WR_ACTIVE_REPLICA - The specification of this flag at creation
time creates a checkpoint with the asynchronous update option, which sup-
ports atomicity when replicas are updated: any of the operations that modify
the checkpoint will be performed on the active checkpoint replica before the 25
operation returns. The atomicity when updating replicas means: for each of the
checkpoint replicas, either the operation on the replica succeeds, or it fails,
and nothing has been written to the replica.
• SA_CKPT_WR_ACTIVE_REPLICA_WEAK - The specification of this flag at cre- 30
ation time creates a checkpoint with the partial update option. Any of the oper-
ations that modify the checkpoint will be performed on the active checkpoint
replica before the call returns. However, no guarantee of atomicity per check-
point replica is provided, that is, if the operation of writing does not complete
successfully, some sections might get corrupted. 35
• SA_CKPT_CHECKPOINT_COLLOCATED - A checkpoint created with such
attribute is called a collocated checkpoint; otherwise, it is called a non-collo-
cated checkpoint. For details, refer to Section 3.1.7 on page 18.
The flags SA_CKPT_WR_ALL_REPLICAS, SA_CKPT_WR_ACTIVE_REPLICA, and
SA_CKPT_WR_ACTIVE_REPLICA_WEAK are mutually exclusive. A value of type 40
SaCkptCheckpointCreationFlagsT is either one of the mutually exclusive flags

or the bitwise OR of one of these mutually exclusive flags and the 1

SA_CKPT_CHECKPOINT_COLLOCATED flag.
3.4.2.2 SaCkptCheckpointCreationAttributesT
5
typedef struct {
SaCkptCheckpointCreationFlagsT creationFlags;
SaSizeT checkpointSize;
SaTimeT retentionDuration; 10
SaUint32T maxSections;
SaSizeT maxSectionSize;
SaSizeT maxSectionIdSize;
} SaCkptCheckpointCreationAttributesT; 15
The attributes defined in the SaCkptCheckpointCreationAttributesT struc-
ture are as follows:
• creationFlags - These flags specify the collocation attribute of checkpoint
replicas and the update option (synchronous or asynchronous). For details, 20
refer to Section 3.4.2.1 on page 23.
• retentionDuration - The duration for which the checkpoint will be retained
while it is not opened by any process. The retentionDuration starts after
the last checkpoint user has closed the checkpoint.
25
• checkpointSize - The net size in bytes of each checkpoint replica that can
be used for application data.
• maxSections - The maximum number of sections in the checkpoint. Every
checkpoint has at least one section. If and only if maxSections is 1, a default
section is automatically created. This default section is identified by the special 30
section identifier descriptor SA_CKPT_DEFAULT_SECTION_ID
(see Section 3.4.3.1 on page 25).
• maxSectionSize - The upper bound on the possible size of the sections in
this checkpoint.
• maxSectionIdSize - The maximum length of the section identifier in the 35
checkpoint. To be accepted as a valid parameter, this value must not equal
zero and may be required to be greater than an implementation-specific mini-
mal value.
40
24 SAI-AIS-CKPT-B.02.02 Section 3.4.2.2 AIS Specification

Note: 1
• checkpointSize =< maxSections * maxSectionSize
• checkpointSize does not include the space needed for storing
maxSections * maxSectionIdSize. 5
3.4.2.3 SaCkptCheckpointOpenFlagsT
#define SA_CKPT_CHECKPOINT_READ 0X1

#define SA_CKPT_CHECKPOINT_WRITE 0X2 10
#define SA_CKPT_CHECKPOINT_CREATE 0X4
typedef SaUint32T SaCkptCheckpointOpenFlagsT;
The SaCkptCheckpointOpenFlagsT type has the following interpretation:
• SA_CKPT_CHECKPOINT_READ - The checkpoint is opened in read mode. 15
• SA_CKPT_CHECKPOINT_WRITE - The checkpoint is opened in write mode. In
order to modify either data or metadata associated with a checkpoint, the
checkpoint must be opened with this flag.
• SA_CKPT_CHECKPOINT_CREATE - The checkpoint is created if it does not 20
already exist.
3.4.3 Section Types
3.4.3.1 SaCkptSectionIdT 25
#define SA_CKPT_DEFAULT_SECTION_ID {0, NULL}
#define SA_CKPT_GENERATED_SECTION_ID {0, NULL}
These special constants define the section identifier descriptor of the default sec-
tion and the section identifier descriptor of a generated section. The section identifier 30
descriptor is represented by the SaCkptSectionIdT structure:
typedef struct {
SaUint16T idLen;
35
SaUint8T *id;
} SaCkptSectionIdT;
The fields of the SaCkptSectionIdT structure are the length of the section identi-
fier and a pointer to the section identifier.
40

3.4.3.2 SaCkptSectionCreationAttributesT 1
typedef struct {
SaCkptSectionIdT *sectionId;
5
SaTimeT expirationTime;
} SaCkptSectionCreationAttributesT;
The fields of the SaCkptSectionCreationAttributesT structure have the fol-
lowing interpretation:
10
• sectionId - [in/out] Pointer to the section identifier descriptor that identifies
the section to be created. If the section identifier descriptor has the special
value SA_CKPT_GENERATED_SECTION_ID, the Checkpoint Service automat-
ically generates a new section identifier and changes the values of the fields in
the section identifier descriptor. 15
• expirationTime - [in] The absolute time after which the Checkpoint Ser-
vice deletes the section automatically. The expirationTime can be speci-
fied when a section is created, or it can be later modified by invoking
saCkptSectionExpirationTimeSet(). If expirationTime has the
special value SA_TIME_END, the Checkpoint Service never deletes the sec- 20
tion automatically.
3.4.3.3 SaCkptSectionStateT
typedef enum { 25
SA_CKPT_SECTION_VALID = 1,
SA_CKPT_SECTION_CORRUPTED = 2
} SaCkptSectionStateT;
The values of the SaCkptSectionStateT enumeration type indicate that the sec- 30
tion is either valid or corrupted.
35
40

3.4.3.4 SaCkptSectionDescriptorT 1
typedef struct {
SaCkptSectionIdT sectionId;
5
SaTimeT expirationTime;
SaSizeT sectionSize;
SaCkptSectionStateT sectionState;
SaTimeT lastUpdate;
10
} SaCkptSectionDescriptorT;
The fields of the SaCkptSectionDescriptorT structure have the following inter-
pretation:
• sectionId - The section identifier descriptor that identifies the section. 15
• expirationTime - The absolute time at which the section will be deleted.
• sectionSize - The amount of the section that is currently in use.
• sectionState - The state of the section. A section is either in the
SA_CKPT_SECTION_VALID state or the SA_CKPT_SECTION_CORRUPTED
20
state. A section can be in the SA_CKPT_SECTION_CORRUPTED state when
the checkpoint has been created with the
SA_CKPT_WR_ACTIVE_REPLICA_WEAK property, and an invocation of
saCkptCheckpointWrite() or saCkptSectionOverwrite() did not
complete successfully.
25
• lastUpdate - The absolute time of the last update.
3.4.3.5 SaCkptSectionsChosenT
typedef enum {
30
SA_CKPT_SECTIONS_FOREVER = 1,
SA_CKPT_SECTIONS_LEQ_EXPIRATION_TIME = 2,
SA_CKPT_SECTIONS_GEQ_EXPIRATION_TIME = 3,
SA_CKPT_SECTIONS_CORRUPTED = 4, 35
SA_CKPT_SECTIONS_ANY = 5
} SaCkptSectionsChosenT;
The values of the SaCkptSectionChosenT enumeration type are used for search-
ing existing sections fulfilling the specified criteria. The values have the following 40
interpretation:

• SA_CKPT_SECTIONS_FOREVER - All sections with expiration time set to 1

SA_TIME_END.
• SA_CKPT_SECTIONS_LEQ_EXPIRATION_TIME - All sections with expiration
time less than or equal to the value of expirationTime.
5
• SA_CKPT_SECTIONS_GEQ_EXPIRATION_TIME - All sections with expiration
time greater than or equal to the value of expirationTime.
• SA_CKPT_SECTIONS_CORRUPTED - All corrupted sections.
• SA_CKPT_SECTIONS_ANY - All sections.
10
3.4.4 IoVector Types
3.4.4.1 SaCkptIOVectorElementT
typedef struct { 15
SaCkptSectionIdT sectionId;
void *dataBuffer;
SaSizeT dataSize;
SaOffsetT dataOffset; 20
SaSizeT readSize;
} SaCkptIOVectorElementT;
The fields of the SaCkptIOVectorElementT structure have the following interpre-
tation: 25
• sectionId - The section identifier descriptor that identifies the section into
which it is to be written or from which it is to be read.
• dataBuffer - A pointer to a buffer that contains data to be written to the sec-
tion or data read from the section. 30
• dataSize - Either the size in bytes of the data to be written to the section
from the buffer pointed to by dataBuffer or the size in bytes of the data to be
read from the section into the buffer pointed to by dataBuffer. This size is at
most maxSectionSize, as specified in the creation attributes of the check-
point. 35
• dataOffset - Offset in the section that marks the start of the data to be writ-
ten to it or to be read from it.
• readSize - Used by saCkptCheckpointRead() to record the number of
bytes of data that have been read from the section; otherwise, this field is 40
ignored.

3.4.5 SaCkptCheckpointDescriptorT 1
typedef struct {
SaCkptCheckpointCreationAttributesT
checkpointCreationAttributes; 5
SaUint32T numberOfSections;
SaSizeT memoryUsed;
} SaCkptCheckpointDescriptorT;
10
The fields of the SaCkptCheckpointDescriptorT structure have the following
interpretation:
• checkpointCreationAttributes - Structure containing the checkpoint
attributes that were set when the checkpoint was created by an invocation of
the saCkptCheckpointOpen() or saCkptCheckpointOpenAsync() 15
functions.
• numberOfSections - The number of sections in the checkpoint.
• memoryUsed - The number of bytes used in the checkpoint to store check-
point data. 20
3.4.6 SaCkptCallbacksT
The SaCkptCallbacksT structure is defined as follows:
typedef struct { 25
saCkptCheckpointOpenCallback;
SaCkptCheckpointSynchronizeCallbackT
saCkptCheckpointSynchronizeCallback;
30
} SaCkptCallbacksT;
The callbacks structure is supplied to the Checkpoint Service by a process and con-
tains the callback functions that the Checkpoint Service can invoke.
35
40

3.4.7 SaCkptCheckpointStatusT 1
The following enum describes the various states of a checkpoint that can be notified
to a system administrator in form of a state change notification. For details on notifi-
cations, refer to Chapter 6 and [2]. 5
typedef enum {
SA_CKPT_SECTION_RESOURCES_EXHAUSTED= 1,
SA_CKPT_SECTION_RESOURCES_AVAILABLE= 2
} SaCkptCheckpointStatusT; 10
The values of the SaCkptCheckpointStatusT enumeration type have the follow-

ing interpretation:
• SA_CKPT_SECTION_RESOURCES_EXHAUSTED - The maximum number of sec-
tions is reached, or no memory is left for write access. 15
• SA_CKPT_SECTION_RESOURCES_AVAILABLE - Memory is available for write
access, or at least one section within the checkpoint is available, after having
recovered from a preceding SA_CKPT_SECTION_RESOURCES_EXHAUSTED
condition. 20
3.4.8 SaCkptStateT
The following enum holds all the checkpoint state types. Currently, only one such
state is defined:
25
typedef enum {
SA_CKPT_CHECKPOINT_STATUS = 1
} SaCkptStateT;
30
35
40

3.5 Library Life Cycle 1
3.5.1 saCkptInitialize()
Prototype 5
SaAisErrorT saCkptInitialize(
SaCkptHandleT *ckptHandle,
const SaCkptCallbacksT *ckptCallbacks,
10
SaVersionT *version
);
Parameters
15
ckptHandle - [out] A pointer to the handle which identifies this particular initializa-
tion of the Checkpoint Service, and which is to be returned by the Checkpoint Ser-
vice. The SaCkptHandleT type is defined in Section 3.4.1.1 on page 22.
ckptCallbacks - [in] If ckptCallbacks is set to NULL, no callback is registered; 20

If ckptCallbacks is not set to NULL, it is a pointer to an SaCkptCallbacksT
structure which contains the callback functions of the process that the Checkpoint
Service may invoke. Only non-NULL callback functions in this structure will be regis-
tered. The SaCkptCallbacksT type is defined in Section 3.4.6 on page 29.
25
version - [in/out] As an input parameter, version is a pointer to a structure con-
taining the required Checkpoint Service version. In this case, minorVersion is
ignored and should be set to 0x00.
As an output parameter, version is a pointer to a structure containing the version
actually supported by the Checkpoint Service. The SaVersionT type is defined in 30
[1].
Description
This function initializes the Checkpoint Service for the invoking process and registers
35
the various callback functions. This function must be invoked prior to the invocation of
any other Checkpoint Service functionality. The handle pointed to by ckptHandle is
returned by the Checkpoint Service as the reference to this association between the
process and the Checkpoint Service. The process uses this handle in subsequent
communication with the Checkpoint Service.
40
If the implementation supports the specified releaseCode and majorVersion,
SA_AIS_OK is returned. In this case, the structure pointed to by the version param-
eter is set by this function to:
AIS Specification SAI-AIS-CKPT-B.02.02 Section 3.5 31

• releaseCode = required release code 1

• majorVersion = highest value of the major version that this implementation
can support for the required releaseCode
• minorVersion = highest value of the minor version that this implementation 5
can support for the required value of releaseCode and the returned value of
majorVersion
If the preceding condition cannot be met, SA_AIS_ERR_VERSION is returned, and
the structure pointed to by the version parameter is set to:
10
if (implementation supports the required releaseCode)
releaseCode = required releaseCode
else {
if (implementation supports releaseCode higher than the required 15
releaseCode)
releaseCode = the lowest value of the supported release codes that
is higher than the required releaseCode
else 20
releaseCode = the highest value of the supported release codes that
is lower than the required releaseCode
}
majorVersion = highest value of the major versions that this implementation can 25
support for the returned releaseCode
minorVersion = highest value of the minor versions that this implementation can
support for the returned values of releaseCode and majorVersion
30
Return Values
SA_AIS_OK - The function completed successfully.
SA_AIS_ERR_LIBRARY - An unexpected problem occurred in the library (such as
corruption). The library cannot be used anymore. 35
SA_AIS_ERR_TIMEOUT - An implementation-dependent timeout occurred before the
call could complete. It is unspecified whether the call succeeded or whether it did not.
SA_AIS_ERR_TRY_AGAIN - The service cannot be provided at this time. The pro-
cess may retry later.
40
SA_AIS_ERR_INVALID_PARAM - A parameter is not set correctly.

SA_AIS_ERR_NO_MEMORY - Either the Checkpoint Service library or the Checkpoint 1

Service provider is out of memory and cannot provide the service.
SA_AIS_ERR_NO_RESOURCES - There are insufficient resources (other than mem-
ory).
5
SA_AIS_ERR_VERSION - The version provided in the structure to which the
version parameter points is not compatible with the version of the Checkpoint Ser-
vice implementation.
SA_AIS_ERR_UNAVAILABLE - The operation requested in this call is unavailable on 10
this cluster node because it is not a member node.
See Also
saCkptSelectionObjectGet(), saCkptDispatch(), saCkptFinalize()
15
3.5.2 saCkptSelectionObjectGet()
Prototype
SaAisErrorT saCkptSelectionObjectGet( 20
SaCkptHandleT ckptHandle,
SaSelectionObjectT *selectionObject
);
25
Parameters
ckptHandle - [in] The handle which was obtained by a previous invocation of the
saCkptInitialize() function and which identifies this particular initialization of
the Checkpoint Service. The SaCkptHandleT type is defined in
30
selectionObject - [out] A pointer to the operating system handle that the invok-
ing process can use to detect pending callbacks. The SaSelectionObjectT type is
defined in [1].
35
Description
This function returns the operating system handle associated with the handle
ckptHandle. The invoking process can use the operating system handle to detect
pending callbacks, instead of repeatedly invoking the saCkptDispatch() function 40
for this purpose.

In a POSIX environment, the operating system handle is a file descriptor that is used 1
with the poll() or select() system calls to detect incoming callbacks.
The operating system handle returned by saCkptSelectionObjectGet() is valid
until saCkptFinalize() is invoked on the same handle ckptHandle.
5
Return Values
10
corruption). The library cannot be used anymore.
15
SA_AIS_ERR_BAD_HANDLE - The handle ckptHandle is invalid, since it is cor-
rupted, uninitialized, or has already been finalized.
20
SA_AIS_ERR_NO_MEMORY - Either the Checkpoint Service library or the Checkpoint
ory).
25
SA_AIS_ERR_UNAVAILABLE - The operation requested in this call is unavailable on
this cluster node due to one of the two reasons:
• the cluster node has left the cluster membership;
• the cluster node has rejoined the cluster membership, but the handle 30
ckptHandle was acquired before the cluster node left the cluster membership.
See Also
saCkptInitialize(), saCkptDispatch(), saCkptFinalize()
35
40

3.5.3 saCkptDispatch() 1
Prototype
SaAisErrorT saCkptDispatch( 5
SaDispatchFlagsT dispatchFlags
);
10
Parameters
the Checkpoint Service. The SaCkptHandleT type is defined in 15
dispatchFlags - [in] Flags that specify the callback execution behavior of the
saCkptDispatch() function, which have the values SA_DISPATCH_ONE,
SA_DISPATCH_ALL, or SA_DISPATCH_BLOCKING. These flags are values of the 20
SaDispatchFlagsT enumeration type, which is described in [1].
Description
In the context of the calling thread, this function invokes pending callbacks for the
handle ckptHandle in the way specified by the dispatchFlags parameter. 25
Return Values
SA_AIS_OK - The function completed successfully. This value is also returned if this
function is being invoked with dispatchFlags set to SA_DISPATCH_ALL or 30
SA_DISPATCH_BLOCKING, and the handle ckptHandle has been finalized.
SA_AIS_ERR_TIMEOUT - An implementation-dependent timeout occurred before the 35
40
SA_AIS_ERR_INVALID_PARAM - The dispatchFlags parameter is invalid.


See Also
saCkptInitialize(), saCkptSelectionObjectGet()
10
3.5.4 saCkptFinalize()
Prototype
SaAisErrorT saCkptFinalize( 15
SaCkptHandleT ckptHandle
);
Parameters
20
25
Description
The saCkptFinalize() function closes the association represented by the
ckptHandle parameter between the invoking process and the Checkpoint Service.
The process must have invoked saCkptInitialize() before it invokes this func- 30
tion. A process must invoke this function once for each handle acquired by invoking
saCkptInitialize().
If the saCkptFinalize() function completes successfully, it releases all resources
acquired when saCkptInitialize() was called. Moreover, it closes all check-
35
points that are open for the particular handle. Furthermore, it cancels all pending
SaCkptCheckpointOpenCallbackT callbacks related to the particular handle.
Note that because the callback invocation is asynchronous, it is still possible that
some callback calls are processed after this call returns successfully.
If a process terminates, the Checkpoint Service implicitly finalizes all instances of the 40
Checkpoint Service that are associated with the process, as described in the preced-
ing paragraph.

After saCkptFinalize() completes successfully, the handle ckptHandle and the 1

selection object associated with it are no longer valid.
Return Values
5
10
15
See Also
saCkptInitialize()
20
25
30
35
40

3.6 Checkpoint Management 1
3.6.1 saCkptCheckpointOpen() and saCkptCheckpointOpenAsync()
Prototype 5
SaAisErrorT saCkptCheckpointOpen(
const SaNameT *checkpointName,
10
const SaCkptCheckpointCreationAttributesT
*checkpointCreationAttributes,
SaCkptCheckpointOpenFlagsT checkpointOpenFlags,
SaTimeT timeout,
15
SaCkptCheckpointHandleT *checkpointHandle
);
SaAisErrorT saCkptCheckpointOpenAsync(
SaCkptHandleT ckptHandle, 20
SaInvocationT invocation,
const SaNameT *checkpointName,
const SaCkptCheckpointCreationAttributesT
*checkpointCreationAttributes, 25
SaCkptCheckpointOpenFlagsT checkpointOpenFlags
);
Parameters
30
35
invocation - [in] A parameter that identifies a particular invocation of the response
callback. The SaInvocationT type is defined in [1].
checkpointName - [in] A pointer to the checkpoint name that identifies a check-

point globally in a cluster. The SaNameT type is defined in [1]. 40

checkpointCreationAttributes - [in] A pointer to the creation attributes of a 1

checkpoint. The SaCkptCheckpointCreationAttributesT type is defined in
If the user intends only to open an existing checkpoint,
checkpointCreationAttributes must be set to NULL and the 5
SA_CKPT_CHECKPOINT_CREATE flag in checkpointOpenFlags may not be set.
If the user intends to open a checkpoint or create and open a checkpoint if it does not
exist, the structure to which checkpointCreationAttributes points must con-
tain the attributes for the checkpoint, and the SA_CKPT_CHECKPOINT_CREATE flag
in checkpointOpenFlags must be set. If the checkpoint already exists, it is not re- 10
created, and the call succeeds only if the creation attributes match the ones used at
creation time, excluding retentionDuration, which is ignored, as it may be inde-
pendently modified by invoking the
saCkptCheckpointRetentionDurationSet() function.
15
checkpointOpenFlags - [in] The value of this parameter is constructed by a bit-
wise OR of the flags defined by the SaCkptCheckpointOpenFlagsT type in
timeout - [in] The saCkptCheckpointOpen() invocation is considered to have 20

failed if it does not complete within the time specified. It is unspecified whether a
checkpoint is created or not. The SaTimeT type is defined in [1].
checkpointHandle - [out] A pointer to the checkpoint handle, allocated in the

address space of the invoking process. If the checkpoint is opened successfully, the 25
Checkpoint Service stores into the memory area to which checkpointHandle
points the handle that the process uses to access the checkpoint in subsequent invo-
cations of the functions of the Checkpoint Service API. In the case of
saCkptCheckpointOpenAsync(), this handle is returned in the corresponding
callback. The SaCkptCheckpointHandleT type is defined in 30
Description
The saCkptCheckpointOpen() and saCkptCheckpointOpenAsync() func-
35
tions open a checkpoint. If the checkpoint does not exist and the
SA_CKPT_CHECKPOINT_CREATE flag is set in the checkpointOpenFlags param-
eter, the checkpoint is first created.
An invocation of saCkptCheckpointOpen() is blocking. A new checkpoint handle
is returned upon successful completion. A checkpoint can be opened multiple times 40
for reading or writing in the same or different processes.

When a checkpoint replica is created as a result of this invocation, the following is 1

guaranteed:
• If the checkpoint has been created with the SA_CKPT_WR_ALL_REPLICAS
flag set, the checkpoint replica must be identical to the other checkpoint repli-
5
cas.
• Otherwise, the data in this new checkpoint replica is synchronized using the
data in the active checkpoint replica.
The completion of the saCkptCheckpointOpenAsync() function is signaled by
the associated saCkptCheckpointOpenCallback() callback function, which 10
must have been supplied when the process invoked the saCkptInitialize() call.
The process supplies the value of invocation when it invokes the
saCkptCheckpointOpenAsync() function and the Checkpoint Service gives that
value of invocation back to the application when it invokes the corresponding
saCkptCheckpointOpenCallback() function. The invocation parameter is a 15
mechanism that enables the process to determine which call triggered which call-
back.
Return Values
20
SA_AIS_ERR_TIMEOUT - An implementation-dependent timeout occurred, or the 25
timeout, specified by the timeout parameter, occurred before the call could com-
plete. It is unspecified whether the call succeeded or whether it did not.
30
SA_AIS_ERR_INIT - The previous invocation of saCkptInitialize() to initialize
the Checkpoint Service was incomplete, since the
saCkptCheckpointOpenCallback() callback function is missing. This return 35
value only applies to the saCkptCheckpointOpenAsync() function.
40

SA_AIS_ERR_INVALID_PARAM - A parameter is not set correctly. In particular, this 1

error is returned for each of the following cases:
• The user specifies checkpointCreationAttributes with
checkpointSize > maxSections * maxSectionSize.
5
• The SA_CKPT_CHECKPOINT_CREATE flag is not set, and
checkpointCreationAttributes is not NULL.
• The SA_CKPT_CHECKPOINT_CREATE flag is set and
checkpointCreationAttributes is NULL.
10
• The SA_CKPT_CHECKPOINT_CREATE flag is set, and the name to which
checkpointName points is not a valid checkpoint DN.
15
ory).
SA_AIS_ERR_NOT_EXIST - The SA_CKPT_CHECKPOINT_CREATE flag is not set,
the checkpointCreationAttributes is NULL, and the checkpoint designated
by the name to which checkpointName points does not exist. 20
SA_AIS_ERR_EXIST - The SA_CKPT_CHECKPOINT_CREATE flag is set, the check-
point already exists, and the creation attributes in the structure to which
checkpointCreationAttributes points (excluding retentionDuration,
which is ignored) are different from the ones used at creation time.
25
SA_AIS_ERR_BAD_FLAGS - The checkpointOpenFlags parameter is invalid.
• the cluster node has left the cluster membership; 30
• the cluster node has rejoined the cluster membership, but the handle
See Also
35
SaCkptCheckpointOpenCallbackT, saCkptCheckpointClose(),
saCkptInitialize(), saCkptCheckpointRetentionDurationSet()
40

3.6.2 SaCkptCheckpointOpenCallbackT 1
Prototype
typedef void (*SaCkptCheckpointOpenCallbackT)( 5

SaCkptCheckpointHandleT checkpointHandle,
SaAisErrorT error
); 10
Parameters
invocation - [in] This parameter was supplied by a process in the corresponding

invocation of the saCkptCheckpointOpenAsync() function and is used by the 15
Checkpoint Service in this callback. This invocation parameter allows the process to
match the invocation of that function with this callback. The SaInvocationT type is
defined in [1].
checkpointHandle - [in] The handle that identifies the checkpoint. The 20

SaCkptCheckpointHandleT type is defined in Section 3.4.1.2 on page 22.
error - [in] This parameter indicates whether the

saCkptCheckpointOpenAsync() function was successful. The SaAisErrorT
type is defined in [1]. The returned values are: 25
• SA_AIS_OK - The function completed successfully.
• SA_AIS_ERR_LIBRARY - An unexpected problem occurred in the library
(such as corruption). The library cannot be used anymore.
• SA_AIS_ERR_TIMEOUT - An implementation-dependent timeout occurred 30
before the call could complete. It is unspecified whether the call succeeded or
whether it did not.
• SA_AIS_ERR_TRY_AGAIN - The service cannot be provided at this time. The
process may try again.
35
• SA_AIS_ERR_BAD_HANDLE - The handle ckptHandle in the corresponding
invocation of the saCkptCheckpointOpenAsync() function is invalid, since
it is corrupted, uninitialized, or has already been finalized.
• SA_AIS_ERR_INVALID_PARAM - A parameter is not set correctly in the corre-
sponding invocation of the saCkptCheckpointOpenAsync() function. In 40
particular, this error is returned for each of the following cases:

• The user specifies checkpointCreationAttributes with 1

checkpointSize > maxSections * maxSectionSize.
• The SA_CKPT_CHECKPOINT_CREATE flag is not set, and
checkpointCreationAttributes is not NULL.

5
• The SA_CKPT_CHECKPOINT_CREATE flag is set and
checkpointCreationAttributes is NULL.
• The SA_CKPT_CHECKPOINT_CREATE flag is set, and the name to which
checkpointName points is not a valid checkpoint DN.

• SA_AIS_ERR_NO_MEMORY - Either the Checkpoint Service library or the 10
Checkpoint Service provider is out of memory and cannot provide the service.
• SA_AIS_ERR_NO_RESOURCES - There are insufficient resources (other than
memory).
• SA_AIS_ERR_NOT_EXIST - In the corresponding invocation of the 15
saCkptCheckpointOpenAsync() function, the
SA_CKPT_CHECKPOINT_CREATE flag is not set, the
checkpointCreationAttributes is NULL, and the checkpoint desig-
nated by the name to which checkpointName points does not exist.
• SA_AIS_ERR_EXIST - In the corresponding invocation of the 20
saCkptCheckpointOpenAsync() function, the
SA_CKPT_CHECKPOINT_CREATE flag is set, the checkpoint already exists,
and the creation attributes in the structure to which
checkpointCreationAttributes points (excluding
retentionDuration, which is ignored) are different from the ones used at 25
creation time.
• SA_AIS_ERR_BAD_FLAGS - The checkpointOpenFlags parameter in the
corresponding invocation of the saCkptCheckpointOpenAsync() function
is invalid.
30
• SA_AIS_ERR_UNAVAILABLE - The operation requested in the corresponding
invocation of the saCkptCheckpointOpenAsync() function is unavailable
on this cluster node due to one of the two reasons:
ckptHandle specified in the corresponding invocation of the
saCkptCheckpointOpenAsync() function was acquired before the clus-
ter node left the cluster membership.
40

Description 1
The Checkpoint Service calls this callback function when the operation requested by
the invocation of saCkptCheckpointOpenAsync() completes.
This callback is invoked in the context of a thread calling saCkptDispatch() on the 5
handle ckptHandle that was specified in the saCkptCheckpointOpenAsync()
call.
If successful, the reference to the opened/created checkpoint is returned in
checkpointHandle; otherwise, an error is returned in the error parameter. 10
Return Values
None
See Also 15
saCkptCheckpointOpenAsync(), saCkptDispatch(),
saCkptCheckpointClose()
3.6.3 saCkptCheckpointClose()
20
Prototype
SaAisErrorT saCkptCheckpointClose(
SaCkptCheckpointHandleT checkpointHandle
25
);
Parameters
checkpointHandle - [in] The handle that identifies the checkpoint to close. The 30
handle checkpointHandle must have been obtained previously by the invocation
of saCkptCheckpointOpen() or saCkptCheckpointOpenCallback(). The
Description 35
This API function closes the checkpoint identified by checkpointHandle and which
was opened by an earlier invocation of either saCkptCheckpointOpen() or
saCkptCheckpointOpenAsync().
After this invocation, the handle checkpointHandle is no longer valid. 40
This call frees all resources allocated for this process by the Checkpoint Service for
the checkpoint identified by the handle checkpointHandle. In particular, this call

frees memory allocated for the process and which has not yet been freed by the 1
saCkptSectionIdFree() or saCkptIOVectorElementDataFree() functions.
This call cancels all pending callbacks that refer directly or indirectly to the handle
checkpointHandle. Note that because the callback invocation is asynchronous, it
5
is still possible that some callback calls are processed after this call returns success-
fully.
When the invocation of the saCkptCheckpointClose() function completes suc-
cessfully, if no process has the checkpoint open any longer, the following will occur:
10
• The checkpoint is deleted immediately if its deletion was pending as a result of
an saCkptCheckpointUnlink() function, or
• the checkpoint will be deleted when the retention duration expires if no process
opens it in the meantime.
The deletion (unlink) of a checkpoint frees all resources allocated by the Checkpoint 15
Service for it.
When a process terminates, all of its opened checkpoints are closed.
Return Values 20
SA_AIS_ERR_BAD_HANDLE - The handle checkpointHandle is invalid, due to one 30
or both of the reasons below:
• It is corrupted, was not obtained with the saCkptCheckpointOpen() or
saCkptCheckpointOpenCallback() functions, or the corresponding check-
point has already been closed. 35
• The handle ckptHandle that was passed to the functions
saCkptCheckpointOpen() or saCkptCheckpointOpenAsync() has
already been finalized.
40


checkpointHandle was acquired before the cluster node left the cluster mem-
bership.
See Also
saCkptCheckpointOpen(), saCkptCheckpointOpenAsync(), 10
SaCkptCheckpointOpenCallbackT, saCkptCheckpointUnlink()
3.6.4 saCkptCheckpointUnlink()
Prototype 15
SaAisErrorT saCkptCheckpointUnlink(
const SaNameT *checkpointName
20
);
Parameters
ckptHandle - [in] The handle which was obtained by a previous invocation of the 25
checkpointName - [in] A pointer to the name of the checkpoint to be unlinked. The 30

SaNameT type is defined in [1].
Description
This function deletes from the cluster an existing checkpoint identified by the name to
which checkpointName points. 35
After successful completion of the invocation, the following applies:

• The name to which checkpointName points is no longer valid, that is, any invo-
cation of a function of the Checkpoint Service API that uses this checkpoint
name returns an error unless a checkpoint is re-created with this name. The 40
checkpoint is re-created by specifying in an open call the
SA_CKPT_CHECKPOINT_CREATE flag and the same name of the checkpoint to

be unlinked. This way, a new instance of the checkpoint is created while the old 1
instance of the checkpoint is possibly not yet finally deleted.
Note that this behavior is similar to the way POSIX treats files.
• If no process has the checkpoint open when saCkptCheckpointUnlink() is
invoked, the checkpoint is immediately deleted. 5
• Any process that has the checkpoint open can still continue to access it. Deletion
of the checkpoint will occur when the last saCkptCheckpointClose() opera-
tion is performed.
The deletion of a checkpoint frees all resources allocated by the Checkpoint Service 10
for it.
This API can be invoked by any process, and the invoking process need not be the
creator or opener of the checkpoint.
15
Return Values
20
cess may retry later. 25
SA_AIS_ERR_NOT_EXIST - The checkpoint identified by the name to which 30
checkpointName points does not exist.
See Also
40
saCkptCheckpointClose()

3.6.5 saCkptCheckpointRetentionDurationSet() 1
Prototype
SaAisErrorT saCkptCheckpointRetentionDurationSet( 5
SaTimeT retentionDuration
);
10
Parameters
checkpointHandle - [in] The handle that identifies the checkpoint whose retention
time is being set. The handle checkpointHandle must have been obtained previ-
ously by the invocation of saCkptCheckpointOpen() or 15
saCkptCheckpointOpenCallback(). The SaCkptCheckpointHandleT type is
defined in Section 3.4.1.2 on page 22.
retentionDuration - [in] The value of the retention duration to be set. The

checkpoint is retained (not deleted) for the retention duration. The SaNameT type is 20
defined in [1].
Description
The function saCkptCheckpointRetentionDurationSet() sets the retention
duration of the checkpoint identified by checkpointHandle to 25
retentionDuration. If the last checkpoint user closes the checkpoint, and the
checkpoint is not opened by any process within the retention duration, the Checkpoint
Service automatically deletes the checkpoint.
This function will fail with the SA_AIS_ERR_ACCESS return value if the checkpoint 30
identified by checkpointHandle was not opened for write mode.
Return Values
35
40


5
point has already been closed.
• The handle ckptHandle that was passed to the saCkptCheckpointOpen()
or saCkptCheckpointOpenAsync() functions has already been finalized.
10
SA_AIS_ERR_ACCESS - The checkpoint identified by checkpointHandle was not
opened for write mode.
SA_AIS_ERR_BAD_OPERATION - The retention duration of the checkpoint identified
by checkpointHandle cannot be changed as the checkpoint has been unlinked.
15
bership.
See Also
saCkptCheckpointOpen(), saCkptCheckpointOpenAsync(), 25
SaCkptCheckpointOpenCallbackT, saCkptCheckpointClose(),
saCkptCheckpointUnlink()
3.6.6 saCkptActiveReplicaSet()
30
Prototype
SaAisErrorT saCkptActiveReplicaSet(
SaCkptCheckpointHandleT checkpointHandle
); 35
Parameters
checkpointHandle - [in] The handle that identifies a checkpoint. The handle

checkpointHandle must have been obtained by a previous invocation of 40
saCkptCheckpointOpen() or saCkptCheckpointOpenAsync(). The

Description 1
This function can be used only for checkpoints that have been created with the collo-
cated attribute and the asynchronous update option.
The local checkpoint replica will become the active replica when this function com- 5
pletes successfully.
A local replica that was set active by a previous call to
saCkptActiveReplicaSet() and was not overridden by another call to
saCkptActiveReplicaSet() on another node, remains active until the check- 10
point expires, or the replica is destroyed.
This function will fail with the SA_AIS_ERR_ACCESS return value if the checkpoint
Return Values 15
20
25
SA_AIS_ERR_BAD_HANDLE - The handle checkpointHandle is invalid, due to one
point has already been closed. 30
opened for write mode. 35
SA_AIS_ERR_BAD_OPERATION - The checkpoint identified by checkpointHandle
was not created as a collocated checkpoint with the asynchronous update option.
40


bership.
See Also
saCkptCheckpointWrite(), saCkptSectionOverwrite(), 10
saCkptCheckpointRead(), saCkptCheckpointOpen(),
saCkptCheckpointOpenAsync(), SaCkptCheckpointOpenCallbackT
3.6.7 saCkptCheckpointStatusGet()
15
Prototype
SaAisErrorT saCkptCheckpointStatusGet(
20
SaCkptCheckpointDescriptorT *checkpointStatus
);
Parameters
25
checkpointHandle - [in] The handle to the checkpoint whose status is to be
returned. The handle checkpointHandle must have been obtained previously by
the invocation of saCkptCheckpointOpen() or
defined in Section 3.4.1.2 on page 22. 30
checkpointStatus - [out] A pointer to an SaCkptCheckpointDescriptorT

structure (allocated in the address space of the invoking process) into which this
function returns the checkpoint status information. The
SaCkptCheckpointDescriptorT structure is defined in Section 3.4.5 on page 29. 35
Description
This function retrieves the checkpoint status of the checkpoint identified by
checkpointHandle and writes the checkpoint status into the structure to which
checkpointStatus points. 40
If the checkpoint was created with either the SA_CKPT_WR_ACTIVE_REPLICA option
or the SA_CKPT_WR_ACTIVE_REPLICA_WEAK option, the checkpoint status is

obtained from the active replica. If the checkpoint was created with the 1
SA_CKPT_WR_ALL_REPLICAS option, the Checkpoint Service determines the rep-
lica from which to obtain the checkpoint status.
5
identified by checkpointHandle was not opened for read mode.
Return Values
10
15
20
or saCkptCheckpointOpenAsync() functions has already been finalized. 25
SA_AIS_ERR_NOT_EXIST - No active replica exists.
opened for read mode. 30

35
bership.
See Also
40
saCkptCheckpointOpen(), saCkptCheckpointOpenAsync(),

3.7 Section Management 1
3.7.1 saCkptSectionCreate()
Prototype 5
SaAisErrorT saCkptSectionCreate(
SaCkptSectionCreationAttributesT
10
*sectionCreationAttributes,
const void *initialData,
SaSizeT initialDataSize
);
15
Parameters
checkpointHandle - [in] The handle to the checkpoint that is to hold the section to
be created. The handle checkpointHandle must have been obtained by a previ-
ous invocation of saCkptCheckpointOpen() or 20
saCkptCheckpointOpenAsync(). The SaCkptCheckpointHandleT type is
sectionCreationAttributes - [in/out] A pointer to an

SaCkptSectionCreationAttributesT structure (as defined in 25
Section 3.4.3.2 on page 26) that contains the in/out field sectionId and the in
field expirationTime. The sectionId field is a pointer to the section identifier
descriptor, which identifies the section to be created. If the section identifier descriptor
has the special value SA_CKPT_GENERATED_SECTION_ID, the Checkpoint Service
automatically generates a new section identifier and changes the values of the fields 30
in the section identifier descriptor (SaCkptSectionIdT structure). In this case, the
id field points to an area of memory that is allocated by the Checkpoint Service
library to contain the new section identifier. The invoking process must free this mem-
ory by calling the saCkptSectionIdFree() function.
35
initialData - [in] Pointer to a location (in the address space of the invoking pro-
cess) that contains the initial data of the section to be created.
initialDataSize - [in] The size in bytes of the initial data of the section to be cre-
ated. This size can be at most maxSectionSize, as specified by the checkpoint cre- 40
ation attributes in the saCkptCheckpointOpen() or
saCkptCheckpointOpenAsync() functions. The SaSizeT type is defined in [1].

Description 1
This function creates a new section in the checkpoint identified by
checkpointHandle, provided that the total number of existing sections is less than
the maximum number of sections specified in one of the 5
saCkptCheckpointOpen() or saCkptCheckpointOpenAsync() API calls.
Unlike a checkpoint, a section does not need to be opened for access.
The Checkpoint Service deletes the section when its expiration time is reached.
If a checkpoint is created to have only one section, it is not necessary to create that
section. 10
The default section is identified by the special section identifier descriptor
SA_CKPT_DEFAULT_SECTION_ID.
If the checkpoint was created with the SA_CKPT_WR_ALL_REPLICAS property, the
section is created in all of the checkpoint replicas when the invocation returns; other-
wise, the section has been created at least in the active checkpoint replica when the 15
invocation returns and will be created asynchronously in the other checkpoint repli-
cas.
20
Return Values
saCkptCheckpointOpenCallback() functions, or the corresponding check- 35
40

SA_AIS_ERR_NO_MEMORY - Either the Checkpoint Service library or the Checkpoint 1

SA_AIS_ERR_NO_RESOURCES - The system does not have enough resources to
create this section.
5
SA_AIS_ERR_NO_SPACE - With the creation of this new section, the maximum num-
ber of sections specified for this checkpoint would be exceeded. The section is not
created.
SA_AIS_ERR_NOT_EXIST - No active replica exists. 10
SA_AIS_ERR_EXIST - The section identified by the section identifier descriptor
referred to by sectionId in the structure to which sectionCreationAttributes 15
points already exists, or the checkpoint was created to have only one section.
20
bership.
See Also 25
saCkptSectionDelete(), saCkptSectionIdFree(),
30
35
40

3.7.2 saCkptSectionDelete() 1
Prototype
SaAisErrorT saCkptSectionDelete( 5
const SaCkptSectionIdT *sectionId
);
10
Parameters
checkpointHandle - [in] The handle to the checkpoint holding the section to be

deleted. The handle checkpointHandle must have been obtained previously by
the invocation of saCkptCheckpointOpen() or 15
sectionId - [in] A pointer to the section identifier descriptor of the section to be

deleted. The SaCkptSectionIdT type is defined in Section 3.4.3.1 on page 25. 20
Description
This function deletes a section in the checkpoint identified by checkpointHandle.
If the checkpoint was created with the SA_CKPT_WR_ALL_REPLICAS property, the
section has been deleted in all of the checkpoint replicas when the invocation returns; 25
otherwise, the section has been deleted at least in the active checkpoint replica when
the invocation returns. The default section identified by the value
SA_CKPT_DEFAULT_SECTION_ID of the section identifier descriptor cannot be
deleted by invoking the saCkptSectionDelete() function.
30
Return Values
SA_AIS_OK - The function completed successfully. 35
call could complete. It is unspecified whether the call succeeded or whether it did not. 40


5
SA_AIS_ERR_INVALID_PARAM - A parameter is not set correctly. In particular, this 10
value is returned if the caller attempts to delete the default section.
SA_AIS_ERR_NOT_EXIST - No active replica exists, or the section identified by the
section identifier descriptor to which sectionId points does not exist.
SA_AIS_ERR_ACCESS - The checkpoint identified by checkpointHandle was not 15
bership.
25
See Also
saCkptSectionCreate(), saCkptCheckpointOpen(),
3.7.3 saCkptSectionIdFree() 30
Prototype
SaAisErrorT saCkptSectionIdFree(
SaCkptCheckpointHandleT checkpointHandle, 35
SaUint8T *id
);
Parameters
40
checkpointHandle - [in] The handle to the checkpoint. The handle
checkpointHandle must have been obtained by a previous invocation of

saCkptCheckpointOpen() or saCkptCheckpointOpenAsync(). The 1

id - [in] A pointer to the section identifier that was allocated by the Checkpoint Ser-
vice library in the saCkptSectionCreate() function and is to be freed. The 5
SaUint8T type is defined in [1].
Description
This function frees the memory to which id points. This memory was allocated by the
10
Checkpoint Service library in a previous call to the saCkptSectionCreate() func-
tion.
For details, refer to the description of the sectionCreationAttributes parame-
ter in the corresponding invocation of the saCkptSectionCreate() function.
15
Return Values
30
bership.
See Also 40
saCkptSectionCreate()

3.7.4 saCkptSectionExpirationTimeSet() 1
Prototype
SaAisErrorT saCkptSectionExpirationTimeSet( 5
const SaCkptSectionIdT* sectionId,
SaTimeT expirationTime
); 10
Parameters
checkpointHandle - [in] The handle to the checkpoint that contains the section
for which the expiration time is to be set. The handle checkpointHandle must 15
have been obtained by a previous invocation of saCkptCheckpointOpen() or
sectionId - [in] A pointer to the section identifier descriptor of the section for which 20
the expiration time is to be set. The SaCkptSectionIdT type is defined in
expirationTime - [in] The expiration time that is to be set for the section identified
by the section identifier descriptor to which sectionId points. The expiration time is 25
an absolute time that defines the time at which the Checkpoint Service will delete the
section automatically, regardless of whether the checkpoint is open by a process or
not.
If expirationTime has the special value SA_TIME_END, the Checkpoint Service
never deletes the section automatically. The SaTimeT type is defined in [1]. 30
Description
This function sets the expiration time of the section identified by the section identifier
descriptor pointed to by sectionId within the checkpoint identified by the handle
35
checkpointHandle to the value expirationTime. The expiration time of the
default section identified by SA_CKPT_DEFAULT_SECTION_ID is unlimited and can-
not be changed.
identified by checkpointHandle was not opened for write mode. 40

Return Values 1
20
SA_AIS_ERR_INVALID_PARAM - A parameter is not set correctly. In particular, this
value is returned if the section identifier descriptor of the section to which sectionId
points is set to SA_CKPT_DEFAULT_SECTION_ID.
25
30
bership. 35
See Also
saCkptSectionCreate(), saCkptCheckpointOpen(),
SaCkptCheckpointOpenCallbackT 40

3.7.5 saCkptSectionIterationInitialize() 1
Prototype
SaAisErrorT saCkptSectionIterationInitialize( 5
SaCkptSectionsChosenT sectionsChosen,
SaTimeT expirationTime,
SaCkptSectionIterationHandleT *sectionIterationHandle 10
);
Parameters
checkpointHandle - [in] The checkpoint handle which was obtained previously by 15

an invocation of saCkptCheckpointOpen() or
sectionsChosen - [in] A predicate (as defined by the SaCkptSectionsChosenT 20

structure in Section 3.4.3.5 on page 27) that describes the sections to be chosen dur-
ing an iteration.
expirationTime - [in] An absolute time used by sectionsChosen, as described

above. This field is ignored when sectionsChosen is 25
SA_CKPT_SECTIONS_FOREVER, SA_CKPT_SECTIONS_CORRUPTED, or
SA_CKPT_SECTIONS_ANY. The SaTimeT type is defined in [1].
sectionIterationHandle - [out] A pointer to a memory area allocated by the

invoking process to contain the section iteration handle. If this function returns suc- 30
cessfully, the Checkpoint Service stores into this memory area the handle that the
process uses in subsequent invocations of the saCkptSectionIterationNext()
and saCkptSectionIterationFinalize() functions for stepping through the
sections of the checkpoint identified by checkpointHandle. The
SaCkptSectionIterationHandleT type is defined in Section 3.4.1.3 on page 22. 35
Description
This function returns the section iteration handle for stepping through the sections of
a checkpoint identified by checkpointHandle. The iteration steps only through 40
sections that match the criteria specified in sectionsChosen. The Checkpoint Ser-
vice keeps track of the current position while iterating through sections.

Return Values
5
10
15
• The handle ckptHandle that was passed to the functions 20
SA_AIS_ERR_NOT_EXIST - No active replica exists. This return code applies only to 25
checkpoints created with the asynchronous update option.
opened for read mode.
checkpointHandle was acquired before the cluster node left the cluster mem- 35
bership.
See Also
saCkptSectionIterationNext(), saCkptSectionIterationFinalize(),
40
saCkptSectionCreate(), saCkptSectionDelete(),
saCkptCheckpointOpen(), saCkptCheckpointOpenAsync()

3.7.6 saCkptSectionIterationNext() 1
Prototype
SaAisErrorT saCkptSectionIterationNext( 5
SaCkptSectionIterationHandleT sectionIterationHandle,
SaCkptSectionDescriptorT *sectionDescriptor
);
10
Parameters
sectionIterationHandle - [in] The section iteration handle which was obtained

by an invocation of the saCkptSectionIterationInitialize() function for
stepping through the sections of a checkpoint. The 15
SaCkptSectionIterationHandleT type is defined in Section 3.4.1.3 on page 22.
sectionDescriptor - [out] A pointer to an SaCkptSectionDescriptorT struc-

ture (as defined in Section 3.4.3.4 on page 27), which is allocated by the invoking
process. The saCkptSectionIterationNext() function places the requested 20
information into this structure. Note that the memory to which
sectionDescriptor->sectionId.id points is allocated by the Checkpoint Ser-
vice, and it is up to the Checkpoint Service to free this memory either
• at the next invocation of the saCkptSectionIterationNext() to continue
the iteration, or 25
• when the saCkptSectionIterationFinalize() function is called to final-
ize the iteration, or
• when the corresponding checkpoint is closed, or
• the handle of this particular initialization of the Checkpoint Service is finalized. 30
The memory area to which sectionDescriptor points should be deallocated by

the invoking process.
Description 35
This function iterates over an internal table of sections by using the handle
sectionIterationHandle which was obtained by a previous invocation of the
saCkptSectionIterationInitialize() function. When the function returns
successfully, the structure to which sectionDescriptor points is set to the
40
descriptor of a section. A subsequent invocation of
saCkptSectionIterationNext() returns another section. When there are no
more sections to return, an error is returned.

Every section created before the invocation of the 1

saCkptSectionIterationInitialize() function and not deleted before the
invocation of saCkptSectionIterationFinalize() will be returned exactly
once by this invocation. No other guarantees are given; sections that are created
after an iteration is initialized or deleted before an iteration is finalized, may or may 5
not be returned by an invocation of this function.
Return Values
10
15
SA_AIS_ERR_BAD_HANDLE - The handle sectionIterationHandle is invalid,
due to one or more of the reasons below:
20
• The handle sectionIterationHandle is either corrupted, or it was not
obtained with the saCkptSectionIterationInitialize() function, or
saCkptSectionIterationFinalize() has already been invoked.
• The checkpoint identified by checkpointHandle, which was specified in the
corresponding saCkptSectionIterationInitialize() call, has already 25
been closed.
SA_AIS_ERR_INVALID_PARAM - A parameter is not set correctly. 30
SA_AIS_ERR_NOT_EXIST - No active replica exists. This return code applies only to
checkpoints created with the asynchronous update option. 35
SA_AIS_ERR_NO_SECTIONS - There are no more sections matching
sectionsChosen.
40


sectionIterationHandle was acquired before the cluster node left the clus-
ter membership.
See Also
saCkptSectionIterationInitialize(), 10
saCkptSectionIterationFinalize(), saCkptSectionCreate(),
saCkptSectionDelete(), saCkptCheckpointOpen(),
saCkptCheckpointOpenAsync()
3.7.7 saCkptSectionIterationFinalize() 15
Prototype
SaAisErrorT saCkptSectionIterationFinalize(
SaCkptSectionIterationHandleT sectionIterationHandle 20
);
Parameters
25
sectionIterationHandle - [in] The section iteration handle which was obtained
by an invocation of the saCkptSectionIterationInitialize() function and
which identifies the iteration to be finalized. The
SaCkptSectionIterationHandleT type is defined in Section 3.4.1.3 on page 22.
Description 30
This function frees resources allocated for iteration.
Return Values
SA_AIS_OK - The function completed successfully. 35

call could complete. It is unspecified whether the call succeeded or whether it did not. 40


SA_AIS_ERR_BAD_HANDLE - The handle sectionIterationHandle is invalid, 1

due to one or more of the reasons below:
• The handle sectionIterationHandle is either corrupted, or it was not
obtained with the saCkptSectionIterationInitialize() function, or
5
saCkptSectionIterationFinalize() has already been invoked.
• The checkpoint identified by checkpointHandle, which was specified in the
corresponding saCkptSectionIterationInitialize() call, has already
been closed.
• The handle ckptHandle that was passed to the saCkptCheckpointOpen() 10
SA_AIS_ERR_NOT_EXIST - No active replica exists. This return code applies only to
checkpoints created with the asynchronous update option.
sectionIterationHandle was acquired before the cluster node left the clus- 20
ter membership.
See Also
saCkptSectionIterationInitialize(),
saCkptSectionIterationNext(), saCkptSectionCreate(), 25
saCkptSectionDelete(), saCkptCheckpointOpen(),
saCkptCheckpointOpenAsync()
30
35
40

3.8 Data Access 1
3.8.1 saCkptCheckpointWrite()
Prototype 5
SaAisErrorT saCkptCheckpointWrite(
const SaCkptIOVectorElementT *ioVector,
10
SaUint32T numberOfElements,
SaUint32T *erroneousVectorIndex
);
Parameters 15
checkpointHandle - [in] The handle to the checkpoint into which data is to be

written. The handle checkpointHandle must have been obtained by a previous
invocation of saCkptCheckpointOpen() or saCkptCheckpointOpenAsync().
The SaCkptCheckpointHandleT type is defined in Section 3.4.1.2 on page 22. 20
ioVector - [in] A pointer to an array with elements ioVector[0], ...,

ioVector[numberOfElements - 1]. The type of each element is
SaCkptIOVectorElementT, as defined in Section 3.4.4.1 on page 28. Each ele-
ment contains the following fields: sectionId, dataBuffer, dataSize, 25
dataOffset, and readSize. If sectionId is equal to
SA_CKPT_DEFAULT_SECTION_ID, the default section is written. The value of
dataSize is at most maxSectionSize, as specified in the creation attributes of the
checkpoint. The field readSize is ignored by the saCkptCheckpointWrite()
function. 30
numberOfElements - [in] The number of elements in the array to which the

ioVector parameter points. The SaUint32T type is defined in [1].
erroneousVectorIndex - [in/out] This parameter is ignored if the 35

saCkptCheckpointWrite() function succeeds. Otherwise, and it is not NULL, it
specifies a pointer to a field (in the address space of the invoking process) where the
Checkpoint Service places the index of the first element of the array pointed to by the
ioVector parameter at which the invocation fails. The index zero corresponds to
ioVector[0]. The SaUint32T type is defined in [1]. 40

Description 1
This function writes data from the memory area(s) specified by the ioVector param-
eter into a checkpoint:
• If the checkpoint has been created with the SA_CKPT_WR_ALL_REPLICAS 5
property, all of the checkpoint replicas have been updated when the invocation
returns SA_AIS_OK; otherwise, nothing has been written at all.
• If the checkpoint has been created with the SA_CKPT_WR_ACTIVE_REPLICA
property, the active checkpoint replica has been updated when the invocation
10
returns SA_AIS_OK. Other checkpoint replicas are updated asynchronously. If
the invocation does not return SA_AIS_OK, nothing has been written at all.
• If the checkpoint been created with the
SA_CKPT_WR_ACTIVE_REPLICA_WEAK property, the active checkpoint rep-
lica has been updated when the invocation returns SA_AIS_OK. Other check- 15
point replicas are updated asynchronously. If the invocation returns with an
error, nothing has been written at all. However, if the invocation does not com-
plete because the process exited while calling saCkptCheckpointWrite(),
the operation may be partially completed, and some sections may be cor-
rupted in the active checkpoint replica. 20
In a single invocation, several sections and several portions of sections can be
updated simultaneously. The elements of the array to which the ioVector parame-
ter points are written in order from ioVector[0] to
ioVector[numberOfElements - 1]. As a result of this invocation, some sections
might grow. 25
Return Values 30
40


5
SA_AIS_ERR_INVALID_PARAM - A parameter is not set correctly. 10

ory). 15
SA_AIS_ERR_NOT_EXIST - No active replica exists, or a section identified by the

section identifier descriptor sectionId in an element of the array to which the
ioVector parameter points does not exist.
bership.
30
See Also
saCkptSectionOverwrite(), saCkptCheckpointRead(),
35
40

3.8.2 saCkptSectionOverwrite() 1
Prototype
SaAisErrorT saCkptSectionOverwrite( 5
const SaCkptSectionIdT *sectionId,
const void *dataBuffer,
SaSizeT dataSize 10
);
Parameters
checkpointHandle - [in] The handle that identifies the checkpoint containing a 15

section to be overwritten. The handle checkpointHandle must have been obtained
by a previous invocation of saCkptCheckpointOpen() or
20
sectionId - [in] A pointer to the section identifier descriptor of the section to over-
write. If the section identifier descriptor has the value
SA_CKPT_DEFAULT_SECTION_ID, the default section is updated. The
SaCkptSectionIdT type is defined in Section 3.4.3.1 on page 25.
25
dataBuffer - [in] A pointer to a buffer that contains the data to be written.
dataSize - [in] The size in bytes of the data to be written. This value becomes the
new size for this section. The SaSizeT type is defined in [1].
30
Description
This function is similar to saCkptCheckpointWrite(), but it overwrites only a sin-
gle section. As a result of this invocation, the previous data and size of the section
may change. This function may be invoked for a section, even if the 35
saCkptCheckpointWrite() function was not previously invoked for the section.
40

Return Values 1
20
SA_AIS_ERR_NO_RESOURCES - There are insufficient resources (other than mem- 25
ory).
bership.
40

See Also 1
saCkptCheckpointRead(), saCkptCheckpointWrite(),
SaCkptCheckpointOpenCallbackT 5
3.8.3 saCkptCheckpointRead()
Prototype
SaAisErrorT saCkptCheckpointRead( 10
SaCkptIOVectorElementT *ioVector,
SaUint32T numberOfElements,
15
SaUint32T *erroneousVectorIndex
);
Parameters
20
checkpointHandle - [in] The handle to the checkpoint from which data is to be
read. The handle checkpointHandle must have been obtained by a previous invo-
cation of saCkptCheckpointOpen() or saCkptCheckpointOpenCallback().
The SaCkptCheckpointHandleT type is defined in Section 3.4.1.2 on page 22.
25
ioVector - [in/out] A pointer to an array that contains elements ioVector[0], ...,
ioVector[numberOfElements - 1]. The type of each element is
SaCkptIOVectorElementT, as defined in Section 3.4.4.1 on page 28. An element
contains the following fields:
• sectionId - [in] The section identifier descriptor of the section from which to 30
read.
• dataBuffer - [in/out] A pointer to a buffer into which read section data is
placed. If dataBuffer is NULL, the value of dataSize provided by the
invoker is ignored and the buffer is provided by the Checkpoint Service library.
35
The buffer must be freed by the invoking process by calling the
saCkptIOVectorElementDataFree() function. Providing a NULL
dataBuffer indicates also that the intention is to read from dataOffset up
to the end of the section identified by the section identifier descriptor
sectionId.
40
• dataSize - [in] Size of the data to be read from the section to the buffer to
which dataBuffer points. The size is at most maxSectionSize, as speci-
fied in the creation attributes of the checkpoint.

• dataOffset - [in] Offset in the section that marks the start of the data to be 1
read from the section.
• readSize - [out] Used by saCkptCheckpointRead() to record the num-
ber of bytes of data that have been read from the section.
5
numberOfElements - [in] The number of elements in the array to which the
ioVector parameter points. The SaUint32T type is defined in [1].
erroneousVectorIndex - [in/out] This parameter is ignored if the

saCkptCheckpointRead() function succeeds. Otherwise, and it is not NULL, it 10
specifies a pointer to a field (in the address space of the invoking process) where the
Checkpoint Service places the index of the first element of the array pointed to by
ioVector parameter at which the invocation fails. The index zero corresponds to the
element ioVector[0]. The SaUint32T type is defined in [1].
15
Description
This function copies data from a checkpoint replica into the array specified by
ioVector. Some of the buffers provided to the invocation may have been modified if
the invocation does not succeed. 20
When the buffer to which dataBuffer points is allocated by the Checkpoint Service
library, care must be taken to ensure that the invoking process deallocates that buffer
space promptly.
Return Values
30
35
40
saCkptCheckpointOpenCallback) functions, or the corresponding check-

• The handle ckptHandle that was passed to the functions 1

5
SA_AIS_ERR_NOT_EXIST - No active replica exists, or a section identified by the
section identifier descriptor sectionId in one of the elements of the array to which 10
ioVector points does not exist.
opened for read mode.
bership. 20
See Also
saCkptIOVectorElementDataFree(), saCkptCheckpointWrite(),
saCkptSectionOverwrite(), saCkptCheckpointOpen(), 25
3.8.4 saCkptIOVectorElementDataFree()
Prototype 30
SaAisErrorT saCkptIOVectorElementDataFree(
void *data
); 35
Parameters
checkpointHandle - [in] The handle of the checkpoint. The handle

checkpointHandle must have been obtained by a previous invocation of 40
saCkptCheckpointOpen() or saCkptCheckpointOpenAsync(). The

data - [in] A pointer to the buffer that was allocated by the Checkpoint Service 1
library in the saCkptCheckpointRead() function and is to be freed.
Description
5
This function frees the memory to which data points and which was allocated by the
Checkpoint Service library in a previous call to the saCkptCheckpointRead()
function.
For details, refer to the description of the ioVector parameter in the corresponding
invocation of the saCkptCheckpointRead() function. 10
Return Values
SA_AIS_ERR_LIBRARY - An unexpected problem occurred in the library (such as 15
• It is corrupted, was not obtained with the saCkptCheckpointOpen() or 20
saCkptCheckpointOpenCallback) functions, or the corresponding check-
already been finalized. 25
30
bership.
35
See Also
saCkptCheckpointRead()
40

3.8.5 saCkptCheckpointSynchronize(), saCkptCheckpointSynchronizeAsync() 1
Prototype
SaAisErrorT saCkptCheckpointSynchronize( 5
SaTimeT timeout
);
10
SaAisErrorT saCkptCheckpointSynchronizeAsync(
SaInvocationT invocation
);
15
Parameters
checkpointHandle - [in] The handle of the checkpoint to be synchronized. The

handle checkpointHandle must have been obtained by a previous invocation of
saCkptCheckpointOpen() or saCkptCheckpointOpenAsync(). The 20
invocation - [in] This parameter identifies a particular invocation of the response

callback. The SaInvocationT type is defined in [1].
25
timeout - [in] The function will terminate if the time it takes exceeds timeout;
however, the propagation of the checkpoint data to other checkpoint replicas might
continue even if this error is returned. The SaTimeT type is defined in [1].
Description 30
The saCkptCheckpointSynchronize() and

saCkptCheckpointSynchronizeAsync() functions ensure that all previous
operations applied on the active checkpoint replica are propagated to other check-
point replicas. Such operations are saCkptCheckpointWrite(), 35
saCkptSectionOverwrite(), saCkptSectionCreate(), and
saCkptSectionDelete().
It is not guaranteed that new operations applied while the synchronization is in
progress will be propagated when the synchronization operation completes. If new
operations are applied while the synchronization is in progress, it is not guaranteed 40
that the replicas are all identical when saCkptCheckpointSynchronize()
returns, or the saCkptCheckpointSynchronizeCallback() callback is invoked

(see the description of the flags SA_CKPT_WR_ACTIVE_REPLICA and 1

SA_CKPT_WR_ACTIVE_REPLICA_WEAK in Section 3.4.2.1 on page 23).
The saCkptCheckpointSynchronize() and
saCkptCheckpointSynchronizeAsync() functions apply only to checkpoints
5
created with the asynchronous update option.
If the specified timeout expires when invoking the
saCkptCheckpointSynchronize() function, it is not guaranteed that the check-
point replicas have been synchronized.
10
The completion of the saCkptCheckpointSynchronizeAsync() function is sig-
naled by the associated saCkptCheckpointSynchronizeCallback() callback
function, which must have been supplied when the process invoked the
saCkptInitialize() call.
The invoking process sets the invocation parameter and the Checkpoint Service 15
uses the value of invocation in the invocation of the callback function.
The SA_AIS_ERR_ACCESS value is returned if the checkpoint identified by
checkpointHandle was not opened for write mode.
Return Values 20
25
SA_AIS_ERR_TIMEOUT - An implementation-dependent timeout occurred, or the
timeout specified by the timeout parameter occurred before the call could complete.
It is unspecified whether the call succeeded or whether it did not.
40

SA_AIS_ERR_INIT - The previous invocation of saCkptInitialize() to initialize 1

the Checkpoint Service was incomplete, since the
saCkptCheckpointSynchronizeCallback() callback function is missing. This
return value applies only to the saCkptCheckpointSynchronizeAsync() func-
tion. 5
10
ory).
SA_AIS_ERR_NOT_EXIST - No active replica exists.
SA_AIS_ERR_BAD_OPERATION - The checkpoint identified by checkpointHandle
was not created with the asynchronous update option.
20
bership. 25
See Also
SaCkptCheckpointSynchronizeCallbackT, saCkptCheckpointOpen(),
saCkptCheckpointOpenAsync(), saCkptInitialize(), 30
saCkptCheckpointWrite(), saCkptSectionOverwrite(),
saCkptSectionCreate(), saCkptSectionDelete(),
35
40

3.8.6 SaCkptCheckpointSynchronizeCallbackT 1
Prototype
typedef void (*SaCkptCheckpointSynchronizeCallbackT)( 5

SaAisErrorT error
);
10
Parameters
invocation - [in] This parameter is supplied by a process in the corresponding

invocation of the saCkptCheckpointSynchronize() function and is used by the
Checkpoint Service in this callback. This invocation parameter allows the process to 15
match the invocation of that function with this callback. The SaInvocationT type is
defined in [1].
error - [in] This parameter indicates whether the

saCkptCheckpointSynchronize() function was successful. The SaAisErrorT 20
type is defined in [1]. The possible return values are:
• SA_AIS_OK - The function completed successfully.
• SA_AIS_ERR_LIBRARY - An unexpected problem occurred in the library
(such as corruption). The library cannot be used anymore.
25
• SA_AIS_ERR_TIMEOUT - An implementation-dependent timeout occurred
before the call could complete. It is unspecified whether the call succeeded or
whether it did not.
• SA_AIS_ERR_TRY_AGAIN - The service cannot be provided at this time. The
process may retry later. 30
• SA_AIS_ERR_BAD_HANDLE - The handle checkpointHandle that was
passed to the corresponding saCkptCheckpointSynchronizeAsync()
function is invalid, due to one or both of the reasons below:
35
saCkptCheckpointOpenCallback() functions, or the corresponding
checkpoint has already been closed.
already been finalized. 40

• SA_AIS_ERR_INVALID_PARAM - A parameter was not set correctly in the 1

corresponding invocation of the saCkptCheckpointSynchronizeAsync()
function.
• SA_AIS_ERR_NO_MEMORY - Either the Checkpoint Service library or the
Checkpoint Service provider is out of memory and cannot provide the service. 5
• SA_AIS_ERR_NO_RESOURCES - There are insufficient resources (other than
memory).
• SA_AIS_ERR_NOT_EXIST - No active replica exists.
• SA_AIS_ERR_ACCESS - The checkpoint identified by checkpointHandle in 10
the corresponding invocation of the
saCkptCheckpointSynchronizeAsync() function was not opened for
write mode.
• SA_AIS_ERR_BAD_OPERATION - The checkpoint identified by
15
checkpointHandle in the corresponding invocation of the
saCkptCheckpointSynchronizeAsync() function was not created with
the asynchronous update option.
• SA_AIS_ERR_UNAVAILABLE - The operation requested in the corresponding
invocation of the saCkptCheckpointSynchronizeAsync() function is 20
unavailable on this cluster node due to one of the two reasons:
checkpointHandle specified in the corresponding invocation of the

saCkptCheckpointSynchronizeAsync() function was acquired before 25
the cluster node left the cluster membership.
Description
The Checkpoint Service invokes this callback function when the operation requested 30
by the invocation of saCkptCheckpointSynchronizeAsync() completes.
This callback is invoked in the context of a thread calling saCkptDispatch() on the
handle ckptHandle that is associated with the
saCkptCheckpointSynchronizeAsync() call. Associated means here that
ckptHandle was specified in an saCkptCheckpointOpen() or 35
saCkptCheckpointOpenAsync() call to obtain the handle checkpointHandle
which in turn was used as an input parameter of the
saCkptCheckpointSynchronizeAsync() call.
The result of the function is returned in the error parameter. 40

This function fails with the SA_AIS_ERR_ACCESS return value if the checkpoint iden- 1
tified by checkpointHandle in the corresponding invocation of the
saCkptCheckpointSynchronizeAsync() function was not opened for write
mode.
5
Return Values
None
See Also
10
saCkptCheckpointSynchronizeAsync(), saCkptCheckpointOpen(),
saCkptCheckpointOpenAsync(), saCkptDispatch()
15
20
25
30
35
40

10
15
20
25
30
35
40

UML Information Model
4 Checkpoint Service UML Information Model 1
The Checkpoint Service Information Model is described in UML and has been orga-
nized in a UML class diagram.
5
The Checkpoint Service UML model is implemented by the SA Forum IMM Service
([2]). For further details on this implementation, refer to the SA Forum Overview doc-
ument ([1]).
The Checkpoint Service UML class diagram has two object classes, which show the 10
contained attributes and the administrative operations (if any) applicable on these
classes.
4.1 DN Format for Checkpoint Service UML Classes

15
Table 2 DN Formats for Objects of Checkpoint Service Classes
Object Class DN Formats for Objects of the Class

20
SaCkptCheckpoint "safCkpt=...,* "
SaCkptReplica "safReplica=...,safCkpt=...,* "
4.2 Checkpoint Service UML Classes 25
The two object classes of the Checkpoint Service UML model are:
• SaCkptCheckpoint —This is a runtime object class, which is used to represent
a checkpoint.
30
• SaCkptReplica —This is a runtime object class, which is used to represent a
checkpoint replica.
FIGURE 1 shows these two classes. A description of each attribute of these classes
may be found in the XMI file (see [5]). For additional details, refer to the SA Forum 35
Overview document (see [1]).
40

UML Information Model
1
FIGURE 1 Checkpoint Service UML Classes
<<RUNTIME>>
SaCkptCheckpoint 5
safCkpt : SaStringT [1]{RDN, RUNTIME, CACHED}
saCkptCheckpointSize : SaUint64T [1]{RUNTIME}
saCkptCheckpointUsedSize : SaUint64T [1]{RUNTIME}
saCkptCheckpointCreationTimestamp : SaTimeT [1]{RUNTIME, CACHED}
saCkptCheckpointCreationFlags : SaCkptCheckpointCreationFlagsT [1]{RUNTIME, CACHED, SAUINT32T}
saCkptCheckpointRetDuration : SaTimeT [1]{RUNTIME} 10
saCkptCheckpointMaxSections : SaUint32T [1]{RUNTIME, CACHED}
saCkptCheckpointMaxSectionSize : SaUint64T [1]{RUNTIME, CACHED}
saCkptCheckpointMaxSectionIdSize : SaUint64T [1]{RUNTIME, CACHED}
saCkptCheckpointNumOpeners : SaUint32T [1]{RUNTIME}
saCkptCheckpointNumReaders : SaUint32T [1]{RUNTIME}
saCkptCheckpointNumWriters : SaUint32T [1]{RUNTIME} 15
saCkptCheckpointNumReplicas : SaUint32T [1]{RUNTIME}
saCkptCheckpointNumSections : SaUint32T [1]{RUNTIME}
saCkptCheckpointNumCorruptSections : SaUint32T [1]{RUNTIME}
<<RUNTIME>> 20
SaCkptReplica
safReplica : SaNameT [1]{RUNTIME}
saCkptReplicaIsActive : SaBoolT [1]{RUNTIME, SAUINT32T}
25
30
35
40

Administration API
5 Checkpoint Service Administration API 1
The Checkpoint Service has no administration interface at the time of publication of

this specification.
5
10
15
20
25
30
35
40

Administration API
10
15
20
25
30
35
40
86 SAI-AIS-CKPT-B.02.02 Section 5 AIS Specification

Alarms and Notifications
6 Checkpoint Service Alarms and Notifications 1
The Checkpoint Service produces certain alarms and notifications to convey impor-
tant information regarding
• its operational and functional state and 5
• the operational and functional state of the objects under its control
to an administrator or a management system.

10
These reports vary in perceived severity and include alarms, which potentially require
an operator intervention, and notifications that signify important state or object
changes. A management entity should regard notifications, but they do not necessar-
ily require an operator intervention.
15
The recommended vehicle to be used for producing alarms and notifications is the
Notification Service of the Service AvailabilityTM Forum (abbreviated as NTF, see [2]),
and hence the various notifications are partitioned into categories as described in this
service.
20
In some cases, this specification uses the word “Unspecified” for values of attributes.
This means that the SA Forum has no specific recommendation on the setting, and
the vendor may set these attributes to whatever makes sense in the vendor’s context.
Such values are generally optional from the CCITT Recommendation X.733 perspec-
tive (see [6]). 25
6.1 Setting Common Attributes

The tables presented in Section 6.2 refer to attributes defined in [2]. The following list
provides recommendations regarding how to populate these attributes. 30
• Correlation ids - They are supplied to correlate two notifications that have been
generated because of a related cause. This attribute is optional. But in case of
alarms that are generated to clear certain conditions, that is, produced with a
perceived severity of SA_NTF_SEVERITY_CLEARED, the correlation id shall be
populated by the application with the notification id that was generated by the 35
Notification Service when the saNtfNotificationSend() API was invoked
to issued the actual alarm.
• Event time - The application might pass a timestamp or optionally pass an
SA_TIME_UNKNOWN value in which case the timestamp is provided by the Notifi-
cation Service. 40

• NCI id - The notification class identifier is an attribute of type SaNtfClassIdT. 1

The vendorId portion of the SaNtfClassIdT data structure must be set to
SA_NTF_VENDOR_ID_SAF always. The majorId and minorId will vary based
on the specific SA Forum service and the particular notification. Every SA Forum
service shall have a majorId as described in the enumeration 5
SaNtfSafServicesT of the Notification Service specification.
• Notification id - This attribute is obtained from the Notification Service when a
notification is generated, and hence need not be populated by an application.
• Notifying object - DN of the entity generating the notification. This name must 10
conform to the SA Forum AIS naming convention and contain at least the
safApp RDN value portion of the DN set to the specified standard RDN value of
the SA Forum AIS Service generating the notification. For details on the SA
Forum AIS naming convention, refer to the SA Forum Overview document ([1]).
15
6.2 Checkpoint Service Notifications
The following describes a set of notifications that a Checkpoint Service implementa-
tion shall produce.
20
The notifying object must be set to the DN "safApp=safCkptService" for the
Checkpoint Service.
The value of the majorId field in the notification class identifier (SaNtfClassIdT)
must be set to SA_SVC_CKPT (as defined in the SaServicesT enum in [1]) in all 25
notifications generated by the Lock Service.
The minorId field within the notification class identifier (SaNtfClassIdT) is set dis-
tinctly for each individual notification. This field is range-bound, and the used ranges
are: 30
• Alarms: (0x01–0x64)
• State change notifications: (0x65–0xC8)
• Object change notifications: (0xC9–0x12C)
• Attribute change notifications: (0x12D–0x190) 35
6.2.1 Checkpoint Service Alarms

The Checkpoint Service does not issue any alarms at the time of publication of this
specification.
40

6.2.2 Checkpoint State Change Notifications 1
6.2.2.1 Checkpoint Section Resources Exhausted
Description 5
The maximum number of sections is reached, or no memory is left for write access. In
future, configuration parameters may be defined as a part of the Checkpoint Service
configuration that will control the generation of this notification.
10
Table 3 Checkpoint Section Resources Exhausted Notification
NTF Attribute Attribute Type (NTF-

SA Forum-Recommended Value
Name Recommended Value) 15
Event Type Mandatory SA_NTF_OBJECT_STATE_CHANGE
Notification Mandatory LDAP DN of the checkpoint that is full and not
Object available for write access.
Notification NTF-internal minorId = 0x65 20
Class Identifier
Additional Text Optional Unspecified
Additional Infor- Optional Unspecified 25
mation
Source Indicator Mandatory SA_NTF_OBJECT_OPERATION or
SA_NTF_UNKNOWN_OPERATION
Changed State Optional SA_CKPT_CHECKPOINT_STATUS 30
Attribute ID
Old Attribute Optional Unspecified
Value
New Attribute Mandatory SA_CKPT_SECTION_RESOURCES_EXHAUSTED 35
Value
40

6.2.2.2 Checkpoint Section Resources Available 1
Description
Memory is available for write access, or at least one section within the checkpoint is
5
available, after having recovered from a preceding
SA_CKPT_SECTION_RESOURCES_EXHAUSTED condition. This notification is gener-
ated only to indicate a recovery from an
SA_CKPT_SECTION_RESOURCES_EXHAUSTED condition and not otherwise. In
future, configuration parameters may be defined as a part of the Checkpoint Service
10
configuration that will control the generation of this notification.
Table 4 Checkpoint Section Resources Available Notification

15
NTF Attribute Attribute Type (NTF-
SA Forum-Recommended Value
Name Recommended Value)
Event Type Mandatory SA_NTF_OBJECT_STATE_CHANGE

Notification Mandatory LDAP DN of the checkpoint which is available 20
Object for write access.
Notification NTF internal minorId = 0x66
Class Identifier
Additional Text Optional Unspecified 25
Additional Infor- Optional Unspecified
mation
Source Indicator Mandatory SA_NTF_OBJECT_OPERATION or
SA_NTF_UNKNOWN_OPERATION 30
Changed State Optional SA_CKPT_CHECKPOINT_STATUS

Attribute ID
Old Attribute Optional SA_CKPT_SECTION_RESOURCES_EXHAUSTED
Value 35
New Attribute Mandatory SA_CKPT_SECTION_RESOURCES_AVAILABLE

Value
40

Management Interface
7 Checkpoint Service Management Interface 1
Currently, an SNMP MIB interface is defined for the Checkpoint Service. Other man-
agement access methods to the Checkpoint Service may be added in future versions
of this specification. 5
7.1 Checkpoint Service MIB (SAF-CKPT-SVC-MIB)

The Checkpoint Service MIB contains two read-only tables,
saCkptCheckpointTable and saCkptNodeReplicaLocTable. 10
The saCkptCheckpointTable contains runtime attributes for the currently created

checkpoints in the cluster, which include all checkpoints in the cluster that have not
been unlinked as well as the ones that have been unlinked but are still in-use within
the cluster. 15
This table mimics the UML runtime object class saCkptCheckpoint, as described
in Section 4.2, in terms of the objects contained in the table.
The saCkptNodeReplicaLocTable shows on which nodes a particular checkpoint

has replicas. 20
This table mimics the UML runtime object class SaCkptReplica, as described in
Section 4.2, in terms of the objects contained in the table.
Additionally, the Checkpoint Service MIB also defines SNMP traps that correspond to
the various notifications for the service, which are described in Chapter 6 of this spec- 25
ification.
For a detailed description of the various objects of this MIB, refer to the
SAF-CKPT-SVC-MIB that can be downloaded from
http://www.saforum.org/specification/download/get_spec. 30
35
40

Management Interface
10
15
20
25
30
35
40

Index of Definitions
Index of Definitions 1
A
active replica 17
asynchronous update option 17
C 5
checkpoint replicas see replicas
checkpoints
see also sections, replicas
definition 15
asynchronous update option 17
collocated 18 10
non-collocated 19
partial update option 18
retention duration 15
synchronization 17
synchronous update option 17
collocated checkpoint 18
E 15
expiration time 16
L
local replica 16
N
non-collocated checkpoints 19
P 20
partial update option 18
R
replicas 16
see also checkpoints
definition 16
active 17 25
local 16
retention duration 15
S
section identifier 15, 25
section identifier descriptor 25
sections
see also checkpoints 30
definition 15
expiration time 16
identifier 15
identifier descriptor 25
synchronization 17
synchronous update option 17
35
40

Sai Ais CKPT B.02.02

Uploaded by

Copyright:

Available Formats

Sai Ais CKPT B.02.02

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Sai Ais CKPT B.02.02

Uploaded by

Copyright:

Available Formats

Service AvailabilityTM Forum

Application Interface Specification

Checkpoint Service SAI-AIS-CKPT-B.02.02

SERVICE AVAILABILITY™ FORUM SPECIFICATION LICENSE AGREEMENT 1

AIS Specification SAI-AIS-CKPT-B.02.02 3

4 SAI-AIS-CKPT-B.02.02 AIS Specification

Table of Contents Checkpoint Service 1

3 SA Checkpoint Service API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

AIS Specification SAI-AIS-CKPT-B.02.02 5

6 SAI-AIS-CKPT-B.02.02 AIS Specification

4.2 Checkpoint Service UML Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 1

5 Checkpoint Service Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

6 Checkpoint Service Alarms and Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 5

7 Checkpoint Service Management Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

AIS Specification SAI-AIS-CKPT-B.02.02 7

8 SAI-AIS-CKPT-B.02.02 AIS Specification

1.1 Document Purpose

Typically, the Service AvailabilityTM Forum Application Interface Specification will be

This section presents the changes of the current release, SAI-AIS-CKPT-B.02.02, 30

1.3.1 New Topics

AIS Specification SAI-AIS-CKPT-B.02.02 Section 1 9

1.3.3 Changes in Return Values of API Functions 15

Table 1 Changes in Return Values of API Functions

All API functions except saCkptFinalize() SA_AIS_ERR_UNAVAILABLE new

1.3.4 Removed Topics

10 SAI-AIS-CKTP-B.02.02 Section 1.3.2 AIS Specification

1.3.5 Other Changes

AIS Specification SAI-AIS-CKPT-B.02.02 Section 1.3.5 11

1.5 How to Provide Feedback on the Specification

1.6 How to Join the Service Availability™ Forum

1.7 Additional Information 25

1.7.1 Member Companies

12 SAI-AIS-CKTP-B.02.02 Section 1.5 AIS Specification

To avoid accumulation of unused checkpoints in the system, checkpoint replicas

AIS Specification SAI-AIS-CKPT-B.02.02 Section 2 13

14 SAI-AIS-CKPT-B.02.02 Section 2.1 AIS Specification

3 SA Checkpoint Service API 1

3.1 Checkpoint Service Model

To avoid the accumulation of unused checkpoints in the system, checkpoints have a 20

If a process terminates abnormally, the Checkpoint Service automatically closes all of

Within a checkpoint, each section is identified by a unique section identifier. Section

The maximum number of sections in a checkpoint is specified when the checkpoint is

AIS Specification SAI-AIS-CKPT-B.02.02 Section 3 15

3.1.3 Checkpoint Replica

3.1.4 Checkpoint Data Access

Requirements regarding the consistency of the various replicas associated to a par-

16 SAI-AIS-CKPT-B.02.02 Section 3.1.3 AIS Specification

To accommodate different trade-offs between checkpoint update performance and 1

3.1.5 Synchronous Update 5

AIS Specification SAI-AIS-CKPT-B.02.02 Section 3.1.5 17

saCkptCheckpointSynchronizeAsync() functions to propagate checkpoint 1

3.1.7 Management of Replicas for Collocated and Non-Collocated Checkpoints

3.1.7.1 Collocated Checkpoints

18 SAI-AIS-CKPT-B.02.02 Section 3.1.7 AIS Specification

The saCkptActiveReplicaSet() function can be used only for collocated check-

3.1.7.2 Non-Collocated Checkpoints

3.1.8 Persistence of Checkpoints

AIS Specification SAI-AIS-CKPT-B.02.02 Section 3.1.7.2 19

3.2 Unavailability of the Checkpoint Service API on a Non-Member Node 1