Halnxamfa Um1

Advanced High Availability Software
Release 3.0 (RM05) for Linux

Application Management Framework
User’s Manual
October 2002 Edition

Application Management Framework User’s Manual
Table of Contents
1. Introduction ......................................................................................................................... 5
1.1. Hardware.......................................................................................................................... 5
1.2. Operating Systems ........................................................................................................... 5
1.3. Audience .......................................................................................................................... 5
1.4. Conventions ..................................................................................................................... 5
1.5. Terms/Acronyms.............................................................................................................. 6
1.6. Definitions........................................................................................................................ 7
2. Framework Overview.......................................................................................................... 8
2.1. Components ..................................................................................................................... 8
2.2. General Description ......................................................................................................... 8
2.2.1. High Level Architectures ........................................................................................ 10
3. Application Management Framework Components.......................................................... 13
3.1. Application Manager...................................................................................................... 13
3.2. Application Manager Configuration .............................................................................. 13
3.2.1. CatalogFile: ............................................................................................................. 13
3.2.2. ConnIDFile:............................................................................................................. 13
3.2.3. Foreground: ............................................................................................................. 14
3.2.4. HbPeriod: ................................................................................................................ 14
3.2.5. KeyFile: ................................................................................................................... 14
3.2.6. MaxHbMisses: ........................................................................................................ 14
3.2.7. MessageLogCount:.................................................................................................. 15
3.2.8. MessageLogFile: ..................................................................................................... 15
3.2.9. MessageLogFreq: .................................................................................................... 15
3.2.10. MessageLogSize: ................................................................................................. 16
3.2.11. SysMessageLevel:................................................................................................ 16
3.2.12. SysMessageOutput:.............................................................................................. 16
3.3. Application Agent(s)...................................................................................................... 17
3.4. Application Agent Configuration................................................................................... 17
3.4.1. CatalogFile: ............................................................................................................. 17
3.4.2. Foreground: ............................................................................................................. 18
3.4.3. MessageLogCount:.................................................................................................. 18
3.4.4. MessageLogFile: ..................................................................................................... 18
3.4.5. MessageLogFreq: .................................................................................................... 18
3.4.6. MessageLogSize:..................................................................................................... 19
3.4.7. SysMessageLevel: ................................................................................................... 19
3.4.8. SysMessageOutput: ................................................................................................. 19
3.5. Application Management Command Line Utility.......................................................... 20
3.6. Commands ..................................................................................................................... 21
3.6.1. Application Start ("app_start") ................................................................................ 21
3.6.2. Application Terminate ("app_terminate") ............................................................... 21
3.6.3. Attribute Get ("attr_get")......................................................................................... 22
Version 0.4 UNCONTROLLED COPY WHEN PRINTED 1/67

3.6.4. Attribute Set ("attr_set").......................................................................................... 22

3.6.5. Application Restart ("app_restart") ......................................................................... 22
3.6.6. Application Suspend ("app_suspend") .................................................................... 22
3.6.7. Application Online ("app_online").......................................................................... 22
3.7. Reference Managed Application Object ........................................................................ 22
3.7.1. Reference Managed Application Object Attributes ................................................ 22
3.7.1.1. attach................................................................................................................. 22
3.7.1.2. change_me ........................................................................................................ 23
3.7.1.3. discs_address .................................................................................................... 23
3.7.1.4. exe_name .......................................................................................................... 23
3.7.1.5. exe_options....................................................................................................... 23
3.7.1.6. hb_misses.......................................................................................................... 24
3.7.1.7. hb_period .......................................................................................................... 24
3.7.1.8. hb_status ........................................................................................................... 24
3.7.1.9. ip_address ......................................................................................................... 24
3.7.1.10. parent ............................................................................................................... 25
3.7.1.11. process_id........................................................................................................ 25
3.7.1.12. stat_cpu............................................................................................................ 25
3.7.1.13. stat_mem ......................................................................................................... 25
3.7.1.14. stat_period ....................................................................................................... 26
3.7.1.15. version ............................................................................................................. 26
3.7.2. Reference Managed Application Object State ........................................................ 26
3.7.3. Reference Managed Application Object Actions .................................................... 26
3.8. Managed Application Messaging Library...................................................................... 27
3.8.1. MAML API Global Data......................................................................................... 27
3.8.2. Interfaces ................................................................................................................. 28
3.8.3. Error Handling......................................................................................................... 28
3.8.4. Limitations and Restrictions.................................................................................... 28
3.9. Usage Concepts.............................................................................................................. 28
3.9.1. Request Queuing ..................................................................................................... 28
3.9.2. Message Callbacks .................................................................................................. 29
3.9.3. Friendly Message Construction............................................................................... 29
3.10. MAML API................................................................................................................. 29
3.10.1. General Access Functions .................................................................................... 30
3.10.1.1. maml_Open() - Initialize MAML.................................................................... 30
3.10.1.2. maml_Close() - Uninitialize MAML .............................................................. 31
3.10.2. Message Callback Related Functions................................................................... 31
3.10.2.1. maml_ProcessMessage() - Process AMF message ......................................... 32
3.10.2.2. maml_RegAppTerminate() - Register callback for Application Terminate
message 32
3.10.2.3. maml_RegAttrGet() - Register callback for Attribute Get message................ 33
3.10.2.4. maml_RegAttrSet() - Register callback for Attribute Set message ................. 34
3.10.2.5. maml_RegAppRestart() - Register callback for Application Restart message 35
3.10.2.6. maml_RegAppOnline() - Register callback for Application Online message 36

3.10.2.7. maml_RegAppSuspend() - Register callback for Application Suspend message

37
3.10.2.8. maml_RegAppAwake() - Register callback for Application Awake message 38
3.10.2.9. maml_RegHeartbeat() - Register callback for Heartbeat message ................. 39
3.10.2.10. maml_RegAppPrematTerm() - Register callback for Application Premature
Termination message......................................................................................................... 40
3.10.2.11. maml_RegApmInfo() - Register callback for APM Information message.... 41
3.10.2.12. maml_RegRequestTimeoutCb() - Register callback for Request timeout. ... 42
3.10.3. Module Description: Friendly Message Construction Functions......................... 42
3.10.3.1. maml_CreateMsgAppTerminate() - Create Application Terminate message . 43
3.10.3.2. maml_CreateMsgAttrGet() - Create Attribute Get message ........................... 44
3.10.3.3. maml_CreateMsgAttrSet() - Create Attribute Set message............................. 45
3.10.3.4. maml_CreateMsgAppRestart() - Create Application Restart message ........... 46
3.10.3.5. maml_CreateMsgAppOnline() - Create Application Online message ............ 47
3.10.3.6. maml_CreateMsgAppSuspend() - Create Application Suspend message ....... 48
3.10.3.7. maml_CreateMsgAppAwake() - Create Application Awake message ............ 49
3.10.3.8. maml_CreateMsgHeartbeat() - Create Heartbeat message............................. 50
3.10.3.9. maml_CreateMsgAppPrematTerm() - Create Application Premature
Termination message......................................................................................................... 51
3.10.3.10. maml_CreateMsgApmInfo() - Create Apm Information message ................ 52
3.10.4. Message Sending Functions................................................................................. 53
3.10.4.1. maml_Send() - Send AMF message to destination ......................................... 53
3.10.4.2. maml_SendRequest() - Queue request message and send to destination........ 54
3.10.5. Module Description: Error Message Functions ................................................... 55
3.10.5.1. maml_MamlErr() - MAML API Error Message ............................................. 55
3.10.6. Module Description: Utility Functions and Macros............................................. 55
3.10.6.1. maml_SetSignal() - Set Signal Handler .......................................................... 55
3.10.6.2. maml_AllocMem() - Allocate Memory .......................................................... 56
3.10.6.3. MAML_IS_AMF_MESSAGE(Data).............................................................. 57
4. Information for AMF Compliant Applications ................................................................. 57
4.1.1. DISCS Connection ID ............................................................................................. 57
4.1.2. Sending Application Awake Request Upon Bootup ................................................ 57
4.1.3. AA Connection ID Determination........................................................................... 58
4.1.4. APM Address Connection ID Determination.......................................................... 58
4.1.5. User Object Location............................................................................................... 58
5. Messages and Their Meanings .......................................................................................... 58
5.1. Messages Created and Sent by an Application .............................................................. 58
5.2. Messages Received by an Application........................................................................... 59
6. Example Usage.................................................................................................................. 60
6.1. Application Startup ........................................................................................................ 60
.............................................................................................................................................. 61
6.2. Callback Registration and Message Processing............................................................. 61
6.3. Callback Behavior.......................................................................................................... 63

Table of Figures
FIGURE 1-HIGH LEVEL ARCHITECTURE #1 (BM MONITORING LOCAL APPS) ......... 11
FIGURE 3-HIGH LEVEL ARCHITECTURE #2 (CM MONITORING ALL APPS IN
CHASSIS)............................................................................................................................. 12
Table of Tables
TABLE 1-RMAO STATE TABLE............................................................................................. 26
TABLE 3-REFERENCE MANAGED APPLICATION OBJECT ACTIONS TABLE............. 27

1. Introduction
Motorola Computer Group (MCG) is producing Advanced High Availability (AHA) systems.
All essential pieces of the hardware can be duplicated to provide redundancy. Most of the active
and passive hardware is packaged into removable objects. The operator may add or remove
objects while the AHA system is running.
The Application Management Framework provides the Event Manager a mechanism of starting,
stopping, and otherwise managing customer applications. The Application Management
Framework software is part of the SCEM software package and is closely integrated with the
Event Manager.
1.1. Hardware
An MXP system is a chassis containing removable objects. A typical system would have system
control boards, a pair of alarm cards, a pair of IP switches, a pair of Fibre Channel switches, and
several payload boards.
From the perspective of Application Management, the only hardware required is a board or
boards capable of running PPC/Intel Linux with an IP presence.
1.2. Operating Systems

The Application Management Framework software will execute on the current or latest version
of the stable Linux kernel. For Intel based systems, a commercially available Linux installation
is suggested. For PowerPC based systems, a Linux PowerPC Project installation is suggested.
1.3. Audience
This document contains information on Motorola Computer Group’s Application Management
Framework software. The information in this document is written for original equipment
manufacturers (OEMs), programmers, and system integrators with an expert knowledge of C
programming and Motorola’s high availability architecture.
1.4. Conventions
The following typographical conventions are used in this document:
bold
is used for user input that you type just as it appears; it is also used for commands,
options and arguments to commands, and names of programs, directories and files.
italic
is used for names of variables to which you assign values. Italic is also used for
comments in screen displays and examples, and to introduce new terms.
courier

is used for system output (for example, screen displays, reports), examples, and system
prompts.
<Enter>, <Return> or <CR>

represents the carriage return or Enter key.
Ctrl
represents the Control key. Execute control characters by pressing the Ctrl key and the
letter simultaneously, for example Ctrl-d.
1.5. Terms/Acronyms
Terms/Acronyms Meaning
AA Application Agent
AMF Application Management Framework
AMCLU Application Management Command Line Utility
APM Application Manager
AHA Advanced High Availability
API Application Programmer Interface

CPS Checkpoint Services
DISCS Distributed Inter-system Communication Services
ED Event Director
EM Event Manager
HA High Availability
MAML Managed Application Messaging Library
MCG Motorola Computer Group
OS Linux Kernel
PC Task Processor or peripheral card
RMAO Reference Managed Application Object
SCEM System Configuration/Event Manager

