Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
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
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.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.
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
ED Event Director
EM Event Manager
HA High Availability
OS Linux Kernel
1.6. Definitions
AMF Compliant Refers to an application that sends and interprets AMF messages,
and adheres to AMF conventions.
Component State The logical state of a component, generally determined from the
current disposition and required disposition attributes.
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
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
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.
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
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
Board Manager
…
Managed Other board
Board (Active)
managers,
managed by
Application Application Event Director
Manager Agent connect in
identical
Managed
Applications fashion.
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
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.
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:
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
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).
Example:
ConnIDFile: /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
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
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
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
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.
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
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
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:
Example:
SysMessageOutput: 0x4
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:
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
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
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
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
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.
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
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
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:
Example:
SysMessageOutput: 0x4
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>]
[-i <ConnIdFile>] [-t <ReqTimeout>]
amclu -c attr_set -o <ObjName> -a <AttrName> [-f <KeyFile>]
-v <AttrValue> [-i <ConnIdFile>] [-t <ReqTimeout>]
amclu -c app_restart -o <ObjName> [-f <KeyFile>]
[-i <ConnIdFile>] [-t <ReqTimeout>]
amclu -c app_online -o <ObjName> [-f <KeyFile>] [-i <ConnIdFile>]
[-t <ReqTimeout>]
amclu -c app_suspend -o <ObjName> [-f <KeyFile>]
[-i <ConnIdFile>] [-t <ReqTimeout>]
amclu -h
Options
-a <AttrName> Attribute name, string
-c <Command> Command
3.6. Commands
The following sections describe the various commands the AMCLU accepts.
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.7.1.1. attach
Type: String
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"
User Populate Before AMCLU Start: Yes
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
User Populate Before AMCLU Start: Yes
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
User Populate Before AMCLU Start: Yes
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
User Populate Before AMCLU Start: Yes
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
User Populate Before AMCLU Start: Yes
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
User Populate Before AMCLU Start: Yes
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
User Populate Before AMCLU Start: No
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
User Populate Before AMCLU Start: No
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
User Populate Before AMCLU Start: No
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
User Populate Before AMCLU Start: Yes
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
User Populate Before AMCLU Start: No
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.
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
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.
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:
3.8.2. Interfaces
The function prototypes are defined in the MAML API header file, <scem/maml.h>.
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.
#include <scem/maml.h>
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).
#include <scem/maml.h>
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
function will set the global MAML API error code, maml_ErrorCode, appropriately and return a
value of -1 (MAML_ERR).
#include <scem/maml.h>
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).
#include <scem/maml.h>
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.
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,
maml_ErrorCode, appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
PARAMETERS
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 parameters of the callback are defined as: Message Flags, Sequence Number, pointer to
Message Return Code, NULL terminated string containing Attribute Name, and NULL
terminated string containing Attribute Value.
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 request on your
own, return a value of '0' from the callback and use the friendly message generation functions
with the maml_Send() call.
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).
#include <scem/maml.h>
PARAMETERS
DESCRIPTION
The maml_RegAttrSet() service function is called by an application to register a callback to be
called when processing an Attribute Set message.
The parameters of the callback are defined as: Message Flags, Sequence Number, pointer to
Message Return Code, NULL terminated string containing Attribute Name, and NULL
terminated string containing Attribute Value.
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 request on your
own, return a value of '0' from the callback and use the friendly message generation functions
with the maml_Send() call.
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
unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
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.
The parameters of the callback are defined as: Message Flags, Sequence Number, and pointer to
Message Return Code.
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.
Note that if you want to delay the follow-up response to a request, or 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.
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,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
PARAMETERS
Callback Pointer to function to be called upon reception of an Application Online
message.
DESCRIPTION
The parameters of the callback are defined as: Message Flags, Sequence Number, and pointer to
Message Return Code.
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.
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.
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
is unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
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.
The parameters of the callback are defined as: Message Flags, Sequence Number, and pointer to
Message Return Code.
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.
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.
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
is unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
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.
The parameters of the callback are defined as: Message Flags, Sequence Number, and pointer to
Message Return Code.
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.
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.
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
is unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
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.
The parameters of the callback are defined as: Message Flags, Sequence Number, and pointer to
Message Return Code.
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.
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.
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
unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
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.
The parameters of the callback are defined as: Message Flags, Sequence Number, pointer to
Message Return Code, and pointer to Process ID.
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.
Note that if you want to delay the follow-up response to a request, or 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 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
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).
#include <scem/maml.h>
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.
The parameters of the callback are defined as: Message Flags, Sequence Number, pointer to
Message Return Code, and pointer to Destination Path of APM.
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, or 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.
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
unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
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
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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
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.
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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
Name Pointer to NULL terminated string containing the attribute name. The
maximum number of characters, including the NULL, is
AMF_MAX_NAME.
Value Pointer to NULL terminated string containing the attribute value. The
maximum number of characters, including the NULL, is
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
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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
Name Pointer to NULL terminated string containing the attribute name. The
maximum number of characters, including the NULL, is
AMF_MAX_NAME.
Value Pointer to NULL terminated string containing the attribute value. The
maximum number of characters, including the NULL, is
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.
Therefore, this function is not recommended for use in signal handlers.
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
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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
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.
Therefore, this function is not recommended for use in signal handlers.
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,
maml_ErrorCode, appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
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
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_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,
maml_ErrorCode, appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
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
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_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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
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
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_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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
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
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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
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.
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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that will contain constructed message.
1 (AMF_MSG_FLAGS_RSP) - Response
MsgReturnCode Unsigned integer containing message return code where 0 is success, non-
zero is failure. Must be no greater than AMF_MAX_UINT_VAL.
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
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_CreateMsgApmInfo() MAML API service function
returns a value of 0 (MAML_ERR_NONE). If the maml_CreateMsgApmInfo() 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).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that contains message to have a variable added to it.
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.
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
function will set the global MAML API error code, maml_ErrorCode, appropriately and return a
value of -1 (MAML_ERR).
#include <scem/maml.h>
PARAMETERS
Message Pointer to structure that contains message to have a variable added to it.
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
unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
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
unsuccessful, the function will set the global MAML API error code, maml_ErrorCode,
appropriately and return a value of -1 (MAML_ERR).
#include <scem/maml.h>
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.
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).
#include <scem/maml.h>
PARAMETERS
MemSize Requested memory size.
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.
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)
#include <scem/maml.h>
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.
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.
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.
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
6. Example Usage
The following sections detail several scenarios on how to use the MAML when developing a
managed application.
#include <stdio.h>
#include <signal.h>
#include <scem/iscapi.h>
#include <scem/maml.h>
extern void TimingFn(int SigNum);
....
/*
** Setup signal handler to be called by maml every 10 ms
*/
....
/*
** Prototypes
*/
extern int AppTerminateCB(unsigned char Flags, unsigned int SeqNumber,
unsigned int *MsgReturnCode, char *ObjectName, char *Forcible, int *PID);
*/
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;
printf("maml_ProcessMessage():%s, ErrNoStr:%s\n",
MamlStr, ErrNoStr);
}
}
else
{
/*
** It’s a non-AMF message (custom message processing)
*/
....
}
}
}
}
else
{
/*
** Error Handling
*/
....
}
}
Application Termination Callback with delayed response generation (possibly perform cleanup in
another thread then acknowledge going down)
#include <unistd.h>
#include <scem/maml.h>
/*
** 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
*/
}
}
{
if(Flags & AMF_MSG_FLAGS_RSP)
{
/*
** 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);
}
/*
** Path of current APM. Used for all sends to APM (at this
time
** only Attribute Set and Premature Termination Messages)
*/
*/
printf("Timeout on message SeqNumber:%d, Type:%d, DestPath:%s\n",
SeqNumber, MsgType, DestPath);
}