1. SAI-Overview-B.02.01 SA Forum Extended Training Materials Service Availability Interface Lesson 1

2. Copyright© 2006 Service Availability™ Forum, Inc 2 Contents  This lesson provides material that is common to all of the areas of the Application Interface Specification. In particular, it addresses: Naming Conventions Programming / Usage Model Library Lifecycle API Error Codes Memory Allocation and Deallocation Version Mechanism Track API Name Types and Object Names

3. Copyright© 2006 Service Availability™ Forum, Inc 3 Application Interface Specification  The Application Interface Specification (AIS) is a set of open standard interface specifications for high service availability in carrier-grade telecommunication systems and networks  It defines Application Program Interfaces (APIs) between the applications and the service availability middleware for: AIS Availability Management Framework AIS Services – Cluster Membership Service – Checkpoint Service – Event Service – Message Service – Lock Service – Log Service – Notification Service – Information Model Management Service

4. Copyright© 2006 Service Availability™ Forum, Inc 4 AIS Naming Conventions  The AIS is broken down into interface areas  An interface area consists of a set of self-contained APIs that can be provided as a single library with its associated header file(s)  Each interface area is assigned an interface area tag that identifies the functions pertaining to that area Amf Availability Management Framework ClmCluster Membership Service CkptCheckpoint Service EvtEvent Service MsgMessage Service LckLock Service LogLog Service NtfNotification Service ImmInformation Model Management Service

5. Copyright© 2006 Service Availability™ Forum, Inc 5 AIS Naming Conventions  Global Function Declarations sa (arguments) Interface area tag Name or abbreviation of object or service Name or abbreviation of action Tag for the function such as Async or Callback Example: saEvtChannelOpenAsync()  Global Variable Declarations sa Example: SaNameT saAmfComponentName

6. Copyright© 2006 Service Availability™ Forum, Inc 6 AIS Naming Conventions  Type Declarations typedef Sa T Example: typedef SaUint32T SaCkptHandleT  Macro Declarations #define SA_ _ Example: #define SA_EVT_HIGHEST_PRIORITY 0 The names of macros use only uppercase letters and the digits 0-9 They use underscores to separate words and improve readability

7. Copyright© 2006 Service Availability™ Forum, Inc 7 AIS Naming Conventions  Enumeration Type Declarations typedef enum { SA_ _ [= ],.... SA_ _ [= ] } ; Example: typedef enum { SA_CKPT_SECTION_VALID = 1, SA_CKPT_SECTION_CORRUPTED = 2 } SaCkptSectionStateT; The names of enumeration elements use only uppercase letters and the digits 0-9 They use underscores to separate words and improve readability

8. Copyright© 2006 Service Availability™ Forum, Inc 8 AIS Naming Conventions  Some Pre-Defined Types and Constants typedef SaUint64T SaSizeT Used to specify sizes of objects typedef SaUint64T SaOffsetT Used to specify offsets in data areas typedef SaInt64T SaTimeT Used to specify time values (nanoseconds granularity) Depending on the case, it can be interpreted as an absolute time or a time duration #define SA_TIME_UNKNOWN 0x8000000000000000 Unknown time value #define SA_TIME_BEGIN 0x0000000000000000 Smallest timestamp #define SA_TIME_END 0x7FFFFFFFFFFFFFFF Largest timestamp #define SA_TIME_MAX Interpreted as an infinite duration

9. Copyright© 2006 Service Availability™ Forum, Inc 9 AIS Programming / Usage Model  The AIS specifies the interface between a process (uni-threaded or multi-threaded) and a library that implements the interface  The term process, as used in the AIS, can be regarded as being equivalent to a process defined by the POSIX standard  The term area server is used to represent the server that provides services for a specification area (Amf, Clm, Ckpt, Msg, etc) P rivate Interface UML Diagram Availability Management Framework Package Server for Service Communication method unspecified - could be remote or local Internal (Private) Interface communication Application Interface Implementation Library Designed to accommodate unthreaded process model -can be used with threaded -process model as well SA Forum Application Interface Process