1.6. Definitions
AMF Compliant Refers to an application that sends and interprets AMF messages,
and adheres to AMF conventions.
Application Customer application.
Attach Indicates that AMF must tie an already executing application to a

user object.
Attribute A named aspect of a component. When associated with a particular

component, the attribute has a value.
Board Manager An Event Manager responsible for hardware events and

applications local to the board on which it runs. It has no concept
of the chassis it is running in.
Chassis An enclosure holding the parts of a high availability system.
Chassis Manager An Event Manager responsible for chassis-related objects and

events.
Component Either an object or a device.
Component State The logical state of a component, generally determined from the
current disposition and required disposition attributes.
Current Disposition An attribute whose value is the current/actual disposition or

condition of an object or device.
Device The active part of an object
Event An indication of a change in the system configuration, e.g. a device

fault was detected, a device offline request, etc.
Legacy Application Application that does not adhere to AMF conventions.
Method An executable program or shell script associated with a

component, e.g. configure method, un-configure method, change
method, Event Notification method, etc.
Object A replaceable part of the hardware or software of the system.
System Refers to entities participating in the Application Management

Framework. Consists of one EM, one APM, one or more AAs, one
AMCLU, zero or more legacy applications, and zero or more
applications utilizing MAML.
User An operator or system administrator who may make changes to the

system.

2. Framework Overview
The Application Management Framework (AMF) is intended to compliment the Event Manager
in further strengthening the EM’s role as the focal point of system management. AMF acts as a
bridge the between the EM and applications running in the system. AMF serves two main
purposes: Application Management and Application Monitoring.
Application Management concerns control and active interaction with applications. Specifically,
it involves starting and stopping of applications, application heartbeating, updating of various
application variables, and instructing applications to transition to different availability-related
states. Application Monitoring involves the periodic updating of statistics (both user-defined and
process related).
2.1. Components
The Application Management Framework consists of the following elements:

• Application Manager (APM): Daemon process that runs locally to the Event Manager.
Responsibilities include heartbeating Application Agents, tracking active applications,
updating the Event Manager upon application changes, and relaying various messages
between different entities in the system.
• Application Agent (AA): Daemon process that runs locally to all managed
applications. Responsibilities include heartbeating AMF compliant applications,
forcible termination of processes, starting of processes, and relaying process-level
statistics.
• Application Management Command Line Utility (AMCLU): Utility that acts as an
interface into the AMF for use by the Event Manager. Responsibilities include making
requests to the APM, AA, and applications for the purposes of starting and stopping
applications, as well as changing and querying application related data.
• Managed Application Messaging Library (MAML): Library consisting of message
formatting, parsing, timeout, callback, and other routines that allow applications to
communicate in the Application Management Framework.
2.2. General Description

As previously stated, the AMF is intended to provide a standard way in which the Event Manager
can manage applications through calls in its actions and methods.
A system utilizing the Application Management Framework consists of the following elements:
• An Event Manager
• A single APM local to the EM
• A single AMCLU local to the EM/APM

• One or more AAs with each being local to managed applications

• Applications utilizing MAML (AMF compliant)
• Legacy applications
• User objects residing in the Event Manager
All active entities in the system adhere to a standard AMF message format utilizing DISCS as the
transport mechanism.
The APM is the entity responsible for updating the Event Manager with application changes.
The APM provides information and notification to the Event Manager via the Event Manager
API library and receives messages from the AMCLU, AAs, and applications utilizing MAML.
Where the APM receives information from applications and updates the Event Mangager, the
AMCLU provides an interface for the Event Manager to affect the system and its applications.
Calls to the AMCLU are to be placed in actions and methods. When called, the AMCLU
generates messages to various entities in the system.
Each AA communicates with the APM and is responsible for process-related data and actions of
managed applications. The AA tracks applications utilizing MAML as well as legacy
applications.
AMF compliant applications utilize the MAML to assist in the formatting, sending and receiving
of messages over DISCS. The applications communicate directly with the APM, AAs, and
AMCLU. Legacy applications are defined as any application that is not "AMF compliant."
Legacy applications can only be started, monitored for process level statistics, and forcibly
terminated.
User objects residing in the Event Manager provide the standard interface for entities in the
system to interact with and change availability related state. The user objects representing
applications are supersets of the Reference Managed Application Object (RMAO). The RMAO
includes attributes required for proper integration into the framework.
Note that the APM locally interfaces with an Event Manager — either a Board Manager or
Chassis Manager. If one wished to represent applications running throughout the chassis in the
CM(s), one would execute an APM on each board containing a Chassis Manager (active/standby)
and have an AA running on each board requiring application management. In the case where one
would only like to model applications at the board level, ensure the APM resides on a board
containing a Board Manager and use the Event Director to coordinate objects at the sub- and
inter-chassis levels.

2.2.1. High Level Architectures

The following figures illustrate the two architectures of a system employing the various entities
in AHA. Figure 1 shows the configuration where one has the Board Managers managing local
applications, and Figure 2 shows the configuration where the CM is managing applications
across the chassis.

SNMP
Module B
Module A
(Any Chassis)
(Any Chassis)
Event Director
Event Director and all Event Director Sync Sync Agent
Chassis Mangers may Agent
communicate with Event Director
respective on-board (Standby)
SNMP agents. Event Director
(Active)
Active/Standby Event Directors
Module C (Any Chassis) Module D (Any Chassis)

Event Director Local Board
Client Resources Local Board
Event Director
Resources
Client
Chassis Manager
Chassis Manager
Sync Agent Chassis
Chassis
Manager
…
(Active) Manager Sync Agent
Other chassis
IPMI Subsystem (Standby)
IPMI managers,
Application Subsystem managed by
Manager Application Event Director,
Application Application
Agent connect in
Manager Agent identical
Managed Managed fashion.
Applications Applications
Typical Active/Standby Chassis Managers
Module E (Any Chassis)

Client Resources
Typical
Board Manager
…
Managed Other board
Board (Active)
managers,
managed by
Application Application Event Director
Manager Agent connect in
identical
Managed
Applications fashion.
Figure 1-High Level Architecture #1 (BM Monitoring Local Apps)

SNMP
Module B
Module A
(Any Chassis)
(Any Chassis)
Event Director
Event Director and all Event Director Sync Sync Agent
Chassis Mangers may Agent
communicate with Event Director
respective on-board (Standby)
SNMP agents. Event Director
(Active)
Active/Standby Event Directors
Module D
Module C (Any Chassis)
(Any Chassis)
Event Director Local Board Client Resources
Client Resources
Chassis
Chassis
Manager
…
Chassis Manager Manager Sync Agent Other chassis
Chassis Manager Sync Agent (Standby)
IPMI managers,
(Active)
Subsystem managed by
IPMI Subsystem Event Director,
Application Application connect in
Manager Agent identical
Application
Manager Application Managed fashion.
Agent Applications
Managed
Applications Typical Active/Standby Chassis Managers
Module E Module F
(Any Chassis)
Application
(Any Chassis)
Application
…
Agent Agent Other
Typical Application applications,
managed Boards managed by
Application
Local Board Resources Managed Managed Manager,
(other than applications) Applications Applications connect in
Managed by Customer identical fashion.
Figure 2-High Level Architecture #2 (CM Monitoring all Apps in Chassis)

3. Application Management Framework Components
3.1. Application Manager

The Application Manager updates the Event Manager with application state change information
and has the additional responsibility of AA heartbeating. The APM resides locally to the Event
Manager and is required to be executing before the Event Manager starts.
3.2. Application Manager Configuration

The Application Manager uses a config file to provide it with various run-time options and
parameters. This is an ASCII text file, which contains parameter definition lines and comment
lines. The default filename is /etc/scem/apm.cfg and may or may not need to be modified,
depending on your needs.
Comment lines are denoted by a ’#’ character in the first position. When comment lines are
detected, they will simply be ignored. Blank lines, i.e., lines with just a carriage return, will be
ignored as well.
Each configuration parameter will consist of two parts: the parameter keyword and the parameter
value, as follows:
<parameter keyword>: <parameter value>
All configuration parameters are optional, i.e., they are not mandatory and can be omitted from
the config file. The Application Manager will assume default values for the omitted parameters.
3.2.1. CatalogFile:
The CatalogFile parameter value specifies the Application Manager’s message catalog file
name/path. This file contains localizable natural-language messages used and logged by the
Application Manager. This file is generated by the gencat(1) utility with the associated message
file in /usr/lib/scem/messages.
The message catalog file normally used is /usr/lib/scem/catalogs/apm.cat and the associated
message file is /usr/lib/scem/messages/apm.msg.
Example:
CatalogFile: /usr/lib/scem/catalogs/apm.cat
The Application Manager default CatalogFile parameter value is set to NULL.
3.2.2. ConnIDFile:
The ConnIDFile parameter value specifies the Application Manager’s connection ID file
name/path. This file contains connection information used by entities wishing to communicate
with the APM (specifically, the AMCLU).

The connection ID file normally used is /var/scem/apm.con.
Example:
ConnIDFile: /var/scem/apm.con
The Application Manager default ConnIDFile parameter value is set to /var/scem/apm.con.
3.2.3. Foreground:
The Foreground parameter value specifies that when the Application Manager starts it should
remain either as a foreground process, via a parameter value of TRUE, or as a background
process, via a parameter value of FALSE.
Examples:
Foreground: FALSE
Foreground: TRUE
The Application Manager default Foreground parameter is set to FALSE.
3.2.4. HbPeriod:
The HbPeriod parameter value specifies the period of time to wait between AA heartbeats in
milliseconds.
Example:
HbPeriod: 200
The minimum value is 10 ms, max is 32767 ms with the default being 200 ms.
3.2.5. KeyFile:
The KeyFile parameter value specifies the Event Manager’s shared memory key file name/path.
The Event Manager writes its shared memory key to the shared memory key file. This file is also
used to lock the Event Manager shared memory segment, when accessing the information in it.
This is a simple ASCII text file, which contains the decimal value of the shared memory key.
Example:
KeyFile: /var/scem/em.key
The default is set to /var/scem/em.key.
3.2.6. MaxHbMisses:
The MaxHbMisses parameter value specifies the number of AA heartbeats to miss before
determining that a user object needs to be taken ‘offline’. If APM detects a heartbeat failure (that
is, the maximum number of heartbeat misses), then it will set hb_status to “failed” for all
applications registered through that AA.

Example:
MaxHbMisses: 5
The minimum value is 1, max is 32767, with the default being 5.
3.2.7. MessageLogCount:
The MessageLogCount parameter value specifies the number of Application Manager
message/status log files to be maintained during file rotation. The minimum number of files that
can be rotated is 1, with a maximum of 30. Each file is created by appending a number, e.g., .1,
.2, .3, etc. to the file name.
Note: This parameter is not used if message/status log file rotation frequency is 0.
Example:
MessageLogCount: 1
The Application Manager default MessageLogCount parameter is set to 0, i.e., to not rotate.
3.2.8. MessageLogFile:
The MessageLogFile parameter value specifies the Application Manager’s message/status log
file name/path. The Application Manager will log messages (error, debug, info, etc.) and its
status to this message/status log file.
This is a simple ASCII text file, with each message or status having a time/date prefix.
Example:
MessageLogFile:/var/scem/apm.log
The Application Manager default MessageLogFile parameter is set to /var/scem/apm.log.
3.2.9. MessageLogFreq:
The MessageLogFreq parameter value specifies the frequency in days of message/status log file
rotation. The minimum number of days that can be specified is 1, with a maximum of 90.
A parameter value of 1 indicates that the message/status log file should be rotated every day. A
value of 2 indicates it should be rotated every other day. A value of 3 indicates every third day
and so on.
Note: This parameter is not used if message/status log count is 0.
Example:
MessageLogFreq: 1
The Application Manager default MessageLogFreq parameter is set to 0, i.e., to not rotate.

