Sie sind auf Seite 1von 67

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

Application Management Framework User’s Manual

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

2/67

Application Management Framework User’s Manual

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

39

3.10.2.10. maml_RegAppPrematTerm() - Register callback for Application Premature

3.10.2.9. maml_RegHeartbeat() - Register callback for Heartbeat message

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

3/67

Application Management Framework User’s Manual

Table of Figures

FIGURE 1-HIGH LEVEL ARCHITECTURE #1 (BM MONITORING LOCAL APPS) FIGURE 3-HIGH LEVEL ARCHITECTURE #2 (CM MONITORING ALL APPS IN CHASSIS)

Table of Tables

TABLE 1-RMAO STATE TABLE TABLE 3-REFERENCE MANAGED APPLICATION OBJECT ACTIONS TABLE

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

11

12

26

27

4/67

Application Management Framework User’s Manual

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

5/67

Application Management Framework User’s Manual

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

6/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

7/67

Application Management Framework User’s Manual

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

8/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

9/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

10/67

Application Management Framework User’s Manual

SNMP Module B Module A (Any Chassis) (Any Chassis) Event Director Event Director and all
SNMP
Module B
Module A
(Any Chassis)
(Any Chassis)
Event Director
Event Director and all
Chassis Mangers may
communicate with
respective on-board
SNMP agents.
Event Director Sync
Agent
Sync Agent
Event Director
(Standby)
Event Director
(Active)
Module C (Any Chassis)
Module D (Any Chassis)
Event Director
Local Board
Local Board
Client
Resources
Event Director
Resources
Client
Chassis Manager
Chassis
Chassis Manager
Sync Agent
Manager
Chassis
(Active)
Manager
Sync Agent
(Standby)
IPMI Subsystem
IPMI
Application
Subsystem
Application
Manager
Application
Agent
Application
Manager
Agent
identical
Managed
Managed
fashion.
Applications
Applications
Typical Active/Standby Chassis Managers
Module E (Any Chassis)
Event Director
Local Board
Client
Resources
Typical
Board Manager
Managed
Other board
(Active)
Board
managers,
managed by
Application
Application
Event Director
Manager
Agent
connect in
identical
Managed
fashion.
Applications

connect in

Active/Standby Event Directors

Other chassis

managers,

managed by

Event Director,

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

11/67

Application Management Framework User’s Manual

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

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

12/67

Application Management Framework User’s Manual

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).

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

13/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

14/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

15/67

Application Management Framework User’s Manual

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

16/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

17/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

18/67

Application Management Framework User’s Manual

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))

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

19/67

Application Management Framework User’s Manual

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>] [-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> -c <Command>

Version 0.4

Attribute name, string Command

UNCONTROLLED COPY WHEN PRINTED

20/67

Application Management Framework User’s Manual

"app_start"

"app_terminate"

"attr_get" "attr_set" "app_restart" "app_online" "app_suspend" Debug on

- Application Start - Application Terminate - Attribute Get - Attribute Set - Application Restart - Application Online - Application Suspend

Update the EM

-D

-e with the results of the get

-f <KeyFile> -F request forcible -h -i <ConnIdFile> -o <ObjName> -t <ReqTimeout> -v <AttrValue>

EM shared memory key file

Make termination

Display this message APM connection ID file Object name, string Request timeout in ms, decimal number (1-32767) 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()).

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.

For legacy applications (determined by attribute "hb_misses" equal

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

21/67

Application Management Framework User’s Manual

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

22/67

Application Management Framework User’s Manual

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" 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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

23/67

Application Management Framework User’s Manual

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

24/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

25/67

Application Management Framework User’s Manual

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.

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

26/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

27/67

Application Management Framework User’s Manual

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

28/67

Application Management Framework User’s Manual

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

29/67

Application Management Framework User’s Manual

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 ID 1 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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

30/67

Application Management Framework User’s Manual

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.

#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).

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.

The service functions described in this section are:

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()

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

31/67

Application Management Framework User’s Manual

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

#include <scem/maml.h>

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

#include <scem/maml.h>

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

32/67

Application Management Framework User’s Manual

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, maml_ErrorCode, appropriately and return a value of -1 (MAML_ERR).

3.10.2.3. maml_RegAttrGet() - Register callback for Attribute Get message

#include <scem/maml.h>

int maml_RegAttrGet(int (*Callback)(unsigned char, unsigned int, unsigned int *, char *, char *))

PARAMETERS

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

33/67

Application Management Framework User’s Manual

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).

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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