10. Copyright© 2006 Service Availability™ Forum, Inc 10 AIS Programming / Usage Model  The area implementation libraries may be implemented in one or several physical libraries However, a process is required to initialize, register and obtain an operating system selection object separately for each area implementation library Thus, from a programming standpoint, it is useful to view these libraries as separate libraries  It is expected that the area server and the area implementation library are packaged together and are designed to be released as a set; however, this does not preclude other packaging options  The area server and the area implementation library may reside on the same or different computers

11. Copyright© 2006 Service Availability™ Forum, Inc 11 AIS Programming / Usage Model  The AIS employs both the synchronous and the asynchronous programming models The synchronous model is generally easier for programmers to understand and use However, there are applications where the number of simultaneous outstanding requests precludes having an independent thread of execution for each request Moreover, some applications require direct control of scheduling within a process To support such applications, some of the APIs of the AIS are based on the asynchronous model

12. Copyright© 2006 Service Availability™ Forum, Inc 12 AIS Library Lifecycle API for Areas  sa Initialize() function SaAisErrorT sa Initialize( /* OUT */Sa HandleT * Handle, /* IN */ const Sa CallbacksT * Callbacks, /* IN/OUT */ SaVersionT *version);  Initializes the area service for the invoking process and registers the callbacks whose function pointers are provided in * Callbacks  Any API call, including sa Dispatch(), can be called from any callback function  Supports several invocations of initialization functions per process and area  Returns Handle, which can be used in subsequent calls  As an input parameter, version indicates the version of the particular area service that the process requires. As an output parameter, the version actually supported by the particular area service is delivered

13. Copyright© 2006 Service Availability™ Forum, Inc 13 AIS Library Lifecycle API for Areas  sa Finalize() function SaAisErrorT sa Finalize( /* IN */ Sa HandleT Handle);  Closes the association, represented by the Handle parameter, between the invoking process and the area service  Releases resources, cancels pending callbacks, etc  A finalize call is needed for each area initialization

14. Copyright© 2006 Service Availability™ Forum, Inc 14 AIS Library Lifecycle API for Areas  sa SelectionObjectGet() function SaAisErrorT sa SelectionObjectGet( /* IN */ Sa HandleT Handle, /* OUT */ SaSelectionObjectT *selectionObject);  Obtains the operating system handle, selectionObject, associated with the handle Handle. This call is used to detect pending callbacks  With POSIX, the selection object is simply a file descriptor, provided by the operating system, and selectionObject is a pointer to the file descriptor  The selectionObject is valid until sa Finalize() is invoked on Handle

15. Copyright© 2006 Service Availability™ Forum, Inc 15 AIS Library Lifecyle API for Areas  sa Dispatch() function SaAisErrorT sa Dispatch( /* IN */ SaClmHandleT Handle, /* OUT */ SaDispatchFlagsT dispatchFlags);  The sa Dispatch() function invokes, in the context of the calling thread, pending callbacks for the handle, designated by Handle, as specified by the dispatchFlags parameter (see the next slide)  When the process detects, using a selection object, that invocations are pending for a callback function, and it is ready to process them, it calls the sa Dispatch() function

16. Copyright© 2006 Service Availability™ Forum, Inc 16 AIS Dispatch Flags  SaDispatchFlagsT type SA_DISPATCH_ONE Invokes a single pending callback in the context of the calling thread, if there is a pending callback, and then returns from the dispatch SA_DISPATCH_ALL Invokes all of the pending callbacks in the context of the calling thread, if there are any pending callbacks, before returning from dispatch SA_DISPATCH_BLOCKING One or more threads calling dispatch remain within dispatch and execute callbacks as they become pending. The thread or threads do not return from dispatch until the corresponding finalize function is executed by one thread of the process

17. Copyright© 2006 Service Availability™ Forum, Inc 17 AIS Error Codes  Some of the Error Codes Defined by the AIS SA_AIS_ERR_LIBRARY An unexpected problem occurred in the library (such as corruption) SA_AIS_ERR_VERSION Version parameter is not compatible with the version of the implementation of the AMF or AIS Service SA_AIS_ERR_INIT A callback function required for the API was not supplied in a previous call of sa Initialize() SA_AIS_ERR_TIMEOUT An implementation-dependent timeout or the timeout specified in the API call occurred before the call could complete SA_AIS_ERR_INVALID_PARAM Parameter is not set correctly SA_AIS_ERR_NO_MEMORY Either the library or the provider of the service is out of memory and cannot provide the service SA_AIS_ERR_BUSY Resource is already in use