3.2.10. MessageLogSize:
The MessageLogSize parameter value specifies the maximum size of the message/status log file.
The parameter value is hexadecimal, with a minimum value of 0x00001000 and a maximum
value of 0x7fffffff. When the size of the file reaches the parameter value, the Application
Manager will rewind to the beginning of the file.
Example:
MessageLogSize: 0x1000
The Application Manager default MessageLogSize parameter is set to unlimited size.
3.2.11. SysMessageLevel:
The SysMessageLevel parameter value specifies the message logging level to be used by the
Application Manager when logging system messages. For example, if the message logging level
was set to "information messages," then the Application Manager would log information level
messages and higher to the specified system message log. For example, a value of 3 for
SysMessageLevel enables logging of information, error, and critical messages. The possible
parameter values, indicating the message logging level, are:
0 (no messages)
1 (critical messages)
2 (error messages)
3 (information messages)
4 (debug messages)
Example:
SysMessageLevel: 3
The Application Manager default SysMessageLevel parameter is set to 3.
3.2.12. SysMessageOutput:
The SysMessageOutput parameter value specifies the system message log to be used by the
Application Manager when logging system messages. This allows the user some flexibility when
the Application Manager logs system messages. The possible parameter values, indicating the
system message log, are:
0x0 (no output)

0x1 (output to syslogd(8))
0x2 (output to stderr(3))
0x4 (output to Application Manager’s message/status log file)
0x7 (output to all)
Example:
SysMessageOutput: 0x4

The Application Manager default SysMessageOutput parameter is set to 0x2.
3.3. Application Agent(s)

Application Agents are responsible for starting, forcibly terminating, and heartbeating
applications. AAs are also responsible for relaying process level statistics to the APM (and up to
the EM after that).
3.4. Application Agent Configuration

The Application Agent uses a config file to provide it with various run-time options and
parameters. This is an ASCII text file, which contains parameter definition lines and comment
lines. The default filename is /etc/scem/aa.cfg and may or may not need to be modified,
depending on your needs.
Comment lines are denoted by a ’#’ character in the first position. When comment lines are
detected, they will simply be ignored. Blank lines, i.e., lines with just a carriage return, will be
ignored as well.
Each configuration parameter will consist of two parts: the parameter keyword and the parameter
value, as follows:
<parameter keyword>: <parameter value>
All configuration parameters are optional, i.e., they are not mandatory and can be omitted from
the config file. The Application Agent will assume default values for those parameters that are
omitted.
3.4.1. CatalogFile:
The CatalogFile parameter value specifies the Application Agent’s message catalog file
name/path. This file contains localizable natural-language messages used and logged by the
Application Agent. This file is generated by the gencat(1) utility with the associated message file
in /usr/lib/scem/messages.
The message catalog file normally used is /usr/lib/scem/catalogs/aa.cat and the associated
message file is /usr/lib/scem/messages/aa.msg.
Example:
CatalogFile: /usr/lib/scem/catalogs/aa.cat
The Application Agent default CatalogFile parameter value is set to NULL.

3.4.2. Foreground:
The Foreground parameter value specifies that when the Application Agent starts it should
remain either as a foreground process, via a parameter value of TRUE, or as a background
process, via a parameter value of FALSE.
Examples:
Foreground: FALSE
Foreground: TRUE
The Application Agent default Foreground parameter is set to FALSE.
3.4.3. MessageLogCount:
The MessageLogCount parameter value specifies the number of Application Agent
message/status log files to be maintained during file rotation. The minimum number of files that
can be rotated is 1, with a maximum of 30. Each file is created by appending a number, e.g., .1,
.2, .3, etc. to the file name.
Note: This parameter is not used if message/status log file rotation frequency is 0.
Example:
MessageLogCount: 1
The Application Agent default parameter is set to 0, i.e., to not rotate.
3.4.4. MessageLogFile:
The MessageLogFile parameter value specifies the Application Agent’s message/status log file
name/path. The Application Agent will log messages (error, debug, info, etc.) and its status to
this message/status log file.
This is a simple ASCII text file, with each message or status having a time/date prefix.
Example:
MessageLogFile:/var/scem/aa.log
The Application Agent default MessageLogFile parameter is set to /var/scem/aa.log.
3.4.5. MessageLogFreq:
The MessageLogFreq parameter value specifies the frequency in days of message/status log file
rotation. The minimum number of days that can be specified is 1, with a maximum of 90.
A parameter value of 1 indicates that the message/status log file should be rotated every day. A
value of 2 indicates it should be rotated every other day. A value of 3 indicates every third day
and so on.
Note: This parameter is not used if message/status log count is 0.

Example:
MessageLogFreq: 1
The Application Agent default MessageLogFreq parameter is set to 0, i.e., to not rotate.
3.4.6. MessageLogSize:
The MessageLogSize parameter value specifies the maximum size of the message/status log file.
The parameter value is hexadecimal, with a minimum value is 0x00001000 and a maximum
value of 0x7fffffff. When the size of the file reaches the parameter value, the Application Agent
will rewind to the beginning of the file.
Example:
MessageLogSize: 0x1000
The Application Agent default MessageLogSize parameter is set to unlimited size.
3.4.7. SysMessageLevel:
The SysMessageLevel parameter value specifies the message logging level to be used by the
Application Agent when logging system messages. For example, if the message logging level
was set to "information messages," then the Application Agent would log information level
messages and higher to the specified system message log. For example, a value of 3 for
SysMessageLevel enables logging of information, error, and critical messages. The possible
parameter values, indicating the message logging level, are:
0 (no messages)
1 (critical messages)
2 (error messages)
3 (information messages)
4 (debug messages)
Example:
SysMessageLevel: 3
The Application Agent default SysMessageLevel parameter is set to 3.
3.4.8. SysMessageOutput:
The SysMessageOutput parameter value specifies the system message log to be used by the
Application Agent when logging system messages. This allows the user some flexibility when
the Application Agent logs system messages. The possible parameter values, indicating the
system message log, are:
0x0 (no output)

0x1 (output to syslogd(8))
0x2 (output to stderr(3))

0x4 (output to Application Agent’s message/status log file)

0x7 (output to all)
Example:
SysMessageOutput: 0x4
The Application Agent default SysMessageOutput parameter is set to 0x2.
3.5. Application Management Command Line Utility

The AMCLU acts as the interface for the Event Manager to interact with managed applications.
Upon execution, the AMCLU interprets various command line arguments and generates a
message. This message is sent to the appropriate entity in the AMF (the APM, an AA, or a
managed application). Calls to the AMCLU are contained in the methods and actions of user
objects.
The AMCLU is primarily intended to be called from a user object (have the EM drive state
changes). It is up to the user to keep user object state coordinated with the actual application
state. For instance, one COULD execute an "app_suspend" command outside of the user object -
this would cause the managed application to suspend itself, but the user object would remain in
whatever state it originally was in. Thus the two entities would be 'out of sync' — not something
one typically wants to do. Also note that not all of the possible AMCLU commands ("attr_get",
"attr_set", and "app_restart") are present in the RMAO, and it is up to the user to determine
where to place these calls.
The following is taken from the man page of the AMCLU and describes command line options
and return codes.
Synopsis
amclu -c app_start -o <ObjName> [-f <KeyFile>] [-i <ConnIdFile>]
[-t <ReqTimeout>]
amclu -c app_terminate -o <ObjName> [-F] [-f <KeyFile>]
[-i <ConnIdFile>] [-t <ReqTimeout>]
amclu -c attr_get -o <ObjName> -a <AttrName> [-e] [-f <KeyFile>]
amclu -c attr_set -o <ObjName> -a <AttrName> [-f <KeyFile>]
-v <AttrValue> [-i <ConnIdFile>] [-t <ReqTimeout>]
amclu -c app_restart -o <ObjName> [-f <KeyFile>]
amclu -c app_online -o <ObjName> [-f <KeyFile>] [-i <ConnIdFile>]
[-t <ReqTimeout>]
amclu -c app_suspend -o <ObjName> [-f <KeyFile>]
amclu -h
Options
-a <AttrName> Attribute name, string
-c <Command> Command

"app_start" - Application Start

"app_terminate" - Application
Terminate
"attr_get" - Attribute Get
"attr_set" - Attribute Set
"app_restart" - Application Restart
"app_online" - Application Online
"app_suspend" - Application Suspend
-D Debug on
-e Update the EM
with the results of the get
-f <KeyFile> EM shared memory key file
-F Make termination
request forcible
-h Display this message
-i <ConnIdFile> APM connection ID file
-o <ObjName> Object name, string
-t <ReqTimeout> Request timeout in ms, decimal number (1-32767)
-v <AttrValue> Attribute value, string
3.6. Commands
The following sections describe the various commands the AMCLU accepts.
3.6.1. Application Start ("app_start")

This command is used to start or attach to applications. When executed, this command will
cause the AMCLU to extract various pieces of information from the specified object, and pass
them to the APM/AA for spawning/attachment.
3.6.2. Application Terminate ("app_terminate")

This command is used to terminate applications, either forcibly (specifying '-F') or with
application consent. A forcible termination involves the AA sending the application the signal
SIGKILL.
Termination with application consent works one of two ways, depending on what type of
application is being terminated (AMF-compliant or legacy). For AMF-compliant applications,
the application will be passed an Application Terminate message (see the MAML API
maml_RegAppTerminate()). For legacy applications (determined by attribute "hb_misses" equal
to 0), the application will be sent a SIGTERM signal. Since it is impossible for the AMF to
determine how long a legacy application normally takes to shutdown, this operation always
succeeds. It is up to the user to wait an appropriate amount of time and attempt a forcible
termination to ensure proper application shutdown. Before attempting a forcible shutdown, one
can determine if the application has terminated by investigating the "req_disposition" or
"change_me" attributes - the APM sets these to "offline" and "yes" respectively, when the AA
detects premature termination.

3.6.3. Attribute Get ("attr_get")

This command is used to retrieve an attribute value from an application. The attributes queried
can be either a process statistic ("stat_cpu", "stat_mem") or an application-specific attribute.
Process statistics can be gathered from both AMF-compliant and legacy applications. Normally,
the results of the get are displayed to stdout. One may use the '-e' option to update the attribute in
the user object as well.
3.6.4. Attribute Set ("attr_set")

This command is used to set an attribute in an application. This operation can either alter AA
behavior ("stat_period", "hb_period") or set an application-specific attribute.
3.6.5. Application Restart ("app_restart")

This command is used to restart an AMF-compliant application. The application will be passed
an Application Restart message (see the MAML API maml_RegAppRestart()).
3.6.6. Application Suspend ("app_suspend")

This command is used to command an AMF-compliant application to suspend itself. The
application will be passed an Application Suspend message (see the MAML API
maml_RegAppSuspend()).
3.6.7. Application Online ("app_online")

This command is used to command an AMF-compliant application to go online. The application
will be passed an Application Online message (see the MAML API maml_RegAppOnline()).
3.7. Reference Managed Application Object

A Reference Managed Application Object (RMAO) is provided for the customer to build upon
and provides a standard way in which the Application Management Framework is to be used by
the Event Manager. Additionally, the Application Manager's default message processing
behavior is closely tied to the RMAO in that upon receiving certain messages, the APM alters
various attributes of the RMAO. Therefore, it is important that any application object wishing
to utilize AMF be a superset of the RMAO. The RMAO also contains default
rules/actions/methods intended to drive it through various states and take certain actions
involving calls to the AMCLU.
3.7.1. Reference Managed Application Object Attributes