#include <scem/maml.h>

int maml_RegAttrSet(int (*Callback)(unsigned char, unsigned int, unsigned int *, char *, char *))

PARAMETERS

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

34/67

Application Management Framework User’s Manual

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.

The callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SeqNumber, unsigned int *MsgReturnCode, char *Name, char *Value).

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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 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.5. maml_RegAppRestart() - Register callback for Application Restart message

#include <scem/maml.h>

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

35/67

Application Management Framework User’s Manual

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 callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SeqNumber, unsigned int *MsgReturnCode).

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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, appropriately and return a value of -1 (MAML_ERR).

3.10.2.6. maml_RegAppOnline() - Register callback for Application Online message

#include <scem/maml.h>

int maml_RegAppOnline(int (*Callback)(unsigned char, unsigned int, unsigned int *))

PARAMETERS

Callback

DESCRIPTION

Version 0.4

Pointer to function to be called upon reception of an Application Online message.

UNCONTROLLED COPY WHEN PRINTED

36/67

Application Management Framework User’s Manual

The maml_RegAppOnline() service function is called by an application to register a callback to be called when processing an Application Online message.

The callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SeqNumber, unsigned int *MsgReturnCode).

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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 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.7. maml_RegAppSuspend() - Register callback for Application Suspend message

#include <scem/maml.h>

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.

The callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SeqNumber, unsigned int *MsgReturnCode).

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

37/67

Application Management Framework User’s Manual

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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 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.8. maml_RegAppAwake() - Register callback for Application Awake message

#include <scem/maml.h>

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.

The callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SeqNumber, unsigned int *MsgReturnCode).

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

38/67

Application Management Framework User’s Manual

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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 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.9. maml_RegHeartbeat() - Register callback for Heartbeat message

#include <scem/maml.h>

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.

The callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SequenceNumber, unsigned int *MsgReturnCode).

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

39/67

Application Management Framework User’s Manual

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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 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.10. maml_RegAppPrematTerm() - Register callback for Application Premature Termination message

#include <scem/maml.h>

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.

The callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SeqNumber, unsigned int *MsgReturnCode, int *PID).

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

40/67

Application Management Framework User’s Manual

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).

3.10.2.11. maml_RegApmInfo() - Register callback for APM Information message

#include <scem/maml.h>

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.

The callback will be called by maml_ProcessMessage() as (*Callback)(unsigned char Flags, unsigned int SeqNumber, unsigned int *MsgReturnCode, char *DestPath).

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK One would register this callback to determine the DISCS address of the active APM.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

41/67

Application Management Framework User’s Manual

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).

3.10.2.12. maml_RegRequestTimeoutCb() - Register callback for Request timeout.

#include <scem/maml.h>

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 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. Module Description: Friendly Message Construction Functions

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

The service functions described in this section are:

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()

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

42/67

Application Management Framework User’s Manual

3.10.3.1. maml_CreateMsgAppTerminate() - Create Application Terminate message

#include <scem/maml.h>

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

43/67

Application Management Framework User’s Manual

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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

#include <scem/maml.h>

int maml_CreateMsgAttrGet(AMF_MSG *Message, unsigned char Flags, unsigned int *SeqNumber, unsigned int MsgReturnCode, char *Name, char *Value)

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.

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

44/67

Application Management Framework User’s Manual

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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_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).

3.10.3.3. maml_CreateMsgAttrSet() - Create Attribute Set message

#include <scem/maml.h>

int maml_CreateMsgAttrSet(AMF_MSG *Message, unsigned char Flags, unsigned int *SeqNumber, unsigned int MsgReturnCode, char *Name, char *Value)

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.

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

45/67

Application Management Framework User’s Manual

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.

USAGE WITHIN APPLICATION MANAGEMENT FRAMEWORK 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 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.4. maml_CreateMsgAppRestart() - Create Application Restart message

#include <scem/maml.h>

int maml_CreateMsgAppRestart(AMF_MSG *Message, unsigned char Flags, unsigned int *SeqNumber, unsigned int MsgReturnCode)

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

Version 0.4

UNCONTROLLED COPY WHEN PRINTED

46/67

Application Management Framework User’s Manual

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 retu