18. Copyright© 2006 Service Availability™ Forum, Inc 18 AIS Programming / Usage Model 1.The process within the component invokes the sa Initialize() function to provide a set of callbacks for use by the library in calling back the component 2.The sa Initialize() function returns an interface handle to the invoking process 3.The process invokes the sa SelectionObjectGet() function to obtain a selection object, which is an operating system dependent object, e.g., a file descriptor 4.The interface returns a selection object to the process, allowing the process to wait until an invocation to a callback function is pending for it 5.The process waits on the selection object Process Application Interface Implementation Library Server for Service Command sa Initialize() sa Dispatch() Invoke proper callback to perform Command Return Handle Return Selection Object sa SelectionObjectGet() wait complete sa Response() Wait on Selection Object Communication by private interface

19. Copyright© 2006 Service Availability™ Forum, Inc 19 AIS Programming / Usage Model 6.The area server sends a command over its "private" interface to the library 7.The library "awakes" the selection object, thereby awaking the process 8.The process invokes the sa Dispatch() function 9.The library invokes the appropriate callback function of the process corresponding to the command received from the area server. The callback function parameters inform the process of the specific details of the command issued by the area server or the information provided by the area server 10.Once the process completes processing the callback, it responds by invoking a function of the area interface. In some cases, more than one response invocation, or no response, is necessary Process Application Interface Implementation Library Server for Service Command sa Initialize() sa Dispatch() Invoke proper callback to perform Command Return Handle Return Selection Object sa SelectionObjectGet() wait complete sa Response() Wait on Selection Object Communication by private interface

20. Copyright© 2006 Service Availability™ Forum, Inc 20 AIS in a POSIX Environment  AIS functions must be thread-safe, so that they can be invoked concurrently by different threads of a process  Async-signal safety (invocation from a signal handler) is not required for AIS functions  Rules to be observed by an application programmer Avoid using any AIS function within a signal handler Do not assume that AIS functions are interruptible by signals Do not assume that AIS functions are thread cancellation points Do not assume that AIS functions are fork-safe – If a process using AIS functions forks a child process, that calls AIS functions, the child process should exec() a new program immediately after being forked; this new program can then use AIS functions

21. Copyright© 2006 Service Availability™ Forum, Inc 21 Memory Allocation and Deallocation  Rule 1: Memory dynamically allocated by one entity (service user or service area library) is deallocated by that same entity with the exception given in Rule 2  Rule 2: The area service library allocates the buffer and the service user deallocates the buffer in cases where It is difficult for the service user to predict how much memory will be needed and, thus, to provide a buffer of the appropriate size It results in excessive copying and, thus, adversely impacts performance Each area service providing a function that allocates memory for a service user must provide a function that the user can call to deallocate the allocated memory

22. Copyright© 2006 Service Availability™ Forum, Inc 22 Memory Allocation and Deallocation  Example Use of Rule 2: typedef struct{ char *buf; SaInt32T len; } SaXxxBufferT; SaAisErrorT saXxxReceive(SaXxxHandleT handle, SaXXXBufferT buffer); SaAisErrorT saXxxReceiveDataFree(SaXXXHandleT handle, void *buffer); SaXxx BufferT msg; SaInt32T myLen; msg.buf = NULL; error = saXxxReceive(handle, msg); if (error != SA_AIS_OK) {/* handle error */} if (msg.buf != NULL) { /* process message */ myLen = msg.len; /* area service sets length */ process_message(msg.buf, myLen); saXxxReceiveDataFree(handle, msg.buf); msg.buf = NULL; };