In addition to the standard fields included in all components, RMAO contains several attributes
that closely tie it with the AMF framework. The following sections describe those attributes,
indicate if the user is responsible for populating a field before instructing the AMCLU to start the
application, and if the APM is responsible for altering it. Note: Integer fields are represented as
null terminated strings in the actual RMAO definition.
3.7.1.1. attach
Type: String

Values: "yes", "no"

User Populate Before AMCLU Start: Yes
APM Alters: No
This attribute indicates if an application needs to be spawned or 'attached' to. If one wanted an
application to be started outside of the Event Manager's control and then wanted to have the
Event Manager manage that application at a later time, one would set this attribute to "yes". If
one wished the Event Manager to spawn the application, set this attribute to "no".
3.7.1.2. change_me
Type: String
Values: "yes", "no"
APM Alters: No
This attribute is part of the standard component attribute list and will be set to "no" if no faults
are present in the particular application. When an application terminates without the EM
instructing it to do so, this attribute is set to a value of "yes" - either the AA detects this
termination in the process of gathering statistics, or an AMF-compliant application informs the
framework of its impending termination.
3.7.1.3. discs_address
Type: String
Values: Any
User Populate Before AMCLU Start: No
APM Alters: Yes
This attribute contains the DISCS connection path of the application on the network. This value
is filled in by the APM upon successfully spawning/attaching to an application as well as when
the APM transitions from a standby to an active role.
3.7.1.4. exe_name
Type: String
Values: Any
APM Alters: No
This attribute contains the executable name of the application including the path. When
'attaching' to an application, only the basename will be considered, so ensure that if one wishes to
attach to applications, that the executable name is unique on the system. Note this does not mean
that one can only have a single instance of a process utilizing a given executable.
3.7.1.5. exe_options
Type: String

Values: Any
APM Alters: No
This attribute contains the executable options that will be used when spawning an application.
This attribute is ignored when attaching to an application.
3.7.1.6. hb_misses
Type: Integer
Values: 0..32767
APM Alters: No
This attribute contains the number of missed heartbeats before the "hb_status" attribute is
changed to "failed". If this value is 0, indicates a legacy application.
3.7.1.7. hb_period
Type: Integer
Values: 100..32767
APM Alters: No
This attribute contains the heartbeat period of the application. A heartbeat is sent every
"hb_period" ms from the AA to the specified application. See "hb_misses" and "hb_status" for
further information on application heartbeating.
3.7.1.8. hb_status
Type: String
Values: "invalid", "valid", "failed"
User Populate Before AMCLU Start: Yes (Initialize to "invalid")
APM Alters: Yes
This attribute indicates the current state of the application heartbeat. Initially, the value should
be set to "invalid". When the application has been successfully spawned or attached to,
"hb_status" is set to "valid". When the number of missed heartbeats exceeds "hb_misses",
"hb_status" transitions to "failed".
3.7.1.9. ip_address
Type: String
Values: Any
APM Alters: No

This attribute contains the IP address of the application. This can be the dotted numeric
representation or domain name. NOTE: For local applications to be managed in an
active/standby CM configuration, ensure that one uses an external interface address (not
'localhost' or 127.0.0.x) to ensure proper failover.
3.7.1.10. parent
Type: String
Values: Any
APM Alters: No
This attribute is intended to contain the parent board name. It is provided merely as a
convenience to the user.
3.7.1.11. process_id
Type: String
Values: 1..32767
User Populate Before AMCLU Start No
APM Alters: Yes
This attribute contains the process ID of the application and is filled in by the APM upon
successfully spawning/attaching to an application. It is provided merely as a convenience to the
user.
3.7.1.12. stat_cpu
Type: String
Values: 0..100
APM Alters: Yes
This attribute contains the CPU utilization of the application and is expressed as a whole number
percentage. This value is updated every "stat_period" seconds. It is calculated in roughly the
same manner that the Unix utility 'top' performs the calculation. The value is equal to amount of
processor time taken by the process since the last "stat_cpu" update divided by "stat_period".
3.7.1.13. stat_mem
Type: String
Values: 0..32767
APM Alters: Yes
This attribute contains memory utilization of the application and is expressed in 10's of kilobytes.
This value is updated every "stat_period" seconds. It is calculated by determining the total
amount of memory currently being used by the application.

3.7.1.14. stat_period
Type: String
Values: 1..32767
APM Alters: No
This attribute contains the statistics relay period of the application. The "stat_cpu" and
"stat_mem" are updated every "stat_period" seconds by the APM.
3.7.1.15. version
Type: String
Values: Any
APM Alters: No
This optional attribute is intended to contain the version of the application. It is provided merely
as a convenience to the user.
3.7.2. Reference Managed Application Object State

The RMAO state transitions are represented in Table 1.
Required Disposition
offline online suspend
offline offline initializing initializing
Current online terminating online suspend
Disposition initializing offline online suspend
integrating unknown unknown unknown
terminating offline unknown unknown
suspend terminating initializing suspend
Table 1-RMAO State Table
3.7.3. Reference Managed Application Object Actions

Table 2 describes the default actions included in the RMAO. In the case of a BM or active CM,
methods make calls to the AMCLU before completing a state transition. In the case of a standby
CM, methods complete state transitions with no AMCLU interaction.
State Transition Action

offline->initializing Call 'install' method (Instruct AMCLU to start application)
initializing->online Call 'configure' method (Instruct AMCLU to 'online' application)

online->terminating Call 'unconfigure' method (no default code in this method)
terminating->offline Call 'uninstall' method (Instruct APM to terminate application)
suspend->initializing No default action

suspend->terminating Call 'unconfigure' method (no default code in this method)

initializing->suspend Call 'configure' method (Instruct AMCLU to suspend application)
initializing->offline Call 'uninstall' method (Instruct APM to terminate application)
online->suspend Call 'configure' method (Instruct AMCLU to suspend application)
Table 2-Reference Managed Application Object Actions Table
3.8. Managed Application Messaging Library

MAML is the messaging library utilized by AMF-compliant applications. It is in the form of a
linkable shared library providing services to applications wishing to be managed by the Event
Manager via the AMF.
The MAML API provides services for applications wishing to be managed in an AHA system.
These services are implemented as simple function calls in a linkable shared library, i.e.,
libmaml.so.1.0.1. The MAML API provides services to handle standard messages sent from the
APM, AAs and AMCLU, as well as send messages adhering to the AMF message format
through the use of a DISCS connection, set request timeouts, and construct and verify AMF
messages.
3.8.1. MAML API Global Data

The following global variables are available to applications/utilities and are declared external in
the MAML API’s header file, <scem/maml.h>:
int maml_DebugFlag This variable is only available if the MAML API library has been
compiled with the DEBUG flag defined. If set to TRUE (1), debug statements contained in
the MAML API service functions will be sent to stdout. If set to FALSE (0), no output will
occur. It is initialized to FALSE.
int maml_ErrorCode This variable contains an error code for a MAML API service function
that returned an error, MAML_ERR (-1). It is set by the failing MAML API service function.
The possible error codes are defined in <scem/maml.h> as follows:
0x0001 (MAML_ERR_FUNC_PARAMS) - Invalid function parameters.

0x0002 (MAML_ERR_VAR_TOO_LONG) - Variable too long.
0x0003 (MAML_ERR_NODE_NOT_FOUND) - Request node not found error.
0x0004 (MAML_ERR_NO_MEMORY) - No memory available.
0x0005 (MAML_ERR_NO_VARIABLE) - No variable at index.
0x0006 (MAML_ERR_BAD_MESSAGE_FORMAT) - Bad message format.
0x0007 (MAML_ERR_REQUEST_ALREADY_QUEUED) - Request already queued.
0x0008 (MAML_ERR_CALLBACK_NOT_DEFINED) - Callback not defined.
0x0009 (MAML_ERR_VARIABLE_OUT_OF_RANGE) - Variable out of range.
0x000A (MAML_ERR_DISCS_REG) - DISCS registration error.
0x000B (MAML_ERR_DISCS_ALREADY_INITIALIZED) - DISCS already initialized.
0x000C (MAML_ERR_DISCS_SEND) - DISCS send error.

0x000D (MAML_ERR_NOT_AMF_MESSAGE) - Not a valid AMF message.

0x000E (MAML_ERR_DISCS_STATUS) - DISCS status error.
0x000F (MAML_ERR_SIGNAL_REGISTRATION_ERROR) - Signal handler registration
error.
0x0010 (MAML_ERR_SEM_CREATE) - Error creating semaphore.
0x0011 (MAML_ERR_SEM_REMOVAL) - Error removing semaphore.
0x0012 (MAML_ERR_BAD_SEMID) - Bad semaphore ID.
0x0013 (MAML_ERR_SEM_LOCK) - Error locking semaphore.
0x0014 (MAML_ERR_SEM_UNLOCK) - Error unlocking semaphore.
0x0015 (MAML_ERR_WRONG_MSG_FLAGS) - Message wasn't a request.
3.8.2. Interfaces
The function prototypes are defined in the MAML API header file, <scem/maml.h>.
3.8.3. Error Handling

The error conditions for the MAML API fall into two categories. The first type of errors are
those resulting from a deficiency of system resources, e.g., system call failing. The second type
of errors are those resulting from invalid data being passed to the MAML API by the caller or by
the MAML API not being in the proper state for the operation the caller is requesting. No matter
what type of error the MAML API encounters, an attempt will be made to return a meaningful
error code. Each function will return either 0 (defined as MAML_ERR_NONE in
<scem/maml.h>) if the operation was successful, or -1 (defined as MAML_ERR in
<scem/maml.h>) if the operation was unsuccessful. If unsuccessful, the MAML API error
variable maml_ErrorCode will be set to help identify the error. See Section 3.8.1.
3.8.4. Limitations and Restrictions

The request timeout processing utilizes the SIGALRM signal. If one wants to utilize timing
capabilities at a ms level, install the SIGALRM handler before calling maml_Open() (Doing so
afterward would trash MAML's request processing.) Approximately once every 100ms the
specified signal handler will be called along with other MAML related logic. Also, it is
important not to call functions that generate a SIGALRM (such as alarm(2) and
getitimer(2)) for these would interfere with MAML request processing.
Since DISCS is being used as the communication path between the MAML API and the other
entities in the AMF, any limitations and restrictions associated with DISCS apply as such.
3.9. Usage Concepts

MAML is provided to assist the end user in message generation, parsing, and sending of
messages. MAML is designed around several concepts described in the following sections.
3.9.1. Request Queuing

As previously described, messages can be considered requests, responses, or notifications.
Requests are expected to have a follow-up response sent from the destination of the request.
MAML includes the concept of request queuing to easily allow the user to handle the

request/response interaction. When sending a request, that request is tracked by an internal

MAML queue based upon sequence number. When a response arrives containing the same
sequence number as the outstanding request, the entry is removed from the queue. In the event
that a specified amount of time passes without a corresponding response arriving, a timeout will
occur and an optional user callback may be called.
APIs relevant to this functionality are:

Section 3.10.1.1 maml_Open() : Specifies request timeout
Section 3.10.2.1 maml_ProcessMessage(): Performs the dequeuing of outstanding requests
Section 3.10.2.12 maml_RegRequestTimeoutCB(): Used to register the callback when request
timeout occurs.
Section 3.10.4.2 maml_SendRequest(): Used to queue a request and send that request via DISCS
3.9.2. Message Callbacks

Message callbacks are utilized to provide a convenient way for the user to process messages
without having to explicitly extract information from the message. Each message type has a
corresponding callback, with the fields from the message being passed in as parameters to the
callback. Additionally, in the case of reception of a request message, one has the option of
allowing MAML to automatically send the corresponding response, after processing the callback.
Also, callbacks are used on the reception of both response messages and request messages. Note
that request de-queuing is independent of the definition of a callback (one could send a request
without ever being aware of the status of the response).
See Section 3.10.2 for relevant APIs.
3.9.3. Friendly Message Construction

To avoid the requirement that the user get involved in messaging details, several "Friendly"
message construction functions have been provided. These functions automatically create the
required message header and add the appropriate message fields. When generating requests and
delayed responses, the user will want to use these functions.
See Section 3.10.3 for relevant APIs.
3.10. MAML API

The various classes of functions being documented in this section are:
• General Access Functions (Section 3.10.1): Describes general access functions.
• Message Callback Related Functions (Section 3.10.2): Describes message callback related
functions.
• Friendly Message Construction Functions (Section 3.10.3): Describes friendly message
construction functions.
• Message Sending Functions (Section 3.10.4): Describes message sending functions.
• Error Message Functions (Section 3.10.5): Describes error message functions.
• Utility Functions and Macros (Section 3.10.6): Describes utility functions and macros.

3.10.1. General Access Functions

This module contains all the routines necessary to open or close access to the MAML.
The service functions described in this section are:

• MAML API Service Function maml_Open()
• MAML API Service Function maml_Close()
3.10.1.1. maml_Open() - Initialize MAML

The maml_Open() MAML API service function registers with DISCS and performs general
initialization.
#include <scem/maml.h>
int maml_Open(char *ConnID, char AssignConnID, int RequestTimeout, int

DiscsTimeout)
PARAMETERS
ConnID Pointer to DISCS connection ID to be used by MAML when auto-sending
messages. Depending on what AssignConnID is set to, ConnID will be
determined by MAML and set to the textual representation of the Process
ID1 or will be taken by MAML as the name to give the DISCS connection.
It is important NOT to register a local ConnID with '@' in the name, for
the maml_Send() function assumes that any ConnID with a '@' in it is on a
remote host.
AssignConnID Flag indicating if MAML should auto-determine (0) the name of the
DISCS connection, or take the value in ConnID as the DISCS connection
name (1).
RequestTimeout Timeout (in ms) used when sending requests to entities in the AMF. If 0,
MAML_DEF_RQST_TIMEOUT (2000) will be used. Otherwise , must
be greater than MAML_RQST_TIMER_PERIOD (100) and less than
AMF_MAX_RSP_TIMEOUT (32767).
DiscsTimeout Timeout (in s) used when registering with DISCS. If this value is 0, then
MAML_DEF_DISCS_TIMEOUT (2) will be used. Valid values are 0 to
0x7FFFFFFF.
DESCRIPTION
The maml_Open() service function is called by an application to initialize access to the MAML.
This involves registering the DISCS connection and initializing the request timer. See Section
3.8.4 for restrictions related to the MAML timer.
1
To maintain AMF compliance. See Section for 4.1.1 details.

RETURN VALUES
Upon successful completion, the maml_Open() MAML API service function returns a value of 0
(MAML_ERR_NONE). If the maml_Open() MAML API service function is unsuccessful, the
function will set the global MAML API error code, maml_ErrorCode, appropriately and return a
value of -1 (MAML_ERR).
3.10.1.2. maml_Close() - Uninitialize MAML

The maml_Close() MAML API service function deregisters with DISCS and performs general
cleanup.
int maml_Close()
PARAMETERS
None.
DESCRIPTION
The maml_Close() service function is called by an application or utility to uninitialize MAML.
RETURN VALUES
Upon successful completion, the maml_Close() MAML API service function returns a value of 0
(MAML_ERR_NONE). If the maml_Close() MAML API service function is unsuccessful, the
3.10.2. Message Callback Related Functions

This module contains all the routines necessary to register and call message callbacks. Callbacks
are utilized to provide a convenient way for the user to process messages without having to
explicitly extract information from the message. Each message type has a corresponding
callback, with the fields from the message being passed as parameters to the callback.
Additionally, in the case of reception of a request message, one has the option of allowing
MAML to automatically send the corresponding response, after processing the callback.

• MAML API Service Function maml_ProcessMessage()
• MAML API Service Function maml_RegAppTerminate()
• MAML API Service Function maml_RegAttrGet()
• MAML API Service Function maml_RegAttrSet()
• MAML API Service Function maml_RegAppRestart()
• MAML API Service Function maml_RegAppOnline()
• MAML API Service Function maml_RegAppSuspend()
• MAML API Service Function maml_RegAppAwake()

• MAML API Service Function maml_RegHeartbeat()

• MAML API Service Function maml_RegAppPrematTerm()
• MAML API Service Function maml_RegApmInfo()
• MAML API Service Function maml_RegRequestTimeoutCb()
3.10.2.1. maml_ProcessMessage() - Process AMF message
int maml_ProcessMessage(AMF_MSG *Message, char *SrcPath)
PARAMETERS
Message Pointer to AMF message to process.
SrcPath Pointer to DISCS source path, indicating what entity sent Message.
DESCRIPTION
The maml_ProcessMessage() service function is called by an application for the purposes of
processing a message it has determined to be an AMF message. This function will dequeue an
outstanding request, parse the message, call the appropriate callback function (if the user has
registered one), and possibly auto-generate and send a message response.
maml_ProcessMessage() is the heart of the message processing functionality of MAML and is
required to be in the DISCS message processing loop of a user application if one wants to utilize
message callback functions, response generation, and timeouts.
Note that responses will only be generated if one has registered a callback for a particular
message type. (The one exception to this rule is for the Heartbeat request which sends a response
message when no callback is defined, otherwise the callback/response generation behavior is
identical to that of other messages.)
RETURN VALUES
• Upon successful completion, the maml_ProcessMessage() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_ProcessMessage() MAML API
service function is unsuccessful, the function will set the global MAML API error code,
maml_ErrorCode, appropriately and return a value of -1 (MAML_ERR).
3.10.2.2. maml_RegAppTerminate() - Register callback for Application Terminate

message
int maml_RegAppTerminate(int (*Callback)(unsigned char, unsigned int, unsigned int *,

char *, char *, int *))

PARAMETERS
Callback Pointer to function to be called upon reception of an Application
Terminate message.
DESCRIPTION
The maml_RegAppTerminate() service function is called by an application to register a callback
to be called when processing an Application Terminate message. The callback will be called by
maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SeqNumber, unsigned
int *MsgReturnCode, char *ObjectName, char *Forcible, int *PID).
The parameters of the callback are defined as: Message Flags, Sequence Number, pointer to
Message Return Code, NULL terminated string containing Object Name, NULL terminated
string containing forcible flag, and pointer to ProcessID.
In the case of a request message, the return value of the callback (0 or 1) determines if a response
will be sent immediately. In the case of a response or notification message, the return value is
ignored. In the case that a response is to be generated, the passed in pointer parameters will be
used to generate the response message - one is intended to overwrite the buffer values passed in.
It is important when filling in character buffer values of the callback to not exceed
AMF_MAX_TEXT (900 characters including NULL), for this will overflow an internal buffer in
maml_ProcessMessage() and the system could become unstable.
Note that if you want to delay the follow-up response to a request and generate a response on
your own, return a value of '0' from the callback and use the friendly message generation
functions with the maml_Send() call.
USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK

One would register this callback to be notified when the Event Manager wishes the application to
terminate.
RETURN VALUES
Upon successful completion, the maml_RegAppTerminate() MAML API service function returns
a value of 0 (MAML_ERR_NONE). If the maml_RegAppTerminate() MAML API service
function is unsuccessful, the function will set the global MAML API error code,
3.10.2.3. maml_RegAttrGet() - Register callback for Attribute Get message
int maml_RegAttrGet(int (*Callback)(unsigned char, unsigned int, unsigned int *, char *,

char *))
PARAMETERS

Callback Pointer to function to be called upon reception of an Attribute Get

message.
DESCRIPTION
The maml_RegAttrGet() service function is called by an application to register a callback to be
called when processing an Attribute Get message.
The callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags,

unsigned int SeqNumber, unsigned int *MsgReturnCode, char *Name, char *Value).
Message Return Code, NULL terminated string containing Attribute Name, and NULL
terminated string containing Attribute Value.
Note that if you want to delay the follow-up response to a request and generate a request on your
own, return a value of '0' from the callback and use the friendly message generation functions
with the maml_Send() call.

One would register this callback if one wished to allow the Event Manager to periodically query
the application for attribute values.
RETURN VALUES
Upon successful completion, the maml_RegAttrGet() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_RegAttrGet() MAML API service function is
unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
3.10.2.4. maml_RegAttrSet() - Register callback for Attribute Set message
int maml_RegAttrSet(int (*Callback)(unsigned char, unsigned int, unsigned int *, char *,

char *))
PARAMETERS

Callback Pointer to function to be called upon reception of an Attribute Set

message.
DESCRIPTION
The maml_RegAttrSet() service function is called by an application to register a callback to be
called when processing an Attribute Set message.

unsigned int SeqNumber, unsigned int *MsgReturnCode, char *Name, char *Value).
Message Return Code, NULL terminated string containing Attribute Name, and NULL
terminated string containing Attribute Value.

One would register this callback if one wished to allow the Event Manager to periodically set
application attribute values. Additionally, it could be used when determining the outcome of
asynchronously updating the EM with application data (checking the Message Return Code of an
Attribute Get response).
RETURN VALUES
Upon successful completion, the maml_RegAttrSet() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_RegAttrSet() MAML API service function is
3.10.2.5. maml_RegAppRestart() - Register callback for Application Restart

message
int maml_RegAppRestart(int (*Callback)(unsigned char, unsigned int, unsigned int *))

PARAMETERS
Callback Pointer to function to be called upon reception of an Application Restart
message.
DESCRIPTION
The maml_RegAppRestart() service function is called by an application to register a callback to
be called when processing an Application Restart message.

unsigned int SeqNumber, unsigned int *MsgReturnCode).
The parameters of the callback are defined as: Message Flags, Sequence Number, and pointer to
Message Return Code.
Note that if you want to delay the follow-up response to a request, or generate a request on your

One would register this callback if one wished to allow the Event Manager to restart the
application.
RETURN VALUES
Upon successful completion, the maml_RegAppRestart() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_RegAppRestart() MAML API service function
is unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
3.10.2.6. maml_RegAppOnline() - Register callback for Application Online message
int maml_RegAppOnline(int (*Callback)(unsigned char, unsigned int, unsigned int *))
PARAMETERS
Callback Pointer to function to be called upon reception of an Application Online
message.
DESCRIPTION

The maml_RegAppOnline() service function is called by an application to register a callback to

be called when processing an Application Online message.


One would register this callback if one wished to allow the Event Manager to request the
application to go 'online'.
RETURN VALUES
Upon successful completion, the maml_RegAppOnline() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_RegAppOnline() MAML API service function
3.10.2.7. maml_RegAppSuspend() - Register callback for Application Suspend

message
int maml_RegAppSuspend(int (*Callback)(unsigned char, unsigned int, unsigned int *))
PARAMETERS
Callback Pointer to function to be called upon reception of an Application Suspend
message.
DESCRIPTION
The maml_RegAppSuspend() service function is called by an application to register a callback to
be called when processing an Application Suspend message.