23. Copyright© 2006 Service Availability™ Forum, Inc 23 AIS Version Mechanism  SaVersionT structure SaUint8T releaseCode  A single ASCII capital letter [A-Z]  All specifications and implementations with the same releaseCode are backward compatible  Infrequent changes are expected SaUint8T majorVersion  A number in the range [01..255]  An area implementation with a given majorVersion complies to the specification bearing the same releaseCode and majorVersion  New majorVersion numbers are expected at most once or twice a year for the first few years, becoming less frequent as time goes on SaUint8T minorVersion  A number in the range [01..255]  Successive updates of an area implementation, complying to an area interface specification bearing the same releaseCode and majorVersion, have increasing minorVersion numbers, which are used to indicate enhancements like better performance or bug fixes  Different values of the minorVersion must not impact compatibility, and are not used to check whether required and supported versions are compatible

24. Copyright© 2006 Service Availability™ Forum, Inc 24 Version Parameter for Initialize  sa Initialize() in the case that the implementation supports the required releaseCode and a major version >= the required majorVersion SA_AIS_OK is returned by sa Initialize() The version parameter is set by sa Initialize() to: – releaseCode = Required release code – majorVersion = Greatest value of the major version that this implementation can support for the required releaseCode – minorVersion = Greatest value of the minor version that this implementation can support for the required value of releaseCode and the returned value of majorVersion

25. Copyright© 2006 Service Availability™ Forum, Inc 25 Version Parameter for Initialize  sa Initialize() in the case that the implementation does not support the required releaseCode or a major version >= the required majorVersion SA_AIS_ERR_VERSION is returned by sa Initialize() The version parameter is set by sa Initialize() to: if (implementation supports the required releaseCode) releaseCode = required releaseCode else { if (implementation supports releaseCode greater than the required releaseCode) releaseCode = the least value of the supported release codes that is greater than the required releaseCode else releaseCode = the greatest value of the supported release codes that is less than the required releaseCode } majorVersion = greatest value of the major versions that this implementation can support for the returned releaseCode minorVersion = greatest value of the minor versions that this implementation can support for the returned values of releaseCode and majorVersion

26. Copyright© 2006 Service Availability™ Forum, Inc 26 Backward Compatibility  To achieve backward compatibility with the AIS B.02.01 specification in the future, the SA Forum will follow the rules below A function / type definition never changes for a given release Changes in a function / type definition (adding a new argument to a function or adding a new field to a data structure) force the definition of a new function / type name – A new function/type name is constructed from the original name in AIS B.02.01 with a suffix indicating the version where the function / type changed, as, for example, in saAmfComponentRegister_3() – Exception: New enum or flag values can be added to an existing enum or flag typedef without changing the type name as long as the size of the enum or flag typedef does not change – AIS implementers must ensure that they respect the version numbers provided by the application when it initializes the library and do not expose new enum values to applications using older versions

27. Copyright© 2006 Service Availability™ Forum, Inc 27 AIS Track API  Some area services provide groups of entities and allow the applications to track those groups as the groups change dynamically Example: Nodes joining or leaving a cluster (i.e., a group of nodes)  Similar functionality for tracking in different area services Start tracking an object (a group) Callback notification about an object change Stop tracking an object  Format: sa Track[ ]() denotes the area service denotes the tracked object denotes one of the track functions  A tracked object is identified by an area service handle and an object name The object name is omitted if the object can be identified by only the area service handle Thus, the objectName parameter is marked “if needed” in the APIs

28. Copyright© 2006 Service Availability™ Forum, Inc 28 AIS Track Flags SA_TRACK_CURRENT Information about all entities in the group is returned immediately, either in a notification buffer as indicated by the caller, or by a single subsequent notification callback SA_TRACK_CHANGES The notification callback is invoked each time at least one change occurs in the membership of the group or one attribute of at least one entity in the group changes. Information about all entities (both entities for which a change occurred and entities for which no change occurred) is passed to the notification SA_TRACK_CHANGES_ONLY The notification callback is invoked each time at least one change occurs in the membership of the group or one attribute of at least one entity in the group changes. Only information about entities that changed is passed in the notification callback