One would register this callback if one wished to allow the Event Manager to request the
application to 'suspend'.
RETURN VALUES
Upon successful completion, the maml_RegAppSuspend() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_RegAppSuspend() MAML API service function
3.10.2.8. maml_RegAppAwake() - Register callback for Application Awake message
int maml_RegAppAwake(int (*Callback)(unsigned char, unsigned int, unsigned int *))
PARAMETERS
Callback Pointer to function to be called upon reception of an Application Awake
message.
DESCRIPTION
The maml_RegAppAwake() service function is called by an application to register a callback to
be called when processing an Application Awake message.



One would register this callback if one wished to determine the outcome of sending an
Application Awake request to the AA (by checking the message return code of the response
message).
RETURN VALUES
Upon successful completion, the maml_RegAppAwake() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_RegAppAwake() MAML API service function
3.10.2.9. maml_RegHeartbeat() - Register callback for Heartbeat message
int maml_RegHeartbeat(int (*Callback)(unsigned char, unsigned int, unsigned int *))
PARAMETERS
Callback Pointer to function to be called upon reception of a Heartbeat message.
DESCRIPTION
The maml_RegHeartbeat() service function is called by an application to register a callback to be
called when processing a Heartbeat message.

unsigned int SequenceNumber, unsigned int *MsgReturnCode).
Note that if you want to delay the follow-up response to a request and generate a response on
your own, return a value of '0' from the callback and use the friendly message generation
functions with the maml_Send() call.


One would register this callback if one wished to be alerted when a heartbeat request message
arrives.
RETURN VALUES
Upon successful completion, the maml_RegHeartbeat() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_RegHeartbeat() MAML API service function is
3.10.2.10. maml_RegAppPrematTerm() - Register callback for Application

Premature Termination message
int maml_RegAppPrematTerm(int (*Callback)(unsigned char, unsigned int, unsigned int *,

int *))
PARAMETERS
Callback Pointer to function to be called upon reception of an Application
Premature Termination message.
DESCRIPTION
The maml_RegAppPrematTerm() service function is called by an application to register a
callback to be called when processing an Application Premature Termination message.

unsigned int SeqNumber, unsigned int *MsgReturnCode, int *PID).
Message Return Code, and pointer to Process ID.

One would register this callback if one wished to determine the outcome of a previously sent
Application Premature Termination request (by checking the message return code of the
response message).
RETURN VALUES
Upon successful completion, the maml_RegAppPrematTerm () MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_RegAppPrematTerm () MAML API
3.10.2.11. maml_RegApmInfo() - Register callback for APM Information message
int maml_RegApmInfo(int (*Callback)(unsigned char, unsigned int, unsigned int *, char

*))
PARAMETERS
Callback Pointer to function to be called upon reception of an APM Information
message.
DESCRIPTION
The maml_RegApmInfo() service function is called by an application to register a callback to be
called when processing an APM Information message.

unsigned int SeqNumber, unsigned int *MsgReturnCode, char *DestPath).
Message Return Code, and pointer to Destination Path of APM.

One would register this callback to determine the DISCS address of the active APM.

RETURN VALUES
Upon successful completion, the maml_RegApmInfo() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_RegApmInfo() MAML API service function is
3.10.2.12. maml_RegRequestTimeoutCb() - Register callback for Request timeout.
int maml_RegRequestTimeoutCb(void (*Callback)(unsigned int, unsigned int, char *))
PARAMETERS
Callback Pointer to function to be called when a request has timed out.
DESCRIPTION
The maml_RegRequestTimeoutCb() service function is called by an application to register a
callback to be called when an outstanding request has timed out. The callback will be called by
the request timeout signal handler as (*Callback)(unsigned int SeqNumber, unsigned int
MsgType, char *DestPath). The parameters of the callback are defined as: Sequence Number,
Message Type, and a NULL terminated string containing Destination Path.
RETURN VALUES
Upon successful completion, the maml_RegRequestTimeoutCb() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_RegRequestTimeoutCb() MAML API
3.10.3. Module Description: Friendly Message Construction Functions

This module contains all the routines to construct the standard messages.

• MAML API Service Function maml_CreateMsgAppTerminate()
• MAML API Service Function maml_CreateMsgAttrGet()
• MAML API Service Function maml_CreateMsgAttrSet()
• MAML API Service Function maml_CreateMsgAppRestart()
• MAML API Service Function maml_CreateMsgAppOnline()
• MAML API Service Function maml_CreateMsgAppSuspend()
• MAML API Service Function maml_CreateMsgAppAwake()
• MAML API Service Function maml_CreateMsgHeartbeat()
• MAML API Service Function maml_CreateMsgAppPrematTerm()
• MAML API Service Function maml_CreateMsgApmInfo()

3.10.3.1. maml_CreateMsgAppTerminate() - Create Application Terminate message
int maml_CreateMsgAppTerminate(AMF_MSG *Message, unsigned char Flags, unsigned

int *SeqNumber, unsigned int MsgReturnCode, char *ObjectName, char *Forcible, int
PID)
PARAMETERS
Message Pointer to structure that will contain constructed message.
Flags Message flags. Valid values are:
0 (AMF_MSG_FLAGS_NONE) - No flags (Request message)
1 (AMF_MSG_FLAGS_RSP) - Response
SeqNumber Pointer to unsigned integer containing sequence number of message. If

equal to NULL or points to the value 0, sequence number is auto-
determined according to the AMF convention. Otherwise, message is
constructed using this value (must be no greater than
AMF_MAX_UINT_VAL). If SeqNumber was a pointer to 0, upon return,
SeqNumber points to the sequence number generated.
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
ObjectName Pointer to NULL terminated string containing the Object Name. The
maximum number of characters, including the NULL, is
AMF_MAX_NAME.
Forcible Pointer to NULL terminated string containing forcible flag. Must be equal
to "yes" or "no".
PID Integer containing process ID. Must be greater than zero and no greater
than AMF_MAX_INT_VAL.
DESCRIPTION
The maml_CreateMsgAppTerminate() service function is called by an application to construct an
Application Terminate message. Upon successful completion, the structure being pointed to by
the Message parameter will contain an Application Terminate message with the given fields.
This function calls a subroutine which blocks on a semaphore waiting for other calls to it to
complete. Therefore, this function is not recommended for use in signal handlers.


In the event that one wishes to delay the response upon reception of a request (through the use of
the return value of the message callback), one would call this function to create the response at
that later time and call maml_Send() afterward.
RETURN VALUES
• Upon successful completion, the maml_CreateMsgAppTerminate () MAML API service
function returns a value of 0 (MAML_ERR_NONE). If the
maml_CreateMsgAppTerminate() MAML API service function is unsuccessful, the function
will set the global MAML API error code, maml_ErrorCode, appropriately and return a value
of -1 (MAML_ERR).
3.10.3.2. maml_CreateMsgAttrGet() - Create Attribute Get message
int maml_CreateMsgAttrGet(AMF_MSG *Message, unsigned char Flags, unsigned int

*SeqNumber, unsigned int MsgReturnCode, char *Name, char *Value)
PARAMETERS

Name Pointer to NULL terminated string containing the attribute name. The
AMF_MAX_NAME.
Value Pointer to NULL terminated string containing the attribute value. The
AMF_MAX_NAME.

DESCRIPTION
The maml_CreateMsgAttrGet() service function is called by an application to construct an
Attribute Get message. Upon successful completion, the structure being pointed to by the
Message parameter will contain an Attribute Get message with the given fields. This function
calls a subroutine which blocks on a semaphore waiting for other calls to it to complete.
Therefore, this function is not recommended for use in signal handlers.

RETURN VALUES
• Upon successful completion, the maml_CreateMsgAttrGet() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgAttrGet() MAML API
3.10.3.3. maml_CreateMsgAttrSet() - Create Attribute Set message
int maml_CreateMsgAttrSet(AMF_MSG *Message, unsigned char Flags, unsigned int

*SeqNumber, unsigned int MsgReturnCode, char *Name, char *Value)
PARAMETERS


Name Pointer to NULL terminated string containing the attribute name. The
AMF_MAX_NAME.
Value Pointer to NULL terminated string containing the attribute value. The
AMF_MAX_NAME.
DESCRIPTION
The maml_CreateMsgAttrSet() service function is called by an application to construct an
Attribute Set message. Upon successful completion, the structure being pointed to by the
Message parameter will contain an Attribute Set message with the given fields. This function
calls a subroutine which blocks on a semaphore waiting for other calls to it to complete.

In the event that a state change occurs within the application that the Event Manager must be
notified of, this function would be used in conjunction with maml_SendRequest().
RETURN VALUES
• Upon successful completion, the maml_CreateMsgAttrSet() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgAttrSet() MAML API
3.10.3.4. maml_CreateMsgAppRestart() - Create Application Restart message
int maml_CreateMsgAppRestart(AMF_MSG *Message, unsigned char Flags, unsigned int

*SeqNumber, unsigned int MsgReturnCode)
PARAMETERS



DESCRIPTION
The maml_CreateMsgAppRestart() service function is called by an application to construct an
Application Restart message. Upon successful completion, the structure being pointed to by the
Message parameter will contain an Application Restart message with the given fields. This
function calls a subroutine which blocks on a semaphore waiting for other calls to it to complete.