29. Copyright© 2006 Service Availability™ Forum, Inc 29 AIS Track Functions SaAisErrorT sa Track( /* IN */ Sa HandleT Handle, /* IN */ SaNameT *objectName, /* if needed */ /* IN */ SaUin8T trackFlags, /* IN/OUT */ Sa NotificationBufferT *notificationBuffer);  Tracks the object in a way determined by the trackFlags parameter  If the flag SA_TRACK_CURRENT is set in the trackFlags parameter, initial status information of the tracked object is retrieved. If the notificationBuffer parameter is not NULL, this information is passed in the given buffer; otherwise, it is passed asynchronously via the callback notification API NotificationBuffer: typedef struct{ /* Optional fields specific to the service */ SaUint32T numberOfItems; Sa NotificationT *items; } Sa NotificationBufferT;  If items is NULL, the area service will allocate the buffer, and it is the responsibility of the calling process to free it  Status changes of the tracked object are always passed asynchronously through the callback notification API; however, if only the SA_TRACK_CURRENT is sent in the trackFlags parameter, a one-time status request is made. No subsequent status changes are notified, unless they have been requested in a preceding sa Track() call

30. Copyright© 2006 Service Availability™ Forum, Inc 30 AIS Track Functions typedef void (*Sa TrackCallbackT)( /* IN */ SaNameT *objectName, /* if needed */ /* IN */ Sa NotificationBufferT *notificationBuffer, /* IN */ SaUint32T numberOfMembers, /* IN */ SaErrorT error);  The notificationBuffer contains the information of the tracked object according to the trackFlags parameter in the sa Track() call. The notificationBuffer is allocated by the area service, and it cannot be accessed outside the callback routine  The numberOfMembers parameter contains the number of members in the group represented by the tracked object SaAisErrorT sa TrackStop( /* IN */ Sa HandleT Handle, /* IN */ SaNameT *objectName /* if needed */);  Stops tracking an object. No more callback notifications about object status changes will be sent to the process  This call is needed only if there was a preceding invocation to sa Track() that used SA_TRACK_CHANGES or SA_TRACK_CHANGES_ONLY

31. Copyright© 2006 Service Availability™ Forum, Inc 31 AIS Name Type  The SaNameT type represents object names in AIS APIs  It allows for both human readable and other representations Human readable representations include ASCII and multi-byte character representations such as UTF-8  SaNameT structure #define SA_MAX_NAME_LENGTH 256 typedef struct { SaUint16T length; SaUint8T value[SA_MAX_NAME_LENGTH]; } SaNameT;

32. Copyright© 2006 Service Availability™ Forum, Inc 32 AIS Name Type  In the SaNameT structure, the length field refers to the number of octets (bytes) used by the representation of the name in the name field  If the C character string representation is used, The value field contains the characters in the string without the terminating null character The length field contains the number of those characters  SaNameT example usage SaNameT myName; myName.length = strlen(“fred”); memcpy(myName.value, “fred”, myName.length); error = saXxxCreateObject(myName, yyy, zzz);

33. Copyright© 2006 Service Availability™ Forum, Inc 33 AIS Object Names  AIS runtime APIs use LDAP Distinguished Names (DNs) to name objects These LDAP DNs follow UTF-8 encoding conventions described in IETF RFC 2253 (http://www.ietf.org/rfc/rfc2253.txt)http://www.ietf.org/rfc/rfc2253.txt The scope of these names is limited to a cluster. Hence, the names do not include a Relative Distinguished Name (RDN) that identifies the cluster Multi-valued RDNs are not supported LDAP names are encoded in SaNameT by using its UTF-8 representation without a terminating null character  The Information Model and System Management APIs also use LDAP DNs to name objects

34. Copyright© 2006 Service Availability™ Forum, Inc 34 AIS Object Names  Relative Distinguished Names for the AIS Services  Format: safApp = saf Service[: ] where saf Service has the values defined in the table below is a string used to differentiate multiple implementations of the same service AIS Service safApp Availability Management Framework safAmfService Cluster Membership Service safCkptService Checkpoint Service safClmService Event Service safEvtService Message Service safMsgService Lock Service safLckService Notification Service safNtfService Log Service safLogService Information Model Management Service safImmService

35. Copyright© 2006 Service Availability™ Forum, Inc 35 Summary  In this lesson you have learned about the following topics that provide the basis of the Application Interface Specification Naming Conventions Programming/Usage Model Library Lifecycle API Error Codes Memory Allocation and Deallocation Version Mechanism Track API Name Types and Object Names