RETURN VALUES
• Upon successful completion, the maml_CreateMsgAppRestart() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgAppRestart() MAML
API service function is unsuccessful, the function will set the global MAML API error code,
3.10.3.5. maml_CreateMsgAppOnline() - Create Application Online message
int maml_CreateMsgAppOnline(AMF_MSG *Message, unsigned char Flags, unsigned int

PARAMETERS



DESCRIPTION
The maml_CreateMsgAppOnline() service function is called by an application to construct an
Application Online message. Upon successful completion, the structure being pointed to by the
Message parameter will contain an Application Online message with the given fields. This

RETURN VALUES
• Upon successful completion, the maml_CreateMsgAppOnline() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgAppOnline() MAML
API service function is unsuccessful, the function will set the global MAML API error code,
3.10.3.6. maml_CreateMsgAppSuspend() - Create Application Suspend message
int maml_CreateMsgAppSuspend(AMF_MSG *Message, unsigned char Flags, unsigned

int *SeqNumber, unsigned int MsgReturnCode)
PARAMETERS



DESCRIPTION
The maml_CreateMsgAppSuspend() service function is called by an application to construct an
Application Suspend message. Upon successful completion, the structure being pointed to by
the Message parameter will contain an Application Suspend message with the given fields. This

RETURN VALUES
• Upon successful completion, the maml_CreateMsgAppSuspend() MAML API service
function returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgAppSuspend()
MAML API service function is unsuccessful, the function will set the global MAML API
error code, maml_ErrorCode, appropriately and return a value of -1 (MAML_ERR).
3.10.3.7. maml_CreateMsgAppAwake() - Create Application Awake message
int maml_CreateMsgAppAwake(AMF_MSG *Message, unsigned char Flags, unsigned int

PARAMETERS



DESCRIPTION
The maml_CreateMsgAppAwake() service function is called by an application to construct an
Application Awake message. Upon successful completion, the structure being pointed to by the
Message parameter will contain an Application Awake message with the given fields. This

Upon application startup, the managed application is required to inform it's local AA that it is up
and running, therefore this function would be used in conjunction with maml_SendRequest().
RETURN VALUES
• Upon successful completion, the maml_CreateMsgAppAwake () MAML API service
function returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgAppAwake()
MAML API service function is unsuccessful, the function will set the global MAML API
error code, maml_ErrorCode, appropriately and return a value of -1 (MAML_ERR).
3.10.3.8. maml_CreateMsgHeartbeat() - Create Heartbeat message
int maml_CreateMsgHeartbeat(AMF_MSG *Message, unsigned char Flags, unsigned int

PARAMETERS


DESCRIPTION
The maml_CreateMsgHeartbeat() service function is called by an application to construct a
Heartbeat message. Upon successful completion, the structure being pointed to by the Message
parameter will contain an Heartbeat message with the given fields. This function calls a
subroutine which blocks on a semaphore waiting for other calls to it to complete. Therefore, this
function is not recommended for use in signal handlers.

RETURN VALUES
• Upon successful completion, the maml_CreateMsgHeartbeat() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgHeartbeat() MAML API
3.10.3.9. maml_CreateMsgAppPrematTerm() - Create Application Premature

Termination message
int maml_ CreateMsgAppPrematTerm(AMF_MSG *Message, unsigned char Flags,

unsigned int *SeqNumber, unsigned int MsgReturnCode, int PID)
PARAMETERS


PID Integer containing process ID. Must be greater than zero and no greater
than AMF_MAX_INT_VAL.
DESCRIPTION
The maml_CreateMsgAppPreMatTerm() service function is called by an application to construct
an Application Premature Termination message. Upon successful completion, the structure
being pointed to by the Message parameter will contain an Application Premature Termination
message with the given fields. This function calls a subroutine which blocks on a semaphore
waiting for other calls to it to complete. Therefore, this function is not recommended for use in
signal handlers.

If an application determines that it must prematurely terminate (that is, termination is not
requested by AMCLU), the managed application is required to inform the APM of the fact before
terminating (if possible). This function should be used in conjunction with
maml_SendRequest().
RETURN VALUES
• Upon successful completion, the maml_CreateMsgAppPreMatTerm() MAML API service
function returns a value of 0 (MAML_ERR_NONE). If the
maml_CreateMsgAppPreMatTerm() MAML API service function is unsuccessful, the
function will set the global MAML API error code, maml_ErrorCode, appropriately and
return a value of -1 (MAML_ERR).
3.10.3.10. maml_CreateMsgApmInfo() - Create Apm Information message
int maml_ CreateMsgApmInfo(AMF_MSG *Message, unsigned char Flags, unsigned int

*SeqNumber, unsigned int MsgReturnCode, char *DestPath)
PARAMETERS


DestPath Pointer to NULL terminated string containing the destination path of

APM. The maximum number of characters, including the NULL, is
ISC_MAX_CONN_PATH.
DESCRIPTION
The maml_CreateMsgApmInfo() service function is called by an application to construct an
APM Information message. Upon successful completion, the structure being pointed to by the
Message parameter will contain an APM Information message with the given fields. This

RETURN VALUES
• Upon successful completion, the maml_CreateMsgApmInfo() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgApmInfo() MAML API
3.10.4. Message Sending Functions

This module contains all the routines necessary to lower level message construction/parsing and
sending of AMF messages.

• MAML API Service Function maml_Send()
• MAML API Service Function maml_SendRequest()
3.10.4.1. maml_Send() - Send AMF message to destination

int maml_Send(AMF_MSG *Message, char *DestPath)
PARAMETERS
Message Pointer to structure that contains message to have a variable added to it.
DestPath Specifies the DISCS destination path. The maximum number of

characters allowed for the DestPath, including the NULL, is defined as
ISC_MAX_CONN_PATH. The rules governing this variable are the same
as those outlined in ISC_Send().
DESCRIPTION
The maml_Send() service function is a simple wrapper for DISCS send. It auto-determines the
flags required for the ISC_Send(). Upon successful completion, the message has been
successfully sent to the local DISC SP.

When an application wishes to generate a response to a message, after earlier receiving the
request, this function would be used. This call should not be used in a message callback
function, rather allow the normal callback response generation to occur.
RETURN VALUES
Upon successful completion, the maml_Send() MAML API service function returns a value of 0
(MAML_ERR_NONE). If the maml_Send() MAML API service function is unsuccessful, the
3.10.4.2. maml_SendRequest() - Queue request message and send to

destination
int maml_SendRequest (AMF_MSG *Message, char *DestPath)
PARAMETERS
Message Pointer to structure that contains message to have a variable added to it.
DestPath Specifies the DISCS destination path. The maximum number of

characters allowed for the DestPath, including the NULL, is defined as
ISC_MAX_CONN_PATH. The rules governing this variable are the same
as those outlined in ISC_Send().
DESCRIPTION
The maml_SendRequest() service function pushes a message onto the request queue and sends
the message with a call to maml_Send().

RETURN VALUES
Upon successful completion, the maml_SendRequest() MAML API service function returns a
value of 0 (MAML_ERR_NONE). If the maml_SendRequest() MAML API service function is
3.10.5. Module Description: Error Message Functions

This module contains all the MAML API error message service functions

• MAML API Service Function maml_MamlErr()
3.10.5.1. maml_MamlErr() - MAML API Error Message
int maml_MamlErr(char **MamlStr, char **ErrNoStr)
PARAMETERS
MamlStr Pointer to an address to hold the NULL terminated error message text
string.
ErrNoStr Pointer to an address to hold the NULL terminated errno message text
string.
DESCRIPTION
The maml_MamlErr() service function is called by an application to return a message string that
corresponds to the global MAML API error code, maml_ErrorCode. If an errno(3) value is also
set, then an errno message string will also be returned.
RETURN VALUES
Upon successful completion, the maml_MamlErr() MAML API service function returns a value
of 0 (MAML_ERR_NONE). If the maml_MamlErr() MAML API service function is
3.10.6. Module Description: Utility Functions and Macros

This module contains all the MAML API utility functions used by the service functions
The utility functions and macros being documented are:
• Utility Function maml_SetSignal()
• Utility Function maml_AllocMem()
• Utility Macro MAML_IS_AMF_MESSAGE()
3.10.6.1. maml_SetSignal() - Set Signal Handler

int maml_SetSignal(int Signum, sighandler_t SigHandler, struct sigaction *OldSigPtr)
PARAMETERS
SigNum A signal number as defined in /usr/include/bits/signum.h.
SigHandler The new signal handler. If this is set to -1, then the old signal handler will
be restored.
OldSigPtr Pointer to the old signal handler.
DESCRIPTION
The maml_SetSignal() utility function is called by an MAML API service function to set a new
signal handler, or to restore an old signal handler, for a given signal.
RETURN VALUES
Upon successful completion, the maml_SetSignal() utility function returns a value of 0
(MAML_ERR_NONE). If the maml_SetSignal() utility function is unsuccessful, the function
will set the global MAML API error code, maml_ErrorCode, appropriately and return a value of -
1 (MAML_ERR).
3.10.6.2. maml_AllocMem() - Allocate Memory
int maml_AllocMem(int MemSize, char **MemPtr)
PARAMETERS
MemSize Requested memory size.
MemPtr Address of return memory pointer.
DESCRIPTION
The maml_AllocMem() utility function is called by an MAML API service function to allocate
memory for the given size and clear it. It will return the pointer to the allocated memory, via the
MemPtr parameter.
When this utility function is called, it will:

• Allocated memory, via a calloc(3) library call, for the size given in the MemSize
parameter.
• If the library call fails, then an error will be returned.

RETURN VALUES
Upon successful completion, the maml_AllocMem() utility function returns a value of 0
(MAML_ERR_NONE). If the maml_AllocMem() utility function is unsuccessful, the function
will set the global MAML API error code, maml_ErrorCode, appropriately and return a value of -
1 (MAML_ERR).
3.10.6.3. MAML_IS_AMF_MESSAGE(Data)
(int) MAML_IS_AMF_MESSAGE((void *)Data)
PARAMETERS
Data Pointer to buffer containing DISCS message
DESCRIPTION
The MAML_IS_AMF_MESSAGE() utility macro is called by an MAML API service function to
determine if the given data buffer is a valid AMF message.
RETURN VALUES
Upon exit, this macro evaluates to either a (1) if the buffer contains a valid message and a (0) if
the buffer does not contain a valid message.
4. Information for AMF Compliant Applications

In addition to using MAML, the AMF contains several conventions for managed applications to
be considered "AMF compliant." The following sections detail these conventions.
Note that the default rules, actions, and methods associated with Reference Managed Application
Objects assume an AMF-compliant application. If your application is compliant, you may need to
make changes to these files.
4.1.1. DISCS Connection ID

The DISCS connection ID of an application in the system MUST be equivalent to the textual
representation of the process ID. This is a required convention because the active elements in the
framework depend on this in order to properly identify the application. The MAML API
maml_Open() (section 3.10.1.1) includes the option to create a connection ID with this name as
well as register the connection.
4.1.2. Sending Application Awake Request Upon Bootup

Applications are required to generate an Application Awake request to the AA to indicate that
the application is ready to receive heartbeat. Without sending this message, the user object's
"hb_status" attribute will remain "invalid" and the AA will not attempt to heartbeat the
application. This heartbeat related behavior only pertains to spawned applications - the AA

initiates heartbeating and changes "hb_status" of attached applications immediately upon

attachment.
4.1.3. AA Connection ID Determination

All AAs register with Connection ID "AA". Thus, applications needing to communicate with
their local AA merely send to this Connection ID.
4.1.4. APM Address Connection ID Determination

The APM in the system has a unique connection ID that is determined when it boots up (it uses
the AMF convention of using its process ID). AMF compliant applications need to communicate
with the APM, thus they need to determine its connection ID.
If the application was started normally (not attached), upon sending the AA the Application
Awake request, the AA will send the application an Apm Information request containing the
system APM path. In the event the application is intended to be attached to, the AA will send the
Apm Information request upon successfully attaching to an application. If one is associating
managed applications with an Event Manager in an active/standby role (such as the Chassis
Manager), all applications will receive an Apm Information request when the standby Event
Manager assumes an active role.
4.1.5. User Object Location

Unlike its hardware counterparts, the location associated with a user object does not have to
equal to the slot number of the board on which the application being represented by the user
object resides. Using the slot number as the location becomes a problem when two or more
instances of the same user object reside on the same board. To solve this problem and alleviate
confusion, you must have a unigue location code for each user object. For convenience, you may
want to inlcude the slot number in the location code. For example, the second instance of an
application running in slot 3 might have a location code of 302; the first instance running in slot
14 could have a location code of 1401. This is simply a recommendation, for the AMF will work
with whatever location scheme the user sees fit.
5. Messages and Their Meanings

The MAML API is built around the reception and creation of various messages. The following
sections indicate how a managed application should concern itself with these messages.
5.1. Messages Created and Sent by an Application

Request messages are generated and sent by the application to alert the Event Manager of a
change in the application's state. The following describes the various requests an application
may want to create and their intended usage.
Message API used in creation Sent to Usage

(Request)
Attribute Set maml_CreateMsgAttrSet() APM Update the Event Manager

of a change in application
state (attribute must be
modeled in user object
representing application).
Application maml_CreateMsgAppPrematTerm() APM Indicates that application is
Premature terminating without being
Termination instructed to by the Event
Manager
Application maml_CreateMsgAppAwake() AA Indicates that application is
Awake up and running and ready to
start receiving AMF
messages
5.2. Messages Received by an Application

Entities within the AMF periodically send messages to managed applications, expecting the
application to perform certain behaviors upon message reception. Note that the response can be
sent immediately by usage of the callback, or sent at a later time. The following table details
these messages and their meaning.
Message API used to register callback Sent from Meaning

(Request)
Application maml_RegAppTerminate() AA Event Manager wishes to
Termination terminate the given
application.
Attribute Get maml_RegAttrGet() AMCLU Event Manager wishes to
retrieve the value of a given
attribute.
Attribute Set maml_RegAttrSet() AMCLU Event Manager wishes to set
the value of a given
attribute.
Application maml_RegAppRestart AMCLU Event Manager wishes
Restart application to restart itself.
Application maml_RegAppOnline AMCLU Event Manager wishes
Online application to go into an
'online' state.
Application maml_RegAppSuspend AMCLU Event Manager wishes
Suspend application to go into a
'suspend' state.
Heartbeat maml_RegHeartbeat AA Periodic heartbeat sent from
AA.
APM maml_RegApmInfo AA AA wishes to inform the
Information application of the APM
connection path.

6. Example Usage
The following sections detail several scenarios on how to use the MAML when developing a
managed application.
6.1. Application Startup

Upon application startup, one of the first things to do is open the MAML library. Additionally,
to adhere to the AMF, an Application Awake message must be sent to the local AA to indicate
that the application is ready to receive messages. The following example illustrates these.
#include <stdio.h>
#include <signal.h>
#include <scem/iscapi.h>
extern void TimingFn(int SigNum);
....
unsigned short RequestTimeout = 0; /* Use the default Timeout */

int DiscsTimeout = 2; /* 2 second DISCS timeout */
char ConnID[ISC_MAX_CONN_ID]; /* Connection ID */
char *MamlStr; /* MAML error string */

char *ErrNoStr; /* Errno string */
AMF_MSG AmfMsg; /* AMF Message */
/*
** Setup signal handler to be called by maml every 10 ms
*/
if(signal(SIGALRM, TimingFn) != SIG_ERR)

{
/*
** Error handling
*/
....
}
else
{
/*
** Open MAML and have it assign the connection ID
*/
if(maml_Open(ConnID, 0, RequestTimeout, DiscsTimeout) != MAML_ERR_NONE)
{
maml_MamlErr(&MamlStr, &ErrNoStr);
printf("Error in maml_Open:%s, ErrNoStr:%s\n", MamlStr, ErrNoStr);
}
else
{
/*
** Create and send the ’Application Awake’ message informing
** the local AA that we are up and running
*/

if(maml_CreateMsgAppAwake(&AmfMsg, AMF_MSG_FLAGS_NONE, NULL, 0)

== MAML_ERR_NONE)
{
if(maml_SendRequest(&AmfMsg, "AA") != MAML_ERR_NONE)
{
/*
** Error Handling
*/
}
}
else
{
/*
** Error Handling
*/
}
/*
** Continue normal processing
*/
....
}
}
....
6.2. Callback Registration and Message Processing

When one wishes to process incoming messages instructing the application to perform certain
behaviors (or examine the response of a previously sent request), callbacks corresponding to
certain messages must be registered. Additionally, one may register a function to be called when
a previously sent request has timed out. The following code illustrates registering several
callbacks and the message loop to accomplish this task:
#include <stdio.h>
#include <unistd.h>
#include <errno.h>
/*
** Prototypes
*/
extern int AppTerminateCB(unsigned char Flags, unsigned int SeqNumber,
unsigned int *MsgReturnCode, char *ObjectName, char *Forcible, int *PID);
extern int AppOnlineCB(unsigned char Flags, unsigned int SeqNumber, unsigned

int *MsgReturnCode);
extern int AppSuspendCB(unsigned char Flags, unsigned int SeqNumber, unsigned

extern int AppAwakeCB(unsigned char Flags, unsigned int SeqNumber, unsigned
extern void RqstTOCB(unsigned int SeqNumber, unsigned int MsgType, char
*DestPath);
/*
** Main message reception function

*/
void MessagingFn(void)
{
int DiscsTimeout = 0;
int Flags;
char Message[ISC_MAX_MSG_DATA];
char SrcPath[ISC_MAX_CONN_PATH];
char ConnID[ISC_MAX_CONN_ID];
char *MamlStr, *ErrNoStr;
if((maml_RegAppTerminate(AppTerminateCB) == MAML_ERR_NONE) &&

(maml_RegAppOnline(AppOnlineCB) == MAML_ERR_NONE) &&
(maml_RegAppSuspend(AppSuspendCB) == MAML_ERR_NONE) &&
(maml_RegAppAwake(AppAwakeCB) == MAML_ERR_NONE) &&
(maml_RegRequestTimeoutCb(RqstTOCB) == MAML_ERR_NONE))
{
/*
** Main message processing loop
*/
while(1)
{
/*
** Receive the ISCS Message
*/
DiscsTimeout = 0;
if(ISC_Recv(ConnID, Message, ISC_MAX_MSG_DATA,

SrcPath, &Flags, &DiscsTimeout) == -1)
{
if(errno == EAGAIN)
{
/*
** Indicates that a message is not in the queue so
** simply wait to get awoken by SIGURG (or any other
** signal for that matter)
*/
pause();
}
else
{
/*
** Error Handling
*/
....
}
}
else
{
if(MAML_IS_AMF_MESSAGE(Message))
{
/*
** It’s an AMF message so go ahead and
** process it
*/
if(maml_ProcessMessage((AMF_MSG *)Message, SrcPath)
!= MAML_ERR_NONE)
{
maml_MamlErr(&MamlStr, &ErrNoStr);

printf("maml_ProcessMessage():%s, ErrNoStr:%s\n",
MamlStr, ErrNoStr);
}
}
else
{
/*
** It’s a non-AMF message (custom message processing)
*/
....
}
}
}
}
else
{
/*
** Error Handling
*/
....
}
}
6.3. Callback Behavior

Message callbacks are executed upon the reception of both response and request messages. The
request timeout callback is executed upon timeout of a request message. The following code
snippets illustrate how this callback could be written.
Application Termination Callback with delayed response generation (possibly perform cleanup in
another thread then acknowledge going down)
#include <unistd.h>
unsigned int SN;

static int AppTerminateCB(unsigned char Flags, unsigned int SeqNumber,
unsigned int *MsgReturnCode, char *ObjectName,
char *Forcible, int *PID)
{
int ReturnCode = 0; /* By default, do not generate a response */
if(Flags & AMF_MSG_FLAGS_RSP)
{
/*
** Applications shouldn’t receive an
** ’Application Termination Response’ so just toss it.
*/
}
else
{
/*
** Application was instructed to terminate so let thread
** know that it’s time to go down (assuming pid matches)
*/
if(*PID == getpid())
{
/*
** Save the sequence number and unlock the semaphore on which

** the other thread is pending (not a

real fctn use your own)
*/
SN = SeqNumber;
SemReturn(MYSEM);
}
}
return(ReturnCode);
}
void Thread(void *arg)

{
AMF_MSG AmfMsg;
/*
** Block on semaphore (Not a real function, use your own)
*/
SemAcquire(MYSEM);
/*
** Shutdown logic here
*/
....
/*
** Finally the message creation with the send. NOTE that this uses
** maml_Send, NOT maml_SendRequest
*/
if(maml_CreateMsgAppTerminate(&AmfMsg, AMF_MSG_FLAGS_RSP, &SN, 0,
"App-1", "no", getpid()) == MAML_ERR_NONE)
{
if(maml_Send(&AmfMsg, "AA") != MAML_ERR_NONE)
{
/*
** Error Handling
*/
}
}
else
{
/*
** Error Handling
*/
}
}
Attribute Get Callback with auto response generation:

/*
** Prototype for name/value lookup
** Fills in the attribute value for a given named attribute. Returns
** a 0 if success, 1 if lookup failed.
*/
int RetrieveValue(char *Name, char *Value);

static int AttrGetCB(unsigned char Flags, unsigned int SeqNumber,
unsigned int *MsgReturnCode, char *Name, char *Value)

{
{
/*
** Managed apps shouldn’t receive this message so just toss it
*/
}
else
{
/*
** A request for an attribute - Retrieve the value for the
** specified name and fill in the message return code.
*/
*MsgReturnCode = RetrieveValue(Name, Value);
}
return(1);
}
APM Information Callback with auto response generation:

/*
** Path of current APM. Used for all sends to APM (at this
time
** only Attribute Set and Premature Termination Messages)
*/
char ApmPath[ISC_MAX_CONN_PATH] = {0};

static int ApmInfoCB(unsigned char Flags, unsigned int SeqNumber,
unsigned int *MsgReturnCode, char *DestPath)
{
{
/*
** Managed apps shouldn’t receive this message so just toss it
*/
}
else
{
/*
** An update of APM information
** Update the path and indicate all went well.
*/
strcpy(ApmPath, DestPath);
*MsgReturnCode = AMF_REQUEST_SUCCEEDED;
}
return(1);
}
Response Timeout Callback:

static void RqstTimeoutCB(unsigned int SeqNumber, unsigned int MsgType,
char *DestPath)
{
/*
** Log a message to stdout

*/
printf("Timeout on message SeqNumber:%d, Type:%d, DestPath:%s\n",
SeqNumber, MsgType, DestPath);
}

Halnxamfa Um1

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

Halnxamfa Um1

Uploaded by

Copyright:

Available Formats

Advanced High Availability Software

Release 3.0 (RM05) for Linux

October 2002 Edition

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 1/67

3.6.4. Attribute Set ("attr_set").......................................................................................... 22

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 2/67

3.10.2.7. maml_RegAppSuspend() - Register callback for Application Suspend message

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 3/67

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 4/67

1.2. Operating Systems

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 5/67

<Enter>, <Return> or <CR>

AMF Application Management Framework

AMCLU Application Management Command Line Utility

APM Application Manager

AHA Advanced High Availability

API Application Programmer Interface

DISCS Distributed Inter-system Communication Services

MAML Managed Application Messaging Library

MCG Motorola Computer Group

PC Task Processor or peripheral card

RMAO Reference Managed Application Object

SCEM System Configuration/Event Manager

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 6/67

Application Customer application.

Attach Indicates that AMF must tie an already executing application to a

Attribute A named aspect of a component. When associated with a particular

Board Manager An Event Manager responsible for hardware events and

Chassis An enclosure holding the parts of a high availability system.

Chassis Manager An Event Manager responsible for chassis-related objects and

Component Either an object or a device.

Current Disposition An attribute whose value is the current/actual disposition or

Device The active part of an object

Event An indication of a change in the system configuration, e.g. a device

Legacy Application Application that does not adhere to AMF conventions.

Method An executable program or shell script associated with a

Object A replaceable part of the hardware or software of the system.

System Refers to entities participating in the Application Management

User An operator or system administrator who may make changes to the

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 7/67

The Application Management Framework consists of the following elements:

2.2. General Description

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 8/67

• One or more AAs with each being local to managed applications

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 9/67

2.2.1. High Level Architectures

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 10/67

Module C (Any Chassis) Module D (Any Chassis)

Typical Active/Standby Chassis Managers

Module E (Any Chassis)

Figure 1-High Level Architecture #1 (BM Monitoring Local Apps)

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 11/67

Figure 2-High Level Architecture #2 (CM Monitoring all Apps in Chassis)

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 12/67

3. Application Management Framework Components

3.1. Application Manager

3.2. Application Manager Configuration

<parameter keyword>: <parameter value>

The Application Manager default CatalogFile parameter value is set to NULL.

Version 0.4 UNCONTROLLED COPY WHEN PRINTED 13/67

The connection ID file normally used is /var/scem/apm.con.

The Application Manager default ConnIDFile parameter value is set to /var/scem/apm.con.

The Application Manager default Foreground parameter is set to FALSE.