OpenClovis Product Documentation - User contributions [en]

Doc:latest/evalguide/prerequisites

2014-11-17T07:12:58Z

Prasad: /* Hardware and Software Prerequisites */

==Hardware and Software Prerequisites==

The OpenClovis SAFplus Platform SDK allows the modeller to define exactly what kind of hardware configuration a model runs on. This Evaluation Model has been set up to allow a variety of hardware configurations. You should match your hardware as best as possible with one of the configurations described below.

This chapter initially summarizes the configurations you may recreate, followed by a description of the hardware and software specifications.

The hardware set up you wish to choose depends upon two factors:
*whether you wish to use ATCA blades or PCs/laptops/Virtual Machines
*number of PCs/laptops/blades/Virtual Machines you have available

The following table helps you decide which setup you can recreate. For example, if you wish to use an ATCA chassis and have 3 blades available, then you may wish to create Hardware Setup 1.2.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Hardware Setups'''
!style="background-color:lightgray;"|
!style="background-color:lightgray;" colspan="3"| Hardware Setup
|- style="background-color:lightgray;"
|
|Single Node
|3 Node - Distributed
|4 Node - Distributed
|-
|style="background-color:lightgray;"|Chassis/Blades
|Hardware Setup 1.1
|Hardware Setup 1.2
|Hardware Setup 1.3
|-
|style="background-color:lightgray;"|Pcs/Laptops/Virtual Machines
|Hardware Setup 2.1
|Hardware Setup 2.2
|Hardware Setup 2.3
|}

[[File:OpenClovis_Note.png]] The word Node here represents either a PC, laptop or blade or Virtual Machine.

===Development Environment===

The Development Machine is the primary machine where the SAFplus Platform SDK and Evaluation System is installed and built. As discussed within this document, the development machine plays an important role in moving System Controller and Payload Node images to the runtime environment.

'''Development Machine'''

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Development Machine Environment'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Development Machine
|PC or Laptop or Virtual Machine
 Hard disk - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or better)
| Linux Distribution (Ubuntu 7.04 and above preferred)
|}

[[File:OpenClovis_Note.png]] Although a distinction is made throughout this document to separate the two functions of the Development Machine and Management Station Machine, they can in fact be the same PC/Laptop/Virtual Machine.

===Runtime Environment===

A distinction is made between the Development and Runtime Environment as SAFplus Platform will most likely run within an environment made up of chassis, blades, shelf managers, switches etc. and be monitored remotely. Hence we have attempted to make this Evaluation System simulate the environment it will be used in, as represented in Runtime Hardware Setup 1.1, 1.2 and 1.3 (see Chapter [[Doc:latest/evalguide/setup#Runtime Hardware Setup| Runtime Hardware Setup]]). An alternative setup is also provided, using PCs/Virtual Machines, as discussed in Runtime Hardware Setup 2.1, 2.2 and 2.3 (again see Chapter [[Doc:latest/evalguide/setup#Runtime Hardware Setup| Runtime Hardware Setup]]).

====Runtime Setup 1.1, 1.2 and 1.3====

Runtime Hardware Setup 1.1, 1.2 or 1.3 requires a Chassis and 1, 3 or 4 blade(s) respectively and one PC or laptop or Virtual Machine to act as the Management Station Machine. Below is listed the equipment required.

=====Chassis=====

ATCA chassis with a Shelf Manager.

=====Management Station Machine=====

A Management Station is necessary for Runtime Hardware Setup 1.1, 1.2 and 1.3.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Management Station Environment'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Development Station Machine
|PC or Laptop or Virtual Machine
 Hard disk - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or better)
| Linux Distribution (Ubuntu 7.04 and above preferred)
|}

[[File:OpenClovis_Note.png]] It is possible to use a single PC/laptop/Virtual Machine as both host for the development and management machines. Virtual machine environments can also be used with some limitations to the hardware exercises.

=====System Controller=====

Runtime Hardware Setup 1.1 and 1.2 required one System Controller.

Runtime Hardware Setup 1.3 requires two System Controllers.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''System Controller'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|System Controller
|ATCA Intel (MPCBL0001) Blade
 Hard Disk - 10 GB or more
 RAM - 512 MB or more
| Linux Distribution (Ubuntu 7.04 and above preferred)
|}

=====Payload (Blades) Node=====

Two Payload nodes are necessary for Runtime Hardware Setup 1.2 and 1.3.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Payload Nodes'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Two Payload Blades
|ATCA Intel (MPCBL0001) Blade
 Hard Disk - 10 GB or more
 RAM - 512 MB or more
| Linux Distribution (Ubuntu 7.04 and above preferred)
|}

=====Switch=====

10/100Mbps or Gigabit Ethernet switch.

See Chapter [[Doc:latest/evalguide/build#Building the Evaluation System and Deploying Runtime Images| Building the Evaluation System and Deploying Runtime Images]] for further installation details.

====Runtime Setup 2.1, 2.2 and 2.3====

Runtime Hardware Setup 2 is a simpler hardware set up, only requiring PC(s)/laptop(s)/Virtual Machine(s) and a switch. Runtime Hardware Setup 2.1, 2.2 or 2.3 requires 1, 3 or 4 PC(s) or laptop(s) or Virtual Machine(s) respectively. In addition a PC or laptop or Virtual Machine is needed to act as the Management Station Machine. Below is listed the equipment required.

=====Management Station Machine=====

One Management Station is necessary for Runtime Hardware Setup 2.1, 2.2 and 2.3.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Development Management Machine'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Management/Development Station Machine
|PC or Laptop or Virtual Machine
 Hard disk - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or better)
| Linux Distribution (Ubuntu 7.04 and above preferred)
|}

[[File:OpenClovis_Note.png]] It is possible to use a single PC as the development machine, management machine and simultaneously as the target for a single node. Distributed node exercises will require a second machine. Virtual machine environments can also be used with some limitations to the hardware exercises.

=====System Controller=====

Runtime Hardware Setup 2.1 and 2.2 required one System Controller.

Runtime Hardware Setup 2.3 requires two System Controllers.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''System Controller'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|System Controller
|PC or Laptop or Virtual Machine
 Hard disk - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or Better)
| Linux Distribution (Ubuntu 7.04 and above preferred)
|}

=====Payload Node=====

Two Payload PCs /laptops/Virtual Machines are required for Runtime Hardware Setup 2.2 and 2.3.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Payload Nodes'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Two Payload Nodes
|PC or Laptop or Virtual Machine
 HD - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or Better)
| Linux Distribution (Ubuntu 7.04 and above preferred)
|}

=====Switch=====

10/100 Mbps or Gigabit ethernet switch.

See Chapter [[Doc:latest/evalguide/build#Building the Evaluation System and Deploying Runtime Images| Building the Evaluation System and Deploying Runtime Images]] for further runtime installation details.

===Summary===

This chapter provided a list of the equipment required for the development and runtime environment. See Chapter [[Doc:latest/evalguide/setup#Runtime Hardware Setup|Runtime Hardware Setup]], for further information concerning setting up the hardware environment. This is followed by Chapter [[Doc:latest/evalguide/build#Building the Evaluation System and Deploying Runtime Images| Building the Evaluation System and Deploying Runtime Images]], which provides information concerning the installation of target images onto the runtime environment.

Doc:latest/evalguide/setup

2014-11-17T07:05:22Z

Prasad: /* Runtime Hardware Setup 2.2 */

==Runtime Hardware Setup==

As SAFplus Platform will run on an environment which consists of chassis, blades, switch fabrics and shelf managers, we have created Runtime Hardware Setup 1.1, 1.2 and 1.3. If this equipment is not available we suggest using a similar environment where PCs/laptops/Virtual Machines can be used to replace the chassis and blades, see Runtime Hardware setup 2.1, 2.2 and 2.3.

'''Management Station Machine'''

The Management Machine allows users to launch the Evaluation System on the target environment, enabling them to remotely control SAFplus Platform (via ssh), start and stop sample applications and monitor output.

'''System Controller'''

One or more System Controllers are required within our target environment. For further information on the role of a System Controller see the Clovis SAFplus Platform User Guide.

'''Payload Node'''

Two Payload Nodes are required for our Evaluation System to demonstrate multi node SAFplus Platform functionality. This is required for Runtime Setup 1.2, 1.3, 2.2 and 2.3.

===Runtime Hardware Setup 1.1===

This is the simple chassis, blade setup. Where one blade/node is present and acts as the System controller. Within the Runtime Hardware Setup 1.1, the following equipment is used.
*1 ATCA Chassis
*1 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module (CMM)
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.1'''
|- style="background-color:lightgray;"
|
|System Controller
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.0.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|
|}

[[File:OpenClovis_Note.png]] The IP addresses here are examples. The end user is able to use his/her IP address. The necessary changes have to be made to <code>target.conf</code>. (See Section [[Doc:latest/evalguide/build#Configuration File - target.conf| Configuration File - target.conf]])

The following diagram shows how the above equipment has been interconnected.

[[File:eval_HwSetup1-1.png|500px|frame|center|'''Runtime Hardware Setup 1.1''']]

===Runtime Hardware Setup 1.2===

This is the chassis and blade setup, where three blades/nodes are present that act as the System Controller and two Payload Nodes. Within the Runtime Hardware Setup 1.2, the following equipment is used:
*1 ATCA Chassis
*3 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.2'''
|- style="background-color:lightgray;"
|
|System Controller
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|2
|3
|
|}

[[File:eval_HwSetup1-2.png|frame|center|'''Runtime Hardware Setup 1.2''']]

===Runtime Hardware Setup 1.3===

This four blade setup, requires two System Controllers and two Payload Nodes. The following equipment is used:
*1 ATCA Chassis
*4 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.3'''
|- style="background-color:lightgray;"
|
|System Controller0
|System Controller1
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|2
|3
|4
|
|}

[[File:eval_HwSetup1-3.png|frame|center|'''Runtime Hardware Setup 1.3''']]

===Runtime Hardware Setup 2.1===

If chassis, blades and switch fabrics are not available and you wish to run the single node setup, then the target environment can be emulated by Runtime Hardware Setup 2.1. This is the simplest set up and requires only one PC/laptop/Virtual Machine to act as the Development Machine, Management Machine and System Controller.

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.1'''
|- style="background-color:lightgray;"
|
|System Controller
|-
|style="background-color:lightgray;"|OS
| Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|}

[[File:eval_HwSetup2-1.png|frame|center|'''Runtime Hardware Setup 2.1''']]

===Runtime Hardware Setup 2.2===

If chassis, blades and switch fabrics are not available, then the target environment can be emulated by Runtime Hardware Setup 2.2. Below is a list of the required hardware:

*'''4 PCs/Laptops/Virtual Machines'''

As shown in Figure [[#Runtime Hardware Setup 2.2|Runtime Hardware Setup 2.2]], these will represent:
*1 Management Station Machine
*1 System Controller node
*2 Payload Nodes (PCs/Laptops/Virtual Machines)
*1 switch

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.2'''
|- style="background-color:lightgray;"
|
|System Controller
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|}


[[File:eval_HwSetup2-2.png|frame|center|'''Runtime Hardware Setup 2.2''']]

===Runtime Hardware Setup 2.3===

If four PCs are available then the target environment can be emulated by Runtime Hardware Setup 2.3. Below is a list of the required hardware:
*'''5 PCs/Laptops/Virtual Machines'''

These will represent:
*1 Management Station Machine
*2 System Controller node
*2 Payload Nodes (PCs/Laptops/Virtual Machines)
*1 switch

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.3'''
|- style="background-color:lightgray;"
|
|System Controller0
|System Controller1
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|}

[[File:eval_HwSetup2-3.png|frame|center|'''Runtime Hardware Setup 2.3''']]

===Summary and Next Steps===

This chapter has laid out the various hardware setups available to run our sample applications. Once you have chosen the set up that you wish to try and have all the hardware in place, correctly interlinked, the next step is to install the run time targets. This is discussed within the following chapter.

Doc:latest/evalguide/setup

2014-11-17T07:04:34Z

Prasad: /* Runtime Hardware Setup */

==Runtime Hardware Setup==

As SAFplus Platform will run on an environment which consists of chassis, blades, switch fabrics and shelf managers, we have created Runtime Hardware Setup 1.1, 1.2 and 1.3. If this equipment is not available we suggest using a similar environment where PCs/laptops/Virtual Machines can be used to replace the chassis and blades, see Runtime Hardware setup 2.1, 2.2 and 2.3.

'''Management Station Machine'''

The Management Machine allows users to launch the Evaluation System on the target environment, enabling them to remotely control SAFplus Platform (via ssh), start and stop sample applications and monitor output.

'''System Controller'''

One or more System Controllers are required within our target environment. For further information on the role of a System Controller see the Clovis SAFplus Platform User Guide.

'''Payload Node'''

Two Payload Nodes are required for our Evaluation System to demonstrate multi node SAFplus Platform functionality. This is required for Runtime Setup 1.2, 1.3, 2.2 and 2.3.

===Runtime Hardware Setup 1.1===

This is the simple chassis, blade setup. Where one blade/node is present and acts as the System controller. Within the Runtime Hardware Setup 1.1, the following equipment is used.
*1 ATCA Chassis
*1 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module (CMM)
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.1'''
|- style="background-color:lightgray;"
|
|System Controller
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.0.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|
|}

[[File:OpenClovis_Note.png]] The IP addresses here are examples. The end user is able to use his/her IP address. The necessary changes have to be made to <code>target.conf</code>. (See Section [[Doc:latest/evalguide/build#Configuration File - target.conf| Configuration File - target.conf]])

The following diagram shows how the above equipment has been interconnected.

[[File:eval_HwSetup1-1.png|500px|frame|center|'''Runtime Hardware Setup 1.1''']]

===Runtime Hardware Setup 1.2===

This is the chassis and blade setup, where three blades/nodes are present that act as the System Controller and two Payload Nodes. Within the Runtime Hardware Setup 1.2, the following equipment is used:
*1 ATCA Chassis
*3 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.2'''
|- style="background-color:lightgray;"
|
|System Controller
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|2
|3
|
|}

[[File:eval_HwSetup1-2.png|frame|center|'''Runtime Hardware Setup 1.2''']]

===Runtime Hardware Setup 1.3===

This four blade setup, requires two System Controllers and two Payload Nodes. The following equipment is used:
*1 ATCA Chassis
*4 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.3'''
|- style="background-color:lightgray;"
|
|System Controller0
|System Controller1
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|2
|3
|4
|
|}

[[File:eval_HwSetup1-3.png|frame|center|'''Runtime Hardware Setup 1.3''']]

===Runtime Hardware Setup 2.1===

If chassis, blades and switch fabrics are not available and you wish to run the single node setup, then the target environment can be emulated by Runtime Hardware Setup 2.1. This is the simplest set up and requires only one PC/laptop/Virtual Machine to act as the Development Machine, Management Machine and System Controller.

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.1'''
|- style="background-color:lightgray;"
|
|System Controller
|-
|style="background-color:lightgray;"|OS
| Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|}

[[File:eval_HwSetup2-1.png|frame|center|'''Runtime Hardware Setup 2.1''']]

===Runtime Hardware Setup 2.2===

If chassis, blades and switch fabrics are not available, then the target environment can be emulated by Runtime Hardware Setup 2.2. Below is a list of the required hardware:

*'''4 PCs/Laptops/Virtual Machines'''

As shown in Figure [[#Runtime Hardware Setup 2.2|Runtime Hardware Setup 2.2]], these will represent:
*1 Management Station Machine
*1 System Controller node
*2 Payload Nodes (PCs/Laptops)
*1 switch

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.2'''
|- style="background-color:lightgray;"
|
|System Controller
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|}


[[File:eval_HwSetup2-2.png|frame|center|'''Runtime Hardware Setup 2.2''']]

===Runtime Hardware Setup 2.3===

If four PCs are available then the target environment can be emulated by Runtime Hardware Setup 2.3. Below is a list of the required hardware:
*'''5 PCs/Laptops/Virtual Machines'''

These will represent:
*1 Management Station Machine
*2 System Controller node
*2 Payload Nodes (PCs/Laptops/Virtual Machines)
*1 switch

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.3'''
|- style="background-color:lightgray;"
|
|System Controller0
|System Controller1
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|2.6 and above
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|}

[[File:eval_HwSetup2-3.png|frame|center|'''Runtime Hardware Setup 2.3''']]

===Summary and Next Steps===

This chapter has laid out the various hardware setups available to run our sample applications. Once you have chosen the set up that you wish to try and have all the hardware in place, correctly interlinked, the next step is to install the run time targets. This is discussed within the following chapter.

Doc:latest/evalguide/csa112

2014-11-17T06:39:56Z

Prasad: /* How to Run csa212 and What to Observe */

==csa112 Event Subscription==

An event service is an communications mechanism organised around the categories of data rather then senders and receivers. A "publisher" posts a message to a well-known event channel and all "subscribers" receive the message. Publishers and subscribers do not need to know who each other are; they need only know the event channel name.

As the Messaging service is similar to mail, the Event service is similar to a bulletin board.

===Objective===

The objective of csa112 is to learn how to use the SAFplus Platform event service to subscribe to events and to extract the relevant information from the events received by subscription.

===What you will learn===

You will learn:
*how to initialize the event library
*how to subscribe to events
*how to receive events
*how to extract the event data

The SAFplus Event service is SA-Forum compliant and this tutorial expects that you will refer to the relevant SA-Forum document for an in-depth description of the APIs used.

===Code===

One difference to note between this application and previous ones is that this application will not have a main loop in <code>initializeAmf</code>. Instead we will do our work in callback code. This means that when we return from <code>initializeAmf</code> we won't exit the application.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
SaNameT evtChannelName =
{
sizeof EVENT_CHANNEL_NAME -1,
EVENT_CHANNEL_NAME
};

SaEvtChannelHandleT evtChannelHandle = 0;
SaEvtHandleT evtLibHandle=0;
SaEvtEventHandleT eventHandle=0;

static void csa112Comp_appEventCallback( SaEvtSubscriptionIdT subscriptionId,
SaEvtEventHandleT eventHandle,
SaSizeT eventDataSize);
</pre></code>
|}

Here we define variables to hold the payload of our event. Note the initialization of the <code>evtChannelName</code>. The length is set to the length of the <code>EVENT_CHANNEL_NAME</code> string WITHOUT including the <code>null</code> terminator.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{
....

const SaEvtCallbacksT evtCallbacks =
{
NULL, /* Event open callback */
csa112Comp_appEventCallback /* Event delivery callback */
};
...

// publish our event callbacks
rc = saEvtInitialize(&evtLibHandle, &evtCallbacks, &evtVersion);
...
</pre></code>
|}

We initialize the OpenClovis Event Manager with <code>saEvtInitialize</code>. We pass the address of the variable where we want the event handle stored. We pass the address of our event callback functions structure. Note that the only event callback function that we specify is <code>csa112Comp_appEventCallback</code>. We do not specify the other callback which is the Asynchronous channel open callback. We specify <code>NULL</code> for that field of <code>evtCallbacks</code> because we don't open our event channel asynchronously.:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{

....

// Open an event chanel so that we can subscribe to events on that channel
rc = saEvtChannelOpen(evtLibHandle, &evtChannelName,
(SA_EVT_CHANNEL_PUBLISHER | SA_EVT_CHANNEL_SUBSCRIBER | SA_EVT_CHANNEL_CREATE),
(SaTimeT)SA_TIME_END, &evtChannelHandle);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failure opening event channel [0x%x] at %ld", rc, time(0L));
errorExit(rc);
}

rc = saEvtEventSubscribe(evtChannelHandle, NULL, 1);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to subscribe to event channel [0x%x]",rc);
errorExit(rc);
}
</pre></code>
|}

Within the above code we open the channel synchronously. We pass the handle we got back from <code>saEvtInitialize</code>, the channel name we defined previously, flags that indicate this process is subscribing to the channel and it's a global channel, and that the channel should be created if it's not already there, a timeout value of "forever", and the address of the location where the channel handle should be stored. Then, we subscribe to a specific event stream on the event channel. The <code>EVENT_TYPE</code> constant is defined in <code>common/common.h</code> as 5432. This value is used by the event publisher when it sends events. The constant 1 being passed simply identifies this specific subscription on this channel. This value will be passed to our event delivery callback function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
static void
csa112Comp_appEventCallback(SaEvtSubscriptionIdT subscriptionId,
SaEvtEventHandleT eventHandle,
SaSizeT eventDataSize)
{

SaAisErrorT rc = SA_AIS_OK;
static ClPtrT resTest = 0;
clprintf(CL_LOG_SEV_INFO,"We've got an event to receive\n");

if (resTest != 0)
{
clHeapFree((char *)resTest);
resTest = 0;
}
resTest = clHeapAllocate(eventDataSize + 1);

if (resTest == 0)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to allocate space for event");
return;
}
rc = saEvtEventDataGet(eventHandle, resTest, &eventDataSize);

if (rc!= SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to get event data [0x%x]",rc);
return;
}

*(((char *)resTest) + eventDataSize) = 0;
clprintf(CL_LOG_SEV_INFO,"received event: %s\n", (char *)resTest);
}
</pre></code>
|}

The event delivery callback function is named <code>csa112Comp_appEventCallback</code>. It checks whether our incoming data buffer needs to be deallocated. If there is a buffer, it deallocates it and then allocates enough data to receive the incoming event data. Then, we extract the data from the event into the newly allocated buffer using <code>clEventDataGet</code>. Finally, we print the event data we received using <code>clprintf</code> which is another member of Clovis' OS Abstraction Layer. As its name and usage suggest, it is the OSAL replacement for printf.

'''Note:'''

Before building the project,copy the common directory which can be found under <code><eval_dir>/src/app</code> to the working area
<code><pre># cp -r <eval_dir>/src/app/common .</pre></code>

===How to Run csa112 and What to Observe===

<ol>
<li>Start example csa212 in the same manner that we have started previous examples, with the SAFplus Platform Console.(Unlock csa212SGI0 instead of csa112SGI0 to run csa212).
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa212SGI0
</pre></code>

Looking at the log file for this example you should see the following.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa212CompI3Log.latest
|-
|<code><pre>
Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00001 : INFO) Component [csa212CompI3] : PID [10366]. Initializing

Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00002 : INFO) IOC Address : 0x4

Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00003 : INFO) IOC Port : 0x80

Fri Oct 1 13:15:31.389 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00004 : INFO) Component [csa212CompI3] : PID [10366]. CSI Set Received

</pre></code>
|}

<li>Now unlock the application with:
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa212SGI0
</pre></code>

At this point you should see the following in the log.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa212CompI3Log.latest
|-
|<code><pre>
Fri Oct 1 13:15:31.389 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00012 : INFO) csa212: ACTIVE state requested; activating service

</pre></code>
|}

Thats all there is to this example. What you are looking at in the log is the output of our event listener. It doesn't appear very interesting because we have not yet written an event publisher that will give the program something to output. We'll do that in the next example (csa213).

<li>At this point we can shut down our example in the usual fashion.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa212SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa212SGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>
</ol>
[[File:OpenClovis_Note.png]]When running model csa212 you will not see the output described for the the amsLockAssignment and amsUnlock commands.

===Summary and References===

We've seen how to create a basic event subscriber application using Clovis' event manager library. For further reading check the Clovis SAFplus Platform API reference guide, specifically the section on the event manager. Also, the header file: <code>clEventExtApi.h</code> should be helpful.

Doc:latest/evalguide/csa113

2014-11-17T06:39:15Z

Prasad: /* csa213 SA Forum Compliant Event Publication */

==csa113 Event Publication==

===Objective===

The objective is to learn how to write an event publishing application using Clovis' Event Manager API.

===What You Will Learn===

*You will learn how to publish events using Clovis' Event Manager API.

===Code===

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{
...
const SaEvtCallbacksT evtCallbacks =
{
NULL, /* Event open callback */
csa112Comp_appEventCallback /* Event delivery callback */
};

...

/* Initialize AMF client library. */
if ( (rc = saAmfInitialize(&amfHandle, &callbacks, &version)) != SA_AIS_OK)
errorExit(rc);

....
</pre></code>
|}

In the <code>initializeAmf</code> function of this example we again see a call to <code>saAmfInitialize</code>. Everything initializeAmf function is the same as before in csa112.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{

...

// Open an event chanel so that we can subscribe to events on that channel
rc = saEvtChannelOpen(evtLibHandle,
&evtChannelName,
(SA_EVT_CHANNEL_PUBLISHER |
SA_EVT_CHANNEL_SUBSCRIBER |
SA_EVT_CHANNEL_CREATE),
(SaTimeT)SA_TIME_END,
&evtChannelHandle);
</pre></code>
|}

Here we open the event channel. This is the same as in csa112.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{

...

rc = saEvtEventAllocate(evtChannelHandle, &eventHandle);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to allocate event [0x%x]\n", rc);
assert(0);
}

rc = saEvtEventAttributesSet(eventHandle,
NULL,
1,
0,
&publisherName);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to set event attributes [0x%x]\n",rc);
assert(0);
}

</pre></code>
|}

The call to <code>saEvtEventAllocate</code> allocates an event header. This header is identified by the event handle passed back to <code>gTestInfo.eventHandle</code>. The handle should be used any time the event header is to be used to manipulate the header, either by using <code>saEvtEventAttributesSet</code> (right below), or to send an event using the header as in <code>saEvtEventPublish</code>. The call to <code>saEvtEventAttributesSet</code> defines defines the priority to be 1 which is just below the highest priority of <code>CL_EVENT_HIGHEST_PRIORITY</code> which is defined as 0 where <code>CL_EVENT_LOWEST_PRIORITY</code> is defined as 3. The retention time is specified as 0 since we don't want the event to be kept around if there is no subscriber to pick it up. Finally the <code>publisherName</code> is specified because it's required. Our subscriber doesn't care who publishes the events it receives.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
int
main(int argc,
char *argv[])
{

...

while (!unblockNow)
{
/* csa113: If I am active then I'll publish an event.
Note, any application can publish and event regardless of
HA state. This tutorial simply uses HA state so only
one of the two processes are publishing.
*/

if (running && ha_state == SA_AMF_HA_ACTIVE)
{
csa113Comp_PublishEvent();
}
/* Keep the event publish rate reasonable for this tutorial*/
sleep(1);
}
</pre></code>
|}

Here is the main loop. As long as the application is running and active we make a call to <code>csa113Comp_PublishEvent</code>. The work of the application takes place in <code>csa113Comp_PublishEvent</code>, which is presented below.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
static SaAisErrorT
csa113Comp_PublishEvent()
{
SaEvtEventIdT eventId = 0;
static int index = 0;
SaSizeT data_len = 0;
SaAisErrorT rc = SA_AIS_OK;
char *data = 0;
typedef void (*Generator)(char **, ClSizeT*);

// Note: to add a new generator, just define it above and then include
// the new functions name in the generators list.
// Next, maybe something that gets disk free info by way of getfsent
// and statfs?

static Generator generators[] =
{
generate_time_of_day,
generate_load_average
};

// every time through increment index and then set index to
// it's value modulo the number of entries in the generators
// array. This will cause us to cycle through the list of
// generators as we're called to publish events.
(*generators[index++])(&data, &data_len);
index %= (int)(sizeof generators / sizeof generators[0]);
if (data == 0 || data_len == 0)
{
clprintf(CL_LOG_SEV_ERROR, "No event data generated.");
return SA_AIS_ERR_NO_MEMORY;
}
clprintf(CL_LOG_SEV_INFO,"Publishing Event: %.*s\n",(int)data_len, data);
rc = saEvtEventPublish(eventHandle, (void *)data, data_len, &eventId);

if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR,"Event publish attempt failed with error [%x]", rc);
}
clHeapFree(data);

return SA_AIS_OK;
}
</pre></code>
|}

There's code to call one of a list of generator functions. The functions on the list, return a pointer and a length which are used to pass to <code>saEvtEventPublish</code>. We pass the eventHandle prepared earlier with <code>saEvtEventAllocate</code> and <code>saEvtEventAttributesSet</code>. Pass the pointer and the length that we get back from the generator function. Those are used to package up the event data and send it to any subscribers. We also pass the address of the <code>eventId</code> local variable. This is required so that the <code>saEvtEventPublish</code> function can return the event ID. We don't need it, so we promptly drop it in the bit bucket. Finally, we free the data that was allocated in the generator function and passed back as we no longer need it.

'''Note:'''

Before building the project,copy the common directory which can be found under <code><eval_dir>/src/app</code> to the working area
<code><pre># cp -r <eval_dir>/src/app/common .</pre></code>

===How to Run csa113 and What to Observe===

In csa113 you will be observing an event publishing application. This will be far more interesting if you observe an event subscription application at the same time. For this we will use the example from csa112.

<ol>
<li>First you should start up csa112 and put it in a LockAssignment state so that it can receive events.(Unlock csa212SGI0 instead of csa112SGI0 to run csa213).
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa112SGI0
</pre></code>

In the csa112 application log you should see:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| $ /root/asp/var/log/csa112CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:50:34 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00037 : INFO)
csa112: Instantiated as component instance csa112CompI0.
Mon Jul 14 22:50:34 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00038 : INFO)
csa112CompI0: Waiting for CSI assignment...
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00041 : INFO)
Component [csa112CompI0] : PID [24830]. CSI Set Received
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00042 : INFO)
CSI Flags : [Add One]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00043 : INFO)
CSI Name : [csa112CSII0]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00044 : INFO)
Name Value Pairs :
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00045 : INFO)
HA State : [Active]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00046 : INFO)
Active Descriptor :
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00047 : INFO)
Transition Descriptor : [1]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00048 : INFO)
Active Component : [csa112CompI0]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00049 : INFO)
csa112: ACTIVE state requested; activating service
</pre></code>
|}
[[File:OpenClovis_Note.png]]When running model csa212 you will not see the output described above for the the amsLockAssignment and amsUnlock commands. Unlock csa212SGI0 instead of csa112SGI0.

<li>Now you can start up the event publishing application and put it in a LockAssignment state. (Unlock csa213SGI0 instead of csa113SGI0 to run csa213).
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa113SGI0
</pre></code>

Putting csa113 into a LockAssignment state caused it to begin publishing events. Using <code>tail -f /root/asp/var/log/csa113CompI0Log.latest</code> on the csa113 application log you can see the events being published.(Unlock csa213SGI0 instead of csa113SGI0 to run SAF version).
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| $ /root/asp/var/log/csa113CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00028 : INFO)
Component [csa113CompI0] : PID [24890]. Initializing
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00029 : INFO)
IOC Address : 0x1
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00030 : INFO)
IOC Port : 0x81
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00037 : INFO)
Instantiated as component instance csa113CompI0.
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00038 : INFO)
csa113CompI0: Waiting for CSI assignment...
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00041 : INFO)
Component [csa113CompI0] : PID [24890]. CSI Set Received
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00042 : INFO)
CSI Flags : [Add One]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00043 : INFO)
CSI Name : [csa113CSII0]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00044 : INFO)
Name Value Pairs :
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00045 : INFO)
HA State : [Active]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00046 : INFO)
Active Descriptor :
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00047 : INFO)
Transition Descriptor : [1]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00048 : INFO)
Active Component : [csa113CompI0]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00049 : INFO)
csa113: ACTIVE state requested; activating service
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00050 : NOTICE)
Publishing Event: Mon Jul 14 22:53:59 2008
Mon Jul 14 22:54:00 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00052 : NOTICE)
Publishing Event: 0.05 0.07 0.03
Mon Jul 14 22:54:01 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00054 : NOTICE)
Publishing Event: Mon Jul 14 22:54:01 2008
Mon Jul 14 22:54:02 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00056 : NOTICE)
Publishing Event: 0.05 0.07 0.03
Mon Jul 14 22:54:03 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00058 : NOTICE)
Publishing Event: Mon Jul 14 22:54:03 2008
Mon Jul 14 22:54:04 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00060 : NOTICE)
Publishing Event: 0.05 0.07 0.03
</pre></code>
|}

Since the event subscriber application is also running you can see the events that it is receiving in the csa112 application log file. Again using <code>tail -f /rootasp//var/log/csa112CompI0Log.latest</code> you can see the following:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa112CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:53:59 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00052 : NOTICE)
We've got an event to receive
Mon Jul 14 22:53:59 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00054 : NOTICE)
received event: Mon Jul 14 22:53:59 2008
Mon Jul 14 22:54:00 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00058 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:00 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00060 : NOTICE)
received event: 0.05 0.07 0.03
Mon Jul 14 22:54:01 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00064 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:01 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00066 : NOTICE)
received event: Mon Jul 14 22:54:01 2008
Mon Jul 14 22:54:02 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00070 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:02 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00072 : NOTICE)
received event: 0.05 0.07 0.03
</pre></code>
|}

<li>Now you can shut everything down in the usual manner. Note that you will be shutting down two service groups.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>

</ol>

===Summary and References===

We've seen how to initialize the event manager subsystem as an event publisher. We've seen:
*events flow from the event publisher to the subscriber.
*how to format events and send them through the event manager subsystem
*For further reading, check the same sources as listed under the csa112 section.

Doc:latest/evalguide/csa113

2014-11-17T06:38:12Z

Prasad: /* Code */

==csa113 Event Publication==

===Objective===

The objective is to learn how to write an event publishing application using Clovis' Event Manager API.

===What You Will Learn===

*You will learn how to publish events using Clovis' Event Manager API.

===Code===

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{
...
const SaEvtCallbacksT evtCallbacks =
{
NULL, /* Event open callback */
csa112Comp_appEventCallback /* Event delivery callback */
};

...

/* Initialize AMF client library. */
if ( (rc = saAmfInitialize(&amfHandle, &callbacks, &version)) != SA_AIS_OK)
errorExit(rc);

....
</pre></code>
|}

In the <code>initializeAmf</code> function of this example we again see a call to <code>saAmfInitialize</code>. Everything initializeAmf function is the same as before in csa112.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{

...

// Open an event chanel so that we can subscribe to events on that channel
rc = saEvtChannelOpen(evtLibHandle,
&evtChannelName,
(SA_EVT_CHANNEL_PUBLISHER |
SA_EVT_CHANNEL_SUBSCRIBER |
SA_EVT_CHANNEL_CREATE),
(SaTimeT)SA_TIME_END,
&evtChannelHandle);
</pre></code>
|}

Here we open the event channel. This is the same as in csa112.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{

...

rc = saEvtEventAllocate(evtChannelHandle, &eventHandle);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to allocate event [0x%x]\n", rc);
assert(0);
}

rc = saEvtEventAttributesSet(eventHandle,
NULL,
1,
0,
&publisherName);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to set event attributes [0x%x]\n",rc);
assert(0);
}

</pre></code>
|}

The call to <code>saEvtEventAllocate</code> allocates an event header. This header is identified by the event handle passed back to <code>gTestInfo.eventHandle</code>. The handle should be used any time the event header is to be used to manipulate the header, either by using <code>saEvtEventAttributesSet</code> (right below), or to send an event using the header as in <code>saEvtEventPublish</code>. The call to <code>saEvtEventAttributesSet</code> defines defines the priority to be 1 which is just below the highest priority of <code>CL_EVENT_HIGHEST_PRIORITY</code> which is defined as 0 where <code>CL_EVENT_LOWEST_PRIORITY</code> is defined as 3. The retention time is specified as 0 since we don't want the event to be kept around if there is no subscriber to pick it up. Finally the <code>publisherName</code> is specified because it's required. Our subscriber doesn't care who publishes the events it receives.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
int
main(int argc,
char *argv[])
{

...

while (!unblockNow)
{
/* csa113: If I am active then I'll publish an event.
Note, any application can publish and event regardless of
HA state. This tutorial simply uses HA state so only
one of the two processes are publishing.
*/

if (running && ha_state == SA_AMF_HA_ACTIVE)
{
csa113Comp_PublishEvent();
}
/* Keep the event publish rate reasonable for this tutorial*/
sleep(1);
}
</pre></code>
|}

Here is the main loop. As long as the application is running and active we make a call to <code>csa113Comp_PublishEvent</code>. The work of the application takes place in <code>csa113Comp_PublishEvent</code>, which is presented below.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
static SaAisErrorT
csa113Comp_PublishEvent()
{
SaEvtEventIdT eventId = 0;
static int index = 0;
SaSizeT data_len = 0;
SaAisErrorT rc = SA_AIS_OK;
char *data = 0;
typedef void (*Generator)(char **, ClSizeT*);

// Note: to add a new generator, just define it above and then include
// the new functions name in the generators list.
// Next, maybe something that gets disk free info by way of getfsent
// and statfs?

static Generator generators[] =
{
generate_time_of_day,
generate_load_average
};

// every time through increment index and then set index to
// it's value modulo the number of entries in the generators
// array. This will cause us to cycle through the list of
// generators as we're called to publish events.
(*generators[index++])(&data, &data_len);
index %= (int)(sizeof generators / sizeof generators[0]);
if (data == 0 || data_len == 0)
{
clprintf(CL_LOG_SEV_ERROR, "No event data generated.");
return SA_AIS_ERR_NO_MEMORY;
}
clprintf(CL_LOG_SEV_INFO,"Publishing Event: %.*s\n",(int)data_len, data);
rc = saEvtEventPublish(eventHandle, (void *)data, data_len, &eventId);

if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR,"Event publish attempt failed with error [%x]", rc);
}
clHeapFree(data);

return SA_AIS_OK;
}
</pre></code>
|}

There's code to call one of a list of generator functions. The functions on the list, return a pointer and a length which are used to pass to <code>saEvtEventPublish</code>. We pass the eventHandle prepared earlier with <code>saEvtEventAllocate</code> and <code>saEvtEventAttributesSet</code>. Pass the pointer and the length that we get back from the generator function. Those are used to package up the event data and send it to any subscribers. We also pass the address of the <code>eventId</code> local variable. This is required so that the <code>saEvtEventPublish</code> function can return the event ID. We don't need it, so we promptly drop it in the bit bucket. Finally, we free the data that was allocated in the generator function and passed back as we no longer need it.

'''Note:'''

Before building the project,copy the common directory which can be found under <code><eval_dir>/src/app</code> to the working area
<code><pre># cp -r <eval_dir>/src/app/common .</pre></code>

===csa213 SA Forum Compliant Event Publication===

This sample application demonstrates the usage of SA Forum Event Service. As mentioned previously, this sample application does not deviate functionally with csa113. The code differences are due to using SA Forum data types (structures) and APIs , as presented in the following two tables. (Note we have not repeated data types and APIs covered previously.)

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum Data Types with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum Data Types
!OpenClovis Data Types
|-
|SaEvtHandleT
|ClEventHandleT
|}

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum APIs with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum APIs
!OpenClovis APIs
|-
|SaEvtEventAllocate
|ClEventAllocate
|-
|saEvtEventAttributesSet
|clEventExtAttributesSet
|-
|saEvtEventPublish
|clEventPublish
|}

===How to Run csa113 and What to Observe===

In csa113 you will be observing an event publishing application. This will be far more interesting if you observe an event subscription application at the same time. For this we will use the example from csa112.

<ol>
<li>First you should start up csa112 and put it in a LockAssignment state so that it can receive events.(Unlock csa212SGI0 instead of csa112SGI0 to run csa213).
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa112SGI0
</pre></code>

In the csa112 application log you should see:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| $ /root/asp/var/log/csa112CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:50:34 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00037 : INFO)
csa112: Instantiated as component instance csa112CompI0.
Mon Jul 14 22:50:34 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00038 : INFO)
csa112CompI0: Waiting for CSI assignment...
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00041 : INFO)
Component [csa112CompI0] : PID [24830]. CSI Set Received
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00042 : INFO)
CSI Flags : [Add One]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00043 : INFO)
CSI Name : [csa112CSII0]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00044 : INFO)
Name Value Pairs :
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00045 : INFO)
HA State : [Active]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00046 : INFO)
Active Descriptor :
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00047 : INFO)
Transition Descriptor : [1]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00048 : INFO)
Active Component : [csa112CompI0]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00049 : INFO)
csa112: ACTIVE state requested; activating service
</pre></code>
|}
[[File:OpenClovis_Note.png]]When running model csa212 you will not see the output described above for the the amsLockAssignment and amsUnlock commands. Unlock csa212SGI0 instead of csa112SGI0.

<li>Now you can start up the event publishing application and put it in a LockAssignment state. (Unlock csa213SGI0 instead of csa113SGI0 to run csa213).
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa113SGI0
</pre></code>

Putting csa113 into a LockAssignment state caused it to begin publishing events. Using <code>tail -f /root/asp/var/log/csa113CompI0Log.latest</code> on the csa113 application log you can see the events being published.(Unlock csa213SGI0 instead of csa113SGI0 to run SAF version).
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| $ /root/asp/var/log/csa113CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00028 : INFO)
Component [csa113CompI0] : PID [24890]. Initializing
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00029 : INFO)
IOC Address : 0x1
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00030 : INFO)
IOC Port : 0x81
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00037 : INFO)
Instantiated as component instance csa113CompI0.
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00038 : INFO)
csa113CompI0: Waiting for CSI assignment...
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00041 : INFO)
Component [csa113CompI0] : PID [24890]. CSI Set Received
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00042 : INFO)
CSI Flags : [Add One]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00043 : INFO)
CSI Name : [csa113CSII0]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00044 : INFO)
Name Value Pairs :
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00045 : INFO)
HA State : [Active]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00046 : INFO)
Active Descriptor :
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00047 : INFO)
Transition Descriptor : [1]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00048 : INFO)
Active Component : [csa113CompI0]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00049 : INFO)
csa113: ACTIVE state requested; activating service
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00050 : NOTICE)
Publishing Event: Mon Jul 14 22:53:59 2008
Mon Jul 14 22:54:00 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00052 : NOTICE)
Publishing Event: 0.05 0.07 0.03
Mon Jul 14 22:54:01 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00054 : NOTICE)
Publishing Event: Mon Jul 14 22:54:01 2008
Mon Jul 14 22:54:02 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00056 : NOTICE)
Publishing Event: 0.05 0.07 0.03
Mon Jul 14 22:54:03 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00058 : NOTICE)
Publishing Event: Mon Jul 14 22:54:03 2008
Mon Jul 14 22:54:04 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00060 : NOTICE)
Publishing Event: 0.05 0.07 0.03
</pre></code>
|}

Since the event subscriber application is also running you can see the events that it is receiving in the csa112 application log file. Again using <code>tail -f /rootasp//var/log/csa112CompI0Log.latest</code> you can see the following:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa112CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:53:59 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00052 : NOTICE)
We've got an event to receive
Mon Jul 14 22:53:59 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00054 : NOTICE)
received event: Mon Jul 14 22:53:59 2008
Mon Jul 14 22:54:00 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00058 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:00 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00060 : NOTICE)
received event: 0.05 0.07 0.03
Mon Jul 14 22:54:01 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00064 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:01 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00066 : NOTICE)
received event: Mon Jul 14 22:54:01 2008
Mon Jul 14 22:54:02 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00070 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:02 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00072 : NOTICE)
received event: 0.05 0.07 0.03
</pre></code>
|}

<li>Now you can shut everything down in the usual manner. Note that you will be shutting down two service groups.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>

</ol>

===Summary and References===

We've seen how to initialize the event manager subsystem as an event publisher. We've seen:
*events flow from the event publisher to the subscriber.
*how to format events and send them through the event manager subsystem
*For further reading, check the same sources as listed under the csa112 section.

Doc:latest/evalguide/csa112

2014-11-17T05:07:43Z

Prasad: /* csa212 SA Forum Compliant Event Subscription */

==csa112 Event Subscription==

An event service is an communications mechanism organised around the categories of data rather then senders and receivers. A "publisher" posts a message to a well-known event channel and all "subscribers" receive the message. Publishers and subscribers do not need to know who each other are; they need only know the event channel name.

As the Messaging service is similar to mail, the Event service is similar to a bulletin board.

===Objective===

The objective of csa112 is to learn how to use the SAFplus Platform event service to subscribe to events and to extract the relevant information from the events received by subscription.

===What you will learn===

You will learn:
*how to initialize the event library
*how to subscribe to events
*how to receive events
*how to extract the event data

The SAFplus Event service is SA-Forum compliant and this tutorial expects that you will refer to the relevant SA-Forum document for an in-depth description of the APIs used.

===Code===

One difference to note between this application and previous ones is that this application will not have a main loop in <code>initializeAmf</code>. Instead we will do our work in callback code. This means that when we return from <code>initializeAmf</code> we won't exit the application.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
SaNameT evtChannelName =
{
sizeof EVENT_CHANNEL_NAME -1,
EVENT_CHANNEL_NAME
};

SaEvtChannelHandleT evtChannelHandle = 0;
SaEvtHandleT evtLibHandle=0;
SaEvtEventHandleT eventHandle=0;

static void csa112Comp_appEventCallback( SaEvtSubscriptionIdT subscriptionId,
SaEvtEventHandleT eventHandle,
SaSizeT eventDataSize);
</pre></code>
|}

Here we define variables to hold the payload of our event. Note the initialization of the <code>evtChannelName</code>. The length is set to the length of the <code>EVENT_CHANNEL_NAME</code> string WITHOUT including the <code>null</code> terminator.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{
....

const SaEvtCallbacksT evtCallbacks =
{
NULL, /* Event open callback */
csa112Comp_appEventCallback /* Event delivery callback */
};
...

// publish our event callbacks
rc = saEvtInitialize(&evtLibHandle, &evtCallbacks, &evtVersion);
...
</pre></code>
|}

We initialize the OpenClovis Event Manager with <code>saEvtInitialize</code>. We pass the address of the variable where we want the event handle stored. We pass the address of our event callback functions structure. Note that the only event callback function that we specify is <code>csa112Comp_appEventCallback</code>. We do not specify the other callback which is the Asynchronous channel open callback. We specify <code>NULL</code> for that field of <code>evtCallbacks</code> because we don't open our event channel asynchronously.:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{

....

// Open an event chanel so that we can subscribe to events on that channel
rc = saEvtChannelOpen(evtLibHandle, &evtChannelName,
(SA_EVT_CHANNEL_PUBLISHER | SA_EVT_CHANNEL_SUBSCRIBER | SA_EVT_CHANNEL_CREATE),
(SaTimeT)SA_TIME_END, &evtChannelHandle);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failure opening event channel [0x%x] at %ld", rc, time(0L));
errorExit(rc);
}

rc = saEvtEventSubscribe(evtChannelHandle, NULL, 1);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to subscribe to event channel [0x%x]",rc);
errorExit(rc);
}
</pre></code>
|}

Within the above code we open the channel synchronously. We pass the handle we got back from <code>saEvtInitialize</code>, the channel name we defined previously, flags that indicate this process is subscribing to the channel and it's a global channel, and that the channel should be created if it's not already there, a timeout value of "forever", and the address of the location where the channel handle should be stored. Then, we subscribe to a specific event stream on the event channel. The <code>EVENT_TYPE</code> constant is defined in <code>common/common.h</code> as 5432. This value is used by the event publisher when it sends events. The constant 1 being passed simply identifies this specific subscription on this channel. This value will be passed to our event delivery callback function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
static void
csa112Comp_appEventCallback(SaEvtSubscriptionIdT subscriptionId,
SaEvtEventHandleT eventHandle,
SaSizeT eventDataSize)
{

SaAisErrorT rc = SA_AIS_OK;
static ClPtrT resTest = 0;
clprintf(CL_LOG_SEV_INFO,"We've got an event to receive\n");

if (resTest != 0)
{
clHeapFree((char *)resTest);
resTest = 0;
}
resTest = clHeapAllocate(eventDataSize + 1);

if (resTest == 0)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to allocate space for event");
return;
}
rc = saEvtEventDataGet(eventHandle, resTest, &eventDataSize);

if (rc!= SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to get event data [0x%x]",rc);
return;
}

*(((char *)resTest) + eventDataSize) = 0;
clprintf(CL_LOG_SEV_INFO,"received event: %s\n", (char *)resTest);
}
</pre></code>
|}

The event delivery callback function is named <code>csa112Comp_appEventCallback</code>. It checks whether our incoming data buffer needs to be deallocated. If there is a buffer, it deallocates it and then allocates enough data to receive the incoming event data. Then, we extract the data from the event into the newly allocated buffer using <code>clEventDataGet</code>. Finally, we print the event data we received using <code>clprintf</code> which is another member of Clovis' OS Abstraction Layer. As its name and usage suggest, it is the OSAL replacement for printf.

'''Note:'''

Before building the project,copy the common directory which can be found under <code><eval_dir>/src/app</code> to the working area
<code><pre># cp -r <eval_dir>/src/app/common .</pre></code>

===How to Run csa212 and What to Observe===

<ol>
<li>Start example csa212 in the same manner that we have started previous examples, with the SAFplus Platform Console.(Unlock csa212SGI0 instead of csa112SGI0 to run csa212).
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa212SGI0
</pre></code>

Looking at the log file for this example you should see the following.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa212CompI3Log.latest
|-
|<code><pre>
Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00001 : INFO) Component [csa212CompI3] : PID [10366]. Initializing

Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00002 : INFO) IOC Address : 0x4

Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00003 : INFO) IOC Port : 0x80

Fri Oct 1 13:15:31.389 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00004 : INFO) Component [csa212CompI3] : PID [10366]. CSI Set Received

</pre></code>
|}

<li>Now unlock the application with:
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa212SGI0
</pre></code>

At this point you should see the following in the log.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa212CompI3Log.latest
|-
|<code><pre>
Fri Oct 1 13:15:31.389 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00012 : INFO) csa212: ACTIVE state requested; activating service

</pre></code>
|}

Thats all there is to this example. What you are looking at in the log is the output of our event listener. It doesn't appear very interesting because we have not yet written an event publisher that will give the program something to output. We'll do that in the next example (csa213).

<li>At this point we can shut down our example in the usual fashion.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa212SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa212SGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>
</ol>
[[File:OpenClovis_Note.png]]When running model csa212 you will not see the output described for the the amsLockAssignment and amsUnlock commands.

===Summary and References===

We've seen how to create a basic event subscriber application using Clovis' event manager library. For further reading check the Clovis SAFplus Platform API reference guide, specifically the section on the event manager. Also, the header file: <code>clEventExtApi.h</code> should be helpful.

Doc:latest/evalguide/csa102

2014-11-14T11:38:22Z

Prasad: /* How to Run csa102 and What to Observe */

==csa102 Redundancy and Failover==

===Objective===

This sample demonstrates basic HA (High Availability) and SU (Service Unit) fail-over functionality. The application has two components, both processing the same workload as csa101, that is, repeatedly printing "Hello World". The difference, however, is that in this case there is now an active component and a standby component, with only the active component performing the printing function.

csa102 is quite similar to csa101, and this section will discuss the areas in which they deviate.

===What you will learn===

*Keeping track of HA states and how to respond to callbacks requesting HA state changes.

===How to create new Project Model csa102===
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model for csa102(the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. This is same as created for ''csa101''.

Create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE as follows:</li>
<code><pre>
# cl-ide
</pre></code>
<li>Start cl-ide by specifying the full path</li>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code. Select the workspace and click '''OK''' to launch SAFplus Platform IDE.

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model '''csa102''' for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.This step is similar compared to ''csa101''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

Enter the following information (These steps are similar compared to ''csa101''):

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''SDK Location''': Enter the location where the SAFplus Platform SDK was installed. For e.g. if the SDK was installed at location /opt/clovis, then the SDK location is /opt/clovis/sdk-<version>.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Tutorial_csa102_AddBlade.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Tutorial_csa102_AddNode.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:Tutorial_csa102_DefineProgramNames.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa102 continuously prints "Hello World!" '''redundantly''').

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa102' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa102SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Tutorial_csa102_ServiceGroupDetails.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our redundant model (which only has one node with one Active component and another standby component used for redundancy) change the '''Redundancy Model''' to '2N Redundancy' as shown.

 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa102 application will not yet start printing "Hello World!".

<li>The third change that we want to make is to the '''Auto repair'''. The '''Auto repair''' defines the state of the component to be achieved after failure of the component. So our csa102 application will not yet start printing "Hello World!".
<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa102'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_csa102_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

To make the model to recover from failure by Stand-by component, the field '''Recovery action on error''' needs to be changed to ''Component fail over''.

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' window will be displayed. If you now completely expand the AMF Configuration branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_csa102_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

===Code===

The code can be geneteted using the same steps as mentioned for csa101. The genetated code can be found within the following directory
<project-area_dir>/eval/src/app/csa102Comp

This sample component is implemented in a few C modules that are quite similar to the csa101 module. We will discuss the additions in detail.

We change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10, CL_LOG_AREA_UNSPECIFIED, CL_LOG_CONTEXT_UNSPECIFIED, __VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;
</pre></code>
|}

Next, the log stream is initialized in the application's "main" function:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
/*
* Initialize the log stream
*/
clEvalAppLogStreamOpen((ClCharT*)appName.value, &gEvalLogStream);
</pre></code>
|}

This function is implemented in the src/app/ev.c file.

As with csa102, the <code>safAssignWork()</code> function is called to set the component's HA state, and the following block of code assigns this requested state to the component, while verbosely detailing this process:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/
pthread_t thr;

clprintf(CL_LOG_SEV_INFO,"csa102: ACTIVE state requested; activating service");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Standby state requested");
running = 0;
saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Acknowledging new state quiesced");
running = 0;

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Signaling completion of QUIESCING");
running = 0;

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
...
</pre></code>
|}

In this case the application spawns a thread when it is assigned active which is a very common strategy for threaded applications. It also sets a global variable "running" to true. When the application is "quesced" -- that is when the active work assignment is taken away -- the application sets this global variable back to 0 to trigger the active thread to quit itself. The thread is simply defined as:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO,"csa102: Threaded Hello World! %s", show_progress());
sleep(2);
}
return NULL;
}

static char* show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}
</pre></code>
|}

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds)) saAmfDispatch(amfHandle, SA_DISPATCH_ALL);

if (running) clprintf(CL_LOG_SEV_INFO,"csa102: Unthreaded Hello World! %s", show_progress()); // Run the "active" code
else clprintf(CL_LOG_SEV_INFO,"csa102: idle");
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===How to Run csa102 and What to Observe===

As with the csa102 example we will use the SAFplus Platform Console to manipulate the administrative state of the csa102 service group.

<ol>
<li>Start the SAFplus Platform Console<code><pre>
# cd /root/asp/bin
# ./asp_console</pre></code>

<li>Then put the csa102SGI0 service group into lock assignment state using the following commands.<code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa102SGI0
</pre></code>

Because example 102 has two components there will be two application log files to view. These are <code>/root/asp/var/log/csa102I0Log.latest</code> and <code>/root/asp/var/log/csa102I1Log.latest</code>. Viewing these application logs using the <code>tail -f</code>, you should see the following.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102I0Log.latest
|-
|<code><pre>
Fri Nov 14 16:54:40.339 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00001 : INFO)
Component [csa102I0] : PID [22012]. Initializing

Fri Nov 14 16:54:40.340 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Fri Nov 14 16:54:40.340 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Fri Nov 14 16:54:42.342 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00004 : INFO)
csa102: idle
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102I1Log.latest
|-
|<code><pre>
Fri Nov 14 16:54:40.347 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00001 : INFO)
Component [csa102I1] : PID [22013]. Initializing

Fri Nov 14 16:54:40.347 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00002 : INFO)
IOC Address : 0x1

Fri Nov 14 16:54:40.347 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00003 : INFO)
IOC Port : 0x82

Fri Nov 14 16:54:42.350 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00004 : INFO)
csa102: idle
</pre></code>
|}

<li>Next, unlock the service group using the following SAFplus Platform Console command.
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa102SGI0
</pre></code>
and in the /var/log/csa102I*.log files we should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102I0Log.latest
|-
|<code><pre>
Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00024 : INFO)
Component [csa102I0] : PID [22012]. CSI Set Received

Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00025 : INFO)
CSI Flags : [Add One]

Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00026 : INFO)
CSI Name : [csa102CSII0]

Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00027 : INFO)
Name value pairs :

Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00028 : INFO)
HA state : [Active]
Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00029 : INFO)
Active Descriptor :
Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00030 : INFO)
Transition Descriptor : [1]

Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00031 : INFO)
Active Component : [csa102I0]

Fri Nov 14 16:55:21.816 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00032 : INFO)
csa102: ACTIVE state requested; activating service

Fri Nov 14 16:55:21.818 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00033 : INFO)
csa102: Unthreaded Hello World! .

Fri Nov 14 16:55:21.818 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00034 : INFO)
csa102: Threaded Hello World! .

Fri Nov 14 16:55:23.818 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00035 : INFO)
csa102: Threaded Hello World! .

Fri Nov 14 16:55:23.821 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00036 : INFO)
csa102: Unthreaded Hello World! .

Fri Nov 14 16:55:25.819 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00037 : INFO)
csa102: Threaded Hello World! .

Fri Nov 14 16:55:25.823 2014 (SCNodeI0.22012 : csa102I0.MAI.---.00038 : INFO)
csa102: Unthreaded Hello World! .
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102I1Log.latest
|-
|<code><pre>
Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00024 : INFO)
Component [csa102I1] : PID [22013]. CSI Set Received

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00025 : INFO)
CSI Flags : [Add One]

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00026 : INFO)
CSI Name : [csa102CSII0]

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00027 : INFO) Name value pairs :

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00028 : INFO)
HA state : [Standby]

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00029 : INFO)
Standby Descriptor :

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00030 : INFO)
Standby Rank : [1]

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00031 : INFO)
Active Component : [csa102I0]

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00032 : INFO)
csa102: Standby state requested

Fri Nov 14 16:55:21.855 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00033 : INFO)
csa102: idle
</pre></code>
|}

These can be watched in a separate terminal window using <code>tail -f</code>. csa102I0 is the active component in this case, and csa102I1 is the standby. Consequently, the "Hello world!" lines appear in csa102I0.log and not in csa102I1.log. They will continue to be logged to that file until the HA state of that component changes, for example, when the process logging those lines is killed. In the mean time the standby component: csa102I1 just waits until it is told that it should take over the workload.
</ol>

'''Changing the HA state of the Client/Server'''

The easiest way to test component fail-over is to kill the process associated with the active component using the <code>kill</code> command. For this you need to know the process ID of the active component. To find the process ID issue the following command from a bash shell.
# ps -eaf | grep csa102
This should produce an output that looks similar to the following.
root 22012 21797 0 16:54 ? 00:00:00 /root/asp/bin/csa102 -p
root 22013 21797 0 16:54 ? 00:00:00 /root/asp/bin/csa102 -p
root 22089 2321 0 16:55 pts/0 00:00:00 grep --color=auto csa102

Notice the two entries that end with <code>csa102 -p</code>. These are our two component processes. The first one is usually the active process. This is the one that we will kill. In this case the process ID is 22012. So to kill the active component you issue the command:
# kill -9 22012
[[File:OpenClovis_Note.png]]If this step does not result in the active component being killed then it is likely that the standby component was killed. In this case simply try killing the other process.

After executing the <code>kill</code> command you can see in the csa102I1 application that the standby component is now active.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102I1Log.latest
|-
|<code><pre>
Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00053 : INFO)
Component [csa102I1] : PID [22013]. CSI Set Received

Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00054 : INFO)
CSI Flags : [Target All]

Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00055 : INFO)
HA state : [Active]

Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00056 : INFO)
Active Descriptor :

Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00057 : INFO)
Transition Descriptor : [3]

Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00058 : INFO)
Active Component : [csa102I0]

Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00059 : INFO)
csa102: ACTIVE state requested; activating service

Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00060 : INFO)
csa102: Unthreaded Hello World! .

Fri Nov 14 16:56:00.257 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00061 : INFO)
csa102: Threaded Hello World! .

Fri Nov 14 16:56:02.258 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00062 : INFO)
csa102: Threaded Hello World! .

Fri Nov 14 16:56:02.259 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00063 : INFO)
csa102: Unthreaded Hello World! .

Fri Nov 14 16:56:04.259 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00064 : INFO)
csa102: Threaded Hello World! .

Fri Nov 14 16:56:04.261 2014 (SCNodeI0.22013 : csa102I1.MAI.---.00065 : INFO)
csa102: Unthreaded Hello World! .
</pre></code>
|}

This indicates that the standby component has taken over for the failed active component.

Looking in the csa102I0 application log you can see that this component was killed and has been restarted. Since csa102I1 took over as the active component this component now goes into the standby state.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102I0Log.latest
|-
|<code><pre>
Fri Nov 14 16:56:00.768 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00001 : INFO)
Component [csa102I0] : PID [22096]. Initializing

Fri Nov 14 16:56:00.768 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Fri Nov 14 16:56:00.768 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00003 : INFO)
IOC Port : 0x83

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00004 : INFO)
Component [csa102I0] : PID [22096]. CSI Set Received

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00005 : INFO)
CSI Flags : [Add One]

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00006 : INFO)
CSI Name : [csa102CSII0]

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00007 : INFO)
Name value pairs :

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00008 : INFO)
HA state : [Standby]

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00009 : INFO)
Standby Descriptor :

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00010 : INFO)
Standby Rank : [1]

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00011 : INFO)
Active Component : [csa102I1]

Fri Nov 14 16:56:00.769 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00012 : INFO)
csa102: Standby state requested

Fri Nov 14 16:56:00.772 2014 (SCNodeI0.22096 : csa102I0.MAI.---.00013 : INFO)
csa102: idle
</pre></code>
|}

You can continue to observe this failover by alternately killing the active component.

To stop csa102 using the SAFplus Platform Console.
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa102SGI0
Successfully changed state of csa102SGI0 to LockAssignment
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa102SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
Successfully changed state of csa102SGI0 to LockInstantiation and exit.

===Summary===

This Sample Application has covered basic HA and failover, with changing the state of a component to active and standby.

Doc:latest/evalguide/csa112

2014-11-14T11:19:03Z

Prasad: /* Code */

==csa112 Event Subscription==

An event service is an communications mechanism organised around the categories of data rather then senders and receivers. A "publisher" posts a message to a well-known event channel and all "subscribers" receive the message. Publishers and subscribers do not need to know who each other are; they need only know the event channel name.

As the Messaging service is similar to mail, the Event service is similar to a bulletin board.

===Objective===

The objective of csa112 is to learn how to use the SAFplus Platform event service to subscribe to events and to extract the relevant information from the events received by subscription.

===What you will learn===

You will learn:
*how to initialize the event library
*how to subscribe to events
*how to receive events
*how to extract the event data

The SAFplus Event service is SA-Forum compliant and this tutorial expects that you will refer to the relevant SA-Forum document for an in-depth description of the APIs used.

===Code===

One difference to note between this application and previous ones is that this application will not have a main loop in <code>initializeAmf</code>. Instead we will do our work in callback code. This means that when we return from <code>initializeAmf</code> we won't exit the application.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
SaNameT evtChannelName =
{
sizeof EVENT_CHANNEL_NAME -1,
EVENT_CHANNEL_NAME
};

SaEvtChannelHandleT evtChannelHandle = 0;
SaEvtHandleT evtLibHandle=0;
SaEvtEventHandleT eventHandle=0;

static void csa112Comp_appEventCallback( SaEvtSubscriptionIdT subscriptionId,
SaEvtEventHandleT eventHandle,
SaSizeT eventDataSize);
</pre></code>
|}

Here we define variables to hold the payload of our event. Note the initialization of the <code>evtChannelName</code>. The length is set to the length of the <code>EVENT_CHANNEL_NAME</code> string WITHOUT including the <code>null</code> terminator.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{
....

const SaEvtCallbacksT evtCallbacks =
{
NULL, /* Event open callback */
csa112Comp_appEventCallback /* Event delivery callback */
};
...

// publish our event callbacks
rc = saEvtInitialize(&evtLibHandle, &evtCallbacks, &evtVersion);
...
</pre></code>
|}

We initialize the OpenClovis Event Manager with <code>saEvtInitialize</code>. We pass the address of the variable where we want the event handle stored. We pass the address of our event callback functions structure. Note that the only event callback function that we specify is <code>csa112Comp_appEventCallback</code>. We do not specify the other callback which is the Asynchronous channel open callback. We specify <code>NULL</code> for that field of <code>evtCallbacks</code> because we don't open our event channel asynchronously.:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{

....

// Open an event chanel so that we can subscribe to events on that channel
rc = saEvtChannelOpen(evtLibHandle, &evtChannelName,
(SA_EVT_CHANNEL_PUBLISHER | SA_EVT_CHANNEL_SUBSCRIBER | SA_EVT_CHANNEL_CREATE),
(SaTimeT)SA_TIME_END, &evtChannelHandle);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failure opening event channel [0x%x] at %ld", rc, time(0L));
errorExit(rc);
}

rc = saEvtEventSubscribe(evtChannelHandle, NULL, 1);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to subscribe to event channel [0x%x]",rc);
errorExit(rc);
}
</pre></code>
|}

Within the above code we open the channel synchronously. We pass the handle we got back from <code>saEvtInitialize</code>, the channel name we defined previously, flags that indicate this process is subscribing to the channel and it's a global channel, and that the channel should be created if it's not already there, a timeout value of "forever", and the address of the location where the channel handle should be stored. Then, we subscribe to a specific event stream on the event channel. The <code>EVENT_TYPE</code> constant is defined in <code>common/common.h</code> as 5432. This value is used by the event publisher when it sends events. The constant 1 being passed simply identifies this specific subscription on this channel. This value will be passed to our event delivery callback function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
static void
csa112Comp_appEventCallback(SaEvtSubscriptionIdT subscriptionId,
SaEvtEventHandleT eventHandle,
SaSizeT eventDataSize)
{

SaAisErrorT rc = SA_AIS_OK;
static ClPtrT resTest = 0;
clprintf(CL_LOG_SEV_INFO,"We've got an event to receive\n");

if (resTest != 0)
{
clHeapFree((char *)resTest);
resTest = 0;
}
resTest = clHeapAllocate(eventDataSize + 1);

if (resTest == 0)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to allocate space for event");
return;
}
rc = saEvtEventDataGet(eventHandle, resTest, &eventDataSize);

if (rc!= SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to get event data [0x%x]",rc);
return;
}

*(((char *)resTest) + eventDataSize) = 0;
clprintf(CL_LOG_SEV_INFO,"received event: %s\n", (char *)resTest);
}
</pre></code>
|}

The event delivery callback function is named <code>csa112Comp_appEventCallback</code>. It checks whether our incoming data buffer needs to be deallocated. If there is a buffer, it deallocates it and then allocates enough data to receive the incoming event data. Then, we extract the data from the event into the newly allocated buffer using <code>clEventDataGet</code>. Finally, we print the event data we received using <code>clprintf</code> which is another member of Clovis' OS Abstraction Layer. As its name and usage suggest, it is the OSAL replacement for printf.

'''Note:'''

Before building the project,copy the common directory which can be found under <code><eval_dir>/src/app</code> to the working area
<code><pre># cp -r <eval_dir>/src/app/common .</pre></code>

===csa212 SA Forum Compliant Event Subscription===

csa212 demonstrates the usage of SA Forum's Event Service. This sample application does not deviate functionally from csa112. The differences in code are due to using SA Forum data types (structures) and APIs , as presented in the following two tables. (Note we have not repeated data types and APIs covered previously.)

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum Data Types with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum Data Types
!OpenClovis Data Types
|-
|SaEvtHandleT
|ClEventInitHandleT
|-
|SaEvtChannelHandleT
|ClEventChannelHandleT
|-
|SaEvtCallbacksT
|ClEventCallbacksT
|-
|SA_EVT_CHANNEL_SUBSCRIBER
|CL_EVENT_CHANNEL_SUBSCRIBER
|-
|SA_EVT_CHANNEL_CREATE
|CL_EVENT_CHANNEL_CREATE
|-
|SA_TIME_END
|CL_RMD_TIMEOUT_FOREVER
|}

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum APIs with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum APIs
!OpenClovis APIs
|-
|SaEvtInitialize
|ClEventInitialize
|-
|saEvtChannelOpen
|clEventChannelOpen
|-
|saEvtEventSubscribe
|clEventExtSubscribe
|-
|saEvtEventDataGet
|clEventDataGet
|-
|saEvtChannelClose
|clEventChannelClose
|-
|saEvtFinalize
|clEventFinalize
|}

===How to Run csa212 and What to Observe===

<ol>
<li>Start example csa212 in the same manner that we have started previous examples, with the SAFplus Platform Console.(Unlock csa212SGI0 instead of csa112SGI0 to run csa212).
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa212SGI0
</pre></code>

Looking at the log file for this example you should see the following.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa212CompI3Log.latest
|-
|<code><pre>
Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00001 : INFO) Component [csa212CompI3] : PID [10366]. Initializing

Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00002 : INFO) IOC Address : 0x4

Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00003 : INFO) IOC Port : 0x80

Fri Oct 1 13:15:31.389 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00004 : INFO) Component [csa212CompI3] : PID [10366]. CSI Set Received

</pre></code>
|}

<li>Now unlock the application with:
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa212SGI0
</pre></code>

At this point you should see the following in the log.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa212CompI3Log.latest
|-
|<code><pre>
Fri Oct 1 13:15:31.389 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00012 : INFO) csa212: ACTIVE state requested; activating service

</pre></code>
|}

Thats all there is to this example. What you are looking at in the log is the output of our event listener. It doesn't appear very interesting because we have not yet written an event publisher that will give the program something to output. We'll do that in the next example (csa213).

<li>At this point we can shut down our example in the usual fashion.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa212SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa212SGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>
</ol>
[[File:OpenClovis_Note.png]]When running model csa212 you will not see the output described for the the amsLockAssignment and amsUnlock commands.

===Summary and References===

We've seen how to create a basic event subscriber application using Clovis' event manager library. For further reading check the Clovis SAFplus Platform API reference guide, specifically the section on the event manager. Also, the header file: <code>clEventExtApi.h</code> should be helpful.

Doc:latest/evalguide/csa112

2014-11-14T11:09:10Z

Prasad: /* Code */

==csa112 Event Subscription==

An event service is an communications mechanism organised around the categories of data rather then senders and receivers. A "publisher" posts a message to a well-known event channel and all "subscribers" receive the message. Publishers and subscribers do not need to know who each other are; they need only know the event channel name.

As the Messaging service is similar to mail, the Event service is similar to a bulletin board.

===Objective===

The objective of csa112 is to learn how to use the SAFplus Platform event service to subscribe to events and to extract the relevant information from the events received by subscription.

===What you will learn===

You will learn:
*how to initialize the event library
*how to subscribe to events
*how to receive events
*how to extract the event data

The SAFplus Event service is SA-Forum compliant and this tutorial expects that you will refer to the relevant SA-Forum document for an in-depth description of the APIs used.

===Code===

One difference to note between this application and previous ones is that this application will not have a main loop in <code>initializeAmf</code>. Instead we will do our work in callback code. This means that when we return from <code>initializeAmf</code> we won't exit the application.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
SaNameT evtChannelName =
{
sizeof EVENT_CHANNEL_NAME -1,
EVENT_CHANNEL_NAME
};

SaEvtChannelHandleT evtChannelHandle = 0;
SaEvtHandleT evtLibHandle=0;
SaEvtEventHandleT eventHandle=0;

static void csa112Comp_appEventCallback( SaEvtSubscriptionIdT subscriptionId,
SaEvtEventHandleT eventHandle,
SaSizeT eventDataSize);
</pre></code>
|}

Here we define variables to hold the payload of our event. Note the initialization of the <code>evtChannelName</code>. The length is set to the length of the <code>EVENT_CHANNEL_NAME</code> string WITHOUT including the <code>null</code> terminator.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{
....

const SaEvtCallbacksT evtCallbacks =
{
NULL, /* Event open callback */
csa112Comp_appEventCallback /* Event delivery callback */
};
...

// publish our event callbacks
rc = saEvtInitialize(&evtLibHandle, &evtCallbacks, &evtVersion);
...
</pre></code>
|}

We initialize the OpenClovis Event Manager with <code>saEvtInitialize</code>. We pass the address of the variable where we want the event handle stored. We pass the address of our event callback functions structure. Note that the only event callback function that we specify is <code>csa112Comp_appEventCallback</code>. We do not specify the other callback which is the Asynchronous channel open callback. We specify <code>NULL</code> for that field of <code>evtCallbacks</code> because we don't open our event channel asynchronously.:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
void
initializeAmf(void)
{

....

// Open an event chanel so that we can subscribe to events on that channel
rc = saEvtChannelOpen(evtLibHandle, &evtChannelName,
(SA_EVT_CHANNEL_PUBLISHER | SA_EVT_CHANNEL_SUBSCRIBER | SA_EVT_CHANNEL_CREATE),
(SaTimeT)SA_TIME_END, &evtChannelHandle);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failure opening event channel [0x%x] at %ld", rc, time(0L));
errorExit(rc);
}

rc = saEvtEventSubscribe(evtChannelHandle, NULL, 1);
if (rc != SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to subscribe to event channel [0x%x]",rc);
errorExit(rc);
}
</pre></code>
|}

Within the above code we open the channel synchronously. We pass the handle we got back from <code>saEvtInitialize</code>, the channel name we defined previously, flags that indicate this process is subscribing to the channel and it's a global channel, and that the channel should be created if it's not already there, a timeout value of "forever", and the address of the location where the channel handle should be stored. Then, we subscribe to a specific event stream on the event channel. The <code>EVENT_TYPE</code> constant is defined in <code>common/common.h</code> as 5432. This value is used by the event publisher when it sends events. The constant 1 being passed simply identifies this specific subscription on this channel. This value will be passed to our event delivery callback function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| main.c
|-
|<code><pre>
static void
csa112Comp_appEventCallback(SaEvtSubscriptionIdT subscriptionId,
SaEvtEventHandleT eventHandle,
SaSizeT eventDataSize)
{

SaAisErrorT rc = SA_AIS_OK;
static ClPtrT resTest = 0;
clprintf(CL_LOG_SEV_INFO,"We've got an event to receive\n");

if (resTest != 0)
{
clHeapFree((char *)resTest);
resTest = 0;
}
resTest = clHeapAllocate(eventDataSize + 1);

if (resTest == 0)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to allocate space for event");
return;
}
rc = saEvtEventDataGet(eventHandle, resTest, &eventDataSize);

if (rc!= SA_AIS_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to get event data [0x%x]",rc);
return;
}

*(((char *)resTest) + eventDataSize) = 0;
clprintf(CL_LOG_SEV_INFO,"received event: %s\n", (char *)resTest);
}
</pre></code>
|}

The event delivery callback function is named <code>csa112Comp_appEventCallback</code>. First it checks that the running variable is not zero and that the High Availability State is <code>CL_AMS_HA_STATE_ACTIVE</code>, otherwise it returns, dropping the event in the bit bucket. Next it checks whether our incoming data buffer needs to be deallocated. If there is a buffer, it deallocates it and then allocates enough data to receive the incoming event data. Then, we extract the data from the event into the newly allocated buffer using <code>clEventDataGet</code>. Finally, we print the event data we received using <code>clprintf</code> which is another member of Clovis' OS Abstraction Layer. As its name and usage suggest, it is the OSAL replacement for printf.

'''Note:'''

Before building the project,copy the common directory which can be found under <code><eval_dir>/src/app</code> to the working area
<code><pre># cp -r <eval_dir>/src/app/common .</pre></code>

===csa212 SA Forum Compliant Event Subscription===

csa212 demonstrates the usage of SA Forum's Event Service. This sample application does not deviate functionally from csa112. The differences in code are due to using SA Forum data types (structures) and APIs , as presented in the following two tables. (Note we have not repeated data types and APIs covered previously.)

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum Data Types with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum Data Types
!OpenClovis Data Types
|-
|SaEvtHandleT
|ClEventInitHandleT
|-
|SaEvtChannelHandleT
|ClEventChannelHandleT
|-
|SaEvtCallbacksT
|ClEventCallbacksT
|-
|SA_EVT_CHANNEL_SUBSCRIBER
|CL_EVENT_CHANNEL_SUBSCRIBER
|-
|SA_EVT_CHANNEL_CREATE
|CL_EVENT_CHANNEL_CREATE
|-
|SA_TIME_END
|CL_RMD_TIMEOUT_FOREVER
|}

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum APIs with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum APIs
!OpenClovis APIs
|-
|SaEvtInitialize
|ClEventInitialize
|-
|saEvtChannelOpen
|clEventChannelOpen
|-
|saEvtEventSubscribe
|clEventExtSubscribe
|-
|saEvtEventDataGet
|clEventDataGet
|-
|saEvtChannelClose
|clEventChannelClose
|-
|saEvtFinalize
|clEventFinalize
|}

===How to Run csa212 and What to Observe===

<ol>
<li>Start example csa212 in the same manner that we have started previous examples, with the SAFplus Platform Console.(Unlock csa212SGI0 instead of csa112SGI0 to run csa212).
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa212SGI0
</pre></code>

Looking at the log file for this example you should see the following.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa212CompI3Log.latest
|-
|<code><pre>
Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00001 : INFO) Component [csa212CompI3] : PID [10366]. Initializing

Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00002 : INFO) IOC Address : 0x4

Fri Oct 1 13:14:16.935 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00003 : INFO) IOC Port : 0x80

Fri Oct 1 13:15:31.389 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00004 : INFO) Component [csa212CompI3] : PID [10366]. CSI Set Received

</pre></code>
|}

<li>Now unlock the application with:
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa212SGI0
</pre></code>

At this point you should see the following in the log.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa212CompI3Log.latest
|-
|<code><pre>
Fri Oct 1 13:15:31.389 2010 (PayloadNodeI1.10366 : csa212CompEO.---.---.00012 : INFO) csa212: ACTIVE state requested; activating service

</pre></code>
|}

Thats all there is to this example. What you are looking at in the log is the output of our event listener. It doesn't appear very interesting because we have not yet written an event publisher that will give the program something to output. We'll do that in the next example (csa213).

<li>At this point we can shut down our example in the usual fashion.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa212SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa212SGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>
</ol>
[[File:OpenClovis_Note.png]]When running model csa212 you will not see the output described for the the amsLockAssignment and amsUnlock commands.

===Summary and References===

We've seen how to create a basic event subscriber application using Clovis' event manager library. For further reading check the Clovis SAFplus Platform API reference guide, specifically the section on the event manager. Also, the header file: <code>clEventExtApi.h</code> should be helpful.

Doc:latest/tutorial

2014-11-14T09:10:56Z

Prasad: /* Resource Editor View */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor1.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Component_Editor1.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

[[File:Make_Image_TIPC_Specific.png|frame|center| '''Make Images Configuration TIPC Specific Details''' ]]

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
</ul>

[[File:Make_Images_General.png|frame|center| '''Make Images Configuration General Details''' ]]

<ul>
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Node_Instance_Details_csa101SUI0.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Node_Instance_Details_csa101I0.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Service_Group_List_csa101SGI0.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Associated_Service_Units.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Service_Instance_List_csa101SII0.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Component_Service_Instance_List_csa101CSII0.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T09:10:40Z

Prasad: /* Component Editor View */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Component_Editor1.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

[[File:Make_Image_TIPC_Specific.png|frame|center| '''Make Images Configuration TIPC Specific Details''' ]]

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
</ul>

[[File:Make_Images_General.png|frame|center| '''Make Images Configuration General Details''' ]]

<ul>
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Node_Instance_Details_csa101SUI0.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Node_Instance_Details_csa101I0.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Service_Group_List_csa101SGI0.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Associated_Service_Units.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Service_Instance_List_csa101SII0.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Component_Service_Instance_List_csa101CSII0.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

File:Resource Editor1.png

2014-11-14T09:09:59Z

Prasad:

File:Component Editor1.png

2014-11-14T09:09:45Z

Prasad:

Doc:latest/tutorial

2014-11-14T09:03:01Z

Prasad: /* Creating the csa101 Images */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

[[File:Make_Image_TIPC_Specific.png|frame|center| '''Make Images Configuration TIPC Specific Details''' ]]

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
</ul>

[[File:Make_Images_General.png|frame|center| '''Make Images Configuration General Details''' ]]

<ul>
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Node_Instance_Details_csa101SUI0.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Node_Instance_Details_csa101I0.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Service_Group_List_csa101SGI0.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Associated_Service_Units.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Service_Instance_List_csa101SII0.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Component_Service_Instance_List_csa101CSII0.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

File:Make Images General.png

2014-11-14T08:58:46Z

Prasad:

File:Make Image TIPC Specific.png

2014-11-14T08:58:30Z

Prasad:

Doc:latest/tutorial

2014-11-14T08:54:27Z

Prasad: /* Component Service Instance Instance */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Node_Instance_Details_csa101SUI0.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Node_Instance_Details_csa101I0.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Service_Group_List_csa101SGI0.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Associated_Service_Units.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Service_Instance_List_csa101SII0.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Component_Service_Instance_List_csa101CSII0.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:53:51Z

Prasad: /* Service Instance Instance */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Node_Instance_Details_csa101SUI0.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Node_Instance_Details_csa101I0.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Service_Group_List_csa101SGI0.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Associated_Service_Units.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Service_Instance_List_csa101SII0.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:52:11Z

Prasad: /* Service Group Instance */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Node_Instance_Details_csa101SUI0.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Node_Instance_Details_csa101I0.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Service_Group_List_csa101SGI0.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Associated_Service_Units.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:50:45Z

Prasad: /* Component Instance */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Node_Instance_Details_csa101SUI0.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Node_Instance_Details_csa101I0.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:50:05Z

Prasad: /* Service Unit Instance */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Node_Instance_Details_csa101SUI0.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:48:20Z

Prasad: /* Node Instance */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Node_Instance_Details_SCNodeI0.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:45:34Z

Prasad: /* Building the csa101 Code */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Build_Configuration.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

File:Build Configuration.png

2014-11-14T08:44:57Z

Prasad:

Doc:latest/tutorial

2014-11-14T08:43:17Z

Prasad: /* Generating the csa101 Code */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Clovis_Workspace_Generate_Source.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

File:Clovis Workspace Generate Source.png

2014-11-14T08:42:42Z

Prasad:

Doc:latest/tutorial

2014-11-14T08:32:58Z

Prasad: /* Configuring Physical Instances */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:AMF_Configuration.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Service_Group_List.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:AMF_Configuration_Final.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:30:23Z

Prasad: /* Creating Node Instances */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:Tutorial_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Node_Instance_List.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Tutorial_AMFSGWizardDetails.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_AMSConfigDetails.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:28:01Z

Prasad: /* Configuring the SAF Component */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:SAF_Component_Details.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Command_Line_Argument_Details.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:Tutorial_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Tutorial_AMFNodeWizardDetails.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Tutorial_AMFSGWizardDetails.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_AMSConfigDetails.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:26:58Z

Prasad: /* Configuring the Service Instance */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Service_Instance_Details.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Tutorial_CommandLineArgs.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:Tutorial_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Tutorial_AMFNodeWizardDetails.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Tutorial_AMFSGWizardDetails.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_AMSConfigDetails.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

File:Service Instance Details.png

2014-11-14T08:26:21Z

Prasad:

Doc:latest/tutorial

2014-11-14T08:24:24Z

Prasad: /* Configuring the Service Group */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Service_Group_Details.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Tutorial_ServiceInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Tutorial_CommandLineArgs.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:Tutorial_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Tutorial_AMFNodeWizardDetails.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Tutorial_AMFSGWizardDetails.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_AMSConfigDetails.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:21:55Z

Prasad: /* Resource Editor View */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Resource_Editor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Tutorial_ServiceGroupDetails.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Tutorial_ServiceInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Tutorial_CommandLineArgs.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:Tutorial_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Tutorial_AMFNodeWizardDetails.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Tutorial_AMFSGWizardDetails.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_AMSConfigDetails.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:20:51Z

Prasad: /* The SAFplus Platform IDE Perspective */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Clovis_Workspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ResourceEditor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Tutorial_ServiceGroupDetails.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Tutorial_ServiceInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Tutorial_CommandLineArgs.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:Tutorial_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Tutorial_AMFNodeWizardDetails.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Tutorial_AMFSGWizardDetails.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_AMSConfigDetails.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:19:27Z

Prasad: /* Creating the Sample Project */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:New_Project_Wizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Clovis_System_Project.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Add_New_Blade_Type.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Add_New_SAF_Node_Type.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:SAF_Service_Type_Name.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Tutorial_GettingStartedIDE_ClovisWorkspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ResourceEditor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Tutorial_ServiceGroupDetails.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Tutorial_ServiceInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Tutorial_CommandLineArgs.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:Tutorial_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Tutorial_AMFNodeWizardDetails.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Tutorial_AMFSGWizardDetails.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_AMSConfigDetails.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

Doc:latest/tutorial

2014-11-14T08:12:42Z

Prasad: /* Launching the SAFplus Platform IDE */

==Preface==
The ''SAFplus Platform Sample Application Tutorial'' is a comprehensive tutorial designed to highlight the steps involved in using SAFplus software to design and build a high availability system. In this tutorial you will learn to:
* Design a model using the SAFplus IDE
* Generate code from this model to provide middleware support
* Customize this code for a particular application
* Build and deploy the customized code
* Run the system to see the SAFplus Platform software in action

===Audience===
 ''SAFplus Platform Sample Application Tutorial'' is designed for system integrators, designers, and system architects. To use SAFplus Platform, you should be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You should also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

 This document assumes that you have installed the SAFplus Platform SDK, following the installation steps found in the ''SAFplus Platform Installation Guide''.

===Documentation Conventions===
This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.
{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names.

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal output.

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths.

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

As mentioned in the ''SAFplus Platform Installation Guide'' the default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===Related Documents===
For additional information about OpenClovis products, please refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform Release Notes]]''' provides information about the software and the hardware required to install OpenClovis SAFplus Availability/Scalability Platform and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''[[Doc:latest/safcompliance | SAFplus Platform SA-Forum Compliance]]''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform Evaluation System User Guide]]''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform Log Tool User Guide]]''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===
OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com.

===Documentation Feedback===
We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

==Our Example: The csa101 System==
The ''SAFplus Platform Sample Application Tutorial'' will take you through a series of examples each introducing a key concept of the product. Each example builds on the example before it so it is important to go through them in order. The examples are named so that it is easy to determine their sequence. The examples all begin with the letters '''csa''' (standing for Clovis Sample Application) and end with a number. Our first example will be '''csa101'''.

The purpose of our first example is to highlight basic component management. It introduces the basic skeleton of a SAFplus Platform based application component and illustrates how it interacts with the System. It demonstrates basic component registration and life-cycle management.

We will keep this first example very simple. It will consist of the SAFplus Platform running a small component named '''csa101'''. All that this component will do is continuously print 'Hello World!' to a log file. While this component is not very exciting, it will allow us to easily see when the application is in a running state and when it is not. This will allow us to focus on the infrastructure of SAFplus Platform and how the application interfaces with it.

For this example we will assume that we have a chassis with five slots. We will have one type of blade in our example, a '''System Controller'''.
 [[File:OpenClovis_Note.png]]With the type of model we are developing we would typically define two blade types to install in these slots. The first blade type would be a '''System Controller''' blade (which is responsible for running the SAFplus Platform software which manages application startup, shutdown, failover, etc.) and the second blade type would be a '''Payload''' blade (which is responsible for running our custom '''csa101''' application). However, for the purpose of simplifying the deployment of our system, we will define only the '''System Controller''' blade type and have both the SAFplus Platform and component application run on this one blade. This will allow the example to be run on a single PC.

==Creating the csa101 Model==
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. The project area can hold multiple models allowing you to manage all of your models in one location. All the models in the same project area share the same SAFplus Platform source tree. This way any modifications made to the SAFplus Platform source tree are re-used across all the models that were created in that project area.

You create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE. For example with a bash shell,
<code><pre>
# export PATH=$PATH:$install_dir/6.1/sdk/bin
# cl-ide
</pre></code>
or
<li>Execute the command
<code><pre>
# <install_dir>/6.1/sdk/bin/cl-ide
</pre></code>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

[[File:Workspace_Launcher.png|frame|center| '''SAFplus Platform IDE Workspace Launcher''' ]]

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code.
<ul>
<li>Select the workspace and click '''OK''' to launch SAFplus Platform IDE as illustrated in the Figure [[#SAFplus Platform IDE Welcome Screen | SAFplus Platform IDE Welcome Screen]].
</ul>

[[File:IDE_Welcome_Screen.png|frame|center| '''SAFplus Platform IDE Welcome Screen''' ]]

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

[[File:Tutorial_GettingStartedIDE_NewProjectWizard.png|frame|center| '''New Project Wizard''' ]]

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

[[File:Tutorial_NewProject.png|frame|center| '''Clovis System Project''' ]]

Enter the following information:

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 [[File:OpenClovis_Note.png]]Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''SDK Location''': Enter the location where the SAFplus Platform SDK was installed. For e.g. if the SDK was installed at location /opt/clovis, then the SDK location is /opt/clovis/sdk-<version>.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 [[File:OpenClovis_Note.png]]This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 or above is installed on your system. If Python 2.5.0 or above was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/6.1/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Tutorial_AddBlade.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Tutorial_AddNode.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:Tutorial_DefineProgramNames.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa101 that continously prints "Hello World!").

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa101' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

===Viewing the Model===

====The SAFplus Platform IDE Perspective====
Once the wizard pages are closed you will be returned to the main IDE view also known as the '''SAFplus Platform IDE Perspective'''. On the left hand side of this view you will see the '''Clovis Workspace''' pane which contains the new project you just created with all project related files and folders. The folders are displayed based on your filter settings. With the default filter settings, the folders shown in Figure [[#Clovis Workspace|Clovis Workspace]] is displayed in the '''Clovis Workspace''' pane. For information about filter settings, refer ''SAFplus Platform IDE User Guide''.

[[File:Tutorial_GettingStartedIDE_ClovisWorkspace.png|frame|center|Clovis Workspace]]

By default, the '''Resource''' and '''Component''' Editor views are available for the created project. To view them, click '''Clovis''' on the menu bar at the top of the screen and select '''Resource Editor''' or '''Component Editor''' from the menu. You can also click '''Resource Editor''' or '''Component Editor''' icons from the tool bar as shown in Figure [[#SAFplus Platform IDE Tool Bar | SAFplus Platform IDE Tool Bar]].

[[File:Tutorial_Toolbar.png|frame|center| '''SAFplus Platform IDE Tool Bar''' ]]

====Resource Editor View====
The '''Resource Editor''' shows the types of physical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Resource Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ResourceEditor.png|frame|center| '''SAFplus Platform Resource Editor''' ]]

This editor always has a '''Chassis''' object which is the root of all other objects in the editor. In our case it also has the '''SysBlade''' blade type that we created through the '''Project Creation Wizard'''. You will also notice that the '''SysBlade''' is attached to the '''Chassis''' using a '''Composition''' relationship indicating that '''SysBlade'''s reside within the '''Chassis'''.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Resource Editor''' view see ''SAFplus Platform IDE User Guide''.

====Component Editor View====
The '''Component Editor''' shows the types of logical objects in our system. It gives us a place to create new objects and interact with the objects that already exist. The '''Component Editor''' view for our model should look similar to the following figure.

[[File:Tutorial_ComponentEditor.png|frame|center| '''SAFplus Platform Component Editor''' ]]

This editor always has a '''Cluster''' object which is the root of all other objects in the editor. In our case it also has the '''SCNode''' node type and the '''csa101''' SAF Service Type (a combination of Service Group, Service Unit, Service Instance, Component Service Instance, and SAF Component) that we created through the '''Project Creation Wizard'''. These have all been automatically attached in a way that makes a working model.

On the right hand side of the editor view you will see the '''Palette''' which can be expanded and collapsed. Expanding the '''Palette''' you will see the list of objects that can be dragged onto the editor view to add to our model. Once an object is on the editor view you can view and change its properties by right clicking on the object and selecting '''Properties...''' from the context menu.

For more information about the '''Component Editor''' view see ''SAFplus Platform IDE User Guide''.

===Configuring the Components===
The '''New Project Wizard''' that we used to create our project configured the system using the most common options. We will have to make a few changes to this model in order for our example to work. We will make these changes in the '''Component Editor''' view.

In the Component Editor you will notice seven different objects that were created by the wizard. The first two of these are:
<ul>
<li>Cluster: The root object of all other objects in the Component Editor view.
<li>SCNode: This is the SAF Node Type that we specified during project creation.
</ul>

The next five objects all make up the Program or SAF Service Type that we specified on the last dialog of the New Project Wizard. These objects are:

<ul>
<li>csa101SG: This is the Service Group representing our high availability software component.
<li>csa101SU: This is the Service Unit that is logically associated with the SCNode SAF Node Type.
<li>csa101SI: This is the Service Instance
<li>csa101CSI: This is the Component Service Instance
<li>csa101: This is the SAF Component which represents our program or executable.
</ul>

We will be making changes to the Service Group (csa101SG), the Service Instance (csa101SI), and the SAF Component (csa101).

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Tutorial_ServiceGroupDetails.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our simple model (which only has one node) we are not going to rely on any failover recovery so change the '''Redundancy Model''' to 'No Redundancy' as shown.
 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa101 application will not yet start printing "Hello World!".

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the Service Instance====
To make changes to the Service Instance double-click on the box titled '''csa101SI'''. The '''Service Instance Details''' dialog is displayed.

[[File:Tutorial_ServiceInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

<ul>
<li>The only change we want to make here is to the '''Number of standby assignments'''. This value represents the number of components that will be waiting to take over during a node failure and goes hand-in-hand with the '''Redundancy Model''' that we selected for the Service Group. Since we selected 'No Redundancy' for our '''Redundancy Model''' we need to set this value to 0...since we are not supporting any failover in this model.

<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa101'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

<ul>
<li>To add command line parameters click the '''Edit...''' button corresponding to the '''Command line Arguments''' label.
</ul>

The '''Command line Argument Details''' dialog is displayed.

[[File:Tutorial_CommandLineArgs.png|frame|center| '''Command line Argument Details''' ]]

<ul>
<li>Click the '''New''' button to add a new value to the list.
<li>Click on the new value in the list and it will become editable. Change the value to '''-p'''.
<li>Click the '''OK''' button to save and close the dialog.
<li>Click the '''OK''' button on the '''SAF Component Details''' dialog to commit the changes to the SAF Component and close the dialog.
<li>Save the component model using the '''File > Save''' menu item.
</ul>

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' dialog is displayed.

[[File:Tutorial_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

You will note from the instructions on this page that the physical instances representing the objects in our model can be created manually or by using wizards. Using the wizards will save us both typing and time so we will use these instead of creating each instance manually.

====Creating Node Instances====
First we will create actual instances of the Node Types (in our case only one Node Type...SCNode) we created in our model.

<ul>
<li>Double-click AMF Configuration in the left hand pane. The Node Instance List appears.
<li>Click on Node Instance List. The right hand pane displays the fields we must fill out to create our node instance.
</ul>

In the right hand pane:

<ul>
<li>Select SCNode for the '''Node Type'''.
<li>Select SysBlade for the '''Blade type'''.
<li>Enter 1 for the '''Node Count'''.
</ul>

The complete form should look like the following.

[[File:Tutorial_AMFNodeWizardDetails.png|frame|center| '''Node Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our node instance.
</ul>

Expanding the '''Node Instance List''' branch of the '''AMF Configuration''' tree in the left-hand pane reveals a new node instance named SCNodeI0 (indicating SCNode Instance 0).

====Creating Service Group Instances====
Now we will create actual instances of the Service Groups that we defined in our model.

<ul>
<li>Click on Service Group List. The right hand pane displays the fields we must fill out to create our service group instance.
</ul>

In the right hand pane:

<ul>
<li>Select csa101SG (the only service group type we defined) for the '''Service Group Type'''.
*The '''Associated Node Instances''' list will be populated with all of the node instances that can be associated with the selected service group type.
<li>Select SCNodeI0 from the '''Associated Node Instances''' list.
</ul>

The completed form should look like the following.

[[File:Tutorial_AMFSGWizardDetails.png|frame|center| '''Service Group Wizard Details''' ]]

<ul>
<li>Click the '''Create Instance Tree''' button to create our service group instance.
</ul>

 
If you now completely expand the '''AMF Configuration''' branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_AMSConfigDetails.png|frame|center| '''AMF Configuration Instance Details''' ]]

Notice that not only have the wizards created the node and service group instances for you, they have also filled out the entire instance tree. This was accomplished based on two key sets of information. The first of these is the association that was made between the service group type and the node instance in the '''Service Group Wizard'''. The second set of information is the component model that we created through the New Project Wizard and the Component Editor.

 [[File:OpenClovis_Note.png]]For more information regarding the specific properties of the generated instances see [[#Appendix B: AMF Configuration Instance Details|Appendix B: AMF Configuration Instance Details]].

 
Thats it. We are done modelling the csa101 example!
<ul>
<li>Click the OK button to commit our changes and close the dialog.
</ul>
Now its time to generate the framework code.

==Generating the csa101 Code==
In this step we generate the source code for our example. The code that will be created is the framework code that handles all of the low level functionality provided by SAFplus Platform.

To generate the source code go to the '''Project''' menu and select '''Generate Source'''. Several progress dialogs will appear and after a few seconds code generation will be complete.

The source code and configuration XML files are generated and placed in subdirectories of the '''Project Area Location''' that we specified in the '''New Project Wizard'''. You can review this location by using the '''Project > Properties''' menu to get to the '''Project Properties''' dialog and then selecting '''Clovis System Project''' in the left hand pane.

You can review the generated code from within the SAFplus Platform IDE. To do this go to the '''Clovis Workspace''' pane and expand the '''SampleModel''' node. The node tree should look like the following.

[[File:Tutorial_CWCodeTree.png|frame|center| '''Clovis Workspace Code Tree''' ]]

The code of particular interest to our example is in the SampleModel/src/app/csa101 branch of the tree. This is the code for our csa101 example. The csa101 example consist of one C module (<code>main.c</code>). There is also a make file that will be used for building the application. The <code>main.c</code> file implements our 'Hello World!' application.

 [[File:OpenClovis_Note.png]]If you run code generation a second time you will be presented with a dialog box asking if you would like to make a backup copy of the existing source code before proceeding. You can answer No to this dialog.

==Customizing the csa101 Code==
While the code that was generated in the previous section can be built and run we want to make some changes to it so that we can easily see what our example is doing. For our example we will be changing one source file (<code>main.c</code>) and two make files.
 [[File:OpenClovis_Note.png]]In a real production situation this is the point where you would customize the code to perform the specific tasks of your product.

You will notice in the C file that there are several places where you see the following comment block.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

/*
---BEGIN_APPLICATION_CODE---
*/

// ...

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Makefiles have a similar convention but with a slightly different syntax.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Makefile
|-
|<code><pre>

# ---BEGIN_APPLICATION_CODE---

# ---END_APPLICATION_CODE---
</pre></code>
|}

These are sections of the file where it is safe to enter custom application code without having to worry about that code being overwritten if you were to again perform '''Generate Source''' for your model. This is important since the typical development cycle is an iterative process where you will return to the IDE to make modifications to your model.

To simplify the process of building and running the csa101 example, OpenClovis, Inc. has already made the necessary code customizations and shipped this code with the SAFplus Platform SDK. At this point you can simply replace the generated source files with these customized versions to avoid typing in the changes. We will go over each customization below and explain what was done.

To replace the generated files with the customized versions shipped with the SAFplus Platform SDK follow these instructions.
 [[File:OpenClovis_Note.png]] The sample applications containing the csa101 example can be found under the installation directory at <code><install_dir>/6.1/sdk/src/examples/eval</code>. We will refer to this directory in the remaining of this section as <code><eval_dir></code>.

<ol>
<li>Exit the SAFplus Platform IDE using the '''File > Exit''' menu item. If you are prompted to save changes before exiting answer yes.
<li>Navigate to the source code work area.
<code><pre># cd /home/clovis/projectarea1/ide_workspace/SampleModel/src/app</pre></code>
<li>Using your favorite editor open the file <code>Makefile</code> that resides in this directory. This is the application make file.
<li>Add the following line to this file within the first <code>BEGIN_APPLICATION_CODE</code> and <code>END_APPLICATION_CODE</code> comment block. This will instruct the build process to build our custom output library.
<code><pre>SUBDIRS += ev</pre></code>
<li>Save this file and exit the editor.
<li>Execute the following command to copy the output package to our working area.
<code><pre># cp -r <eval_dir>/src/app/ev .</pre></code>
<li>Navigate to the component code work area.
<code><pre># cd csa101</pre></code>
<li>Execute the following command to copy the csa101 source code.
<code><pre># cp <eval_dir>/src/app/csa101Comp/main.c .</pre></code>
<li>Execute the following command to copy the component make file.
<code><pre># cp <eval_dir>/src/app/csa101Comp/Makefile .</pre></code>
<li>Restart the SAFplus Platform IDE.
<code><pre># cl-ide</pre></code>
</ol>

===Customizing main.c===
The <code>main.c</code> file is the C module which will implement our 'Hello World!' behavior. We have to make changes in several parts of this file.
 [[File:OpenClovis_Note.png]]If you copied the files as instructed in the section above then these changes have already been made to the files. Use this section to review and understand the changes.

In the include section of this file we have added a new include for <code>ev.h</code>. This refers to a special output library that we copied to our work area in the previous section. This output library is used to redirect output from the application to a component specific log. This is purely cosmetic but it will allow us to easily monitor what is happening when we run our example.
Also, we change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10,
"MAI", CL_LOG_CONTEXT_UNSPECIFIED,__VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}

Next we define a static variables that will keep track of the state of our application and a function to aid in showing when the application is running.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
---BEGIN_APPLICATION_CODE---
*/

static int running = 0;

static char*
show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}

/*
---END_APPLICATION_CODE---
*/
</pre></code>
|}
The <code>running</code> flag will be used to indicate whether the current application is active or suspended.
The function <code>show_progress</code> returns a pointer to a c string with a number of spaces followed by a '.' character. The number of spaces in the string cycles from zero to an upper bound. This is used later on to provide visual indication of the progress of the application's output.

Next we have added a function <code>activeLoop</code> to print the output.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO, "csa101: Threaded Hello World! %s\n",
show_progress());
sleep(2);
}
return NULL;
}

</pre></code>
|}
Notice the while loop condition. This function uses the <code>running</code> variable that was initialized to 0. The loop will keep running until <code>running</code> is set to non-zero. The work of the application: printing "Hello World!" along with the progress indicator. Next the command <code>sleep(2)</code> simply sleeps for two seconds so as not to fill log files too quickly or completely swamp the CPU.

When <code>running</code> becomes non-zero, we return from the function.

Next, the log stream is initialized in the <code>initializeAmf</code> function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

/* Set up console redirection for demo purposes */
clEvalAppLogStreamOpen((ClCharT *)appName.value, &gEvalLogStream);
...
clprintf(CL_LOG_SEV_INFO,"csa101: Instantiated as component instance %s.", appName.value);
clprintf(CL_LOG_SEV_INFO,"%s: Waiting for CSI assignment...", appName.value);

/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}

Next we indicate log stream when we are exiting.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clEvalAppLogStreamClose(gEvalLogStream);
/*
* ---END_APPLICATION_CODE---
*/

</pre></code>
|}
This will cause <code>activeLoop</code> function to exit.
Next we will put in code to manage the state of our application.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
void safAssignWork(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

printCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

pthread_t thr;
clprintf(CL_LOG_SEV_INFO, "csa101: ACTIVE state requested; activating service\n");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa101: Standby state requested");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Acknowledging new state quiesced");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_INFO, "csa101: Signaling completion of QUIESCING");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
</pre></code>
|}
We have modified the <code>safAssignWork</code> callback function to let our application know what to do when the state changes. In the case where the state changes to <code>SA_AMF_HA_ACTIVE</code> we set the <code>running</code> variable to 1. This will cause our application to spawns a thread which calls <code>activeLoop</code> function and start printing the 'Hello World!' message. For any other state change we set the <code>running</code> variable to 0 which will cause the message to stop printing. For any state change we print out a message indicating the new state of the application.

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|main.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds))
{
saAmfDispatch(amfHandle, SA_DISPATCH_ALL);
}
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa101: Unthreaded Hello World! %s",
show_progress()); // Run the "active" code
}
else
{
clprintf(CL_LOG_SEV_INFO,"csa101: idle");
}
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===Customizing the Component MakeFile===
We have to make a small change to the component <code>MakeFile</code> so that it knows about our special output library during the build. To do this we add the following lines. This file is located in <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app</code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Component MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

SUBDIRS += ev

# ---END_APPLICATION_CODE---
</pre></code>
|}

===Customizing the Application MakeFile===
We have to make sure that our special output library is built along with our application. To do this we change the line listing the sudirectories to make as follows. This file is located in the directory <code>/home/clovis/projectarea1/ide_workspace/SampleModel/src/app/csa101</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|Application MakeFile
|-
|<code><pre>
# ---BEGIN_APPLICATION_CODE---

...

EXTRA_LDLIBS += $(LIB_DIR)/libeval.a

# ---END_APPLICATION_CODE---
</pre></code>
|}

We are finished customizing our application code!

==Building the csa101 Code==

Now that we have finished customizing the code it is time to build it. The build process is launched using the '''Project > Build Project''' menu item. Once selected the '''Build Configuration''' dialog appears.

[[File:Tutorial_BuildConfigDetails.png|frame|center| '''Build Configuration Details''' ]]

The '''Build Configuration''' dialog is used to gather specific information about the build we are about to perform. Using this dialog you can rebuild the same model using different cross builds, or including different chassis managers. We don't have to make any changes to this dialog since the default settings make sense for our sample application.

 [[File:OpenClovis_Note.png]]If you have prebuilt the SAFplus Platform libraries then you can check the '''Use pre built SAFplus''' checkbox and include the location of the prebuilt libraries. For more information about pre-building SAFplus Platform libraries, see ''SAFplus Platform SDK User Guide''.

 [[File:OpenClovis_Note.png]]The '''Include SNMP for North Bound Access''' control is checked by default. This just means that Net SNMP will be started along with our system. If you want end-to-end connectivity you will need to supply an SNMP Sub Agent and a MIB. See the ''SAFplus Platform SDK User Guide'' for more details.

 [[File:OpenClovis_Note.png]]In the '''Project''' menu if the '''Build Project''' entry is not highlighted, then click in the right pane i.e. '''Clovis Workspace''' pane and click the '''Project''' menu again. This not highlighting of the '''Build Project''' is because the '''Clovis Workspace''' is not selected properly because of moving focus to some other pane.

 Click the '''OK''' button to begin the build. If this is the first time that the project is being built, or if you have made changes to any setting on this screen, you will initially see a progress dialog indicating that the project is being configured. The configuration step is setting up the project for building. After the configuration has completed you will see a progress dialog indicating that the code is being built.

==Creating the csa101 Images==

Making the csa101 images will create software packages that can be deployed on target machines to run the example. The process of creating images is launched using the '''Project > Make Images''' menu item. Once selected the '''Make Images Configuration''' dialog appears.

[[File:Tutorial_MakeImagesConfigDetails.png|frame|center| '''Make Images Configuration Details''' ]]

The '''Make Images Configuration''' dialog is used to indicate information about the environment on which the images will be deployed. This information is used to tailor the images to run on that environment. Here we will make the following modificaiton.

<ul>
<li>Enter a value for the '''Trap IP'''. This value specifies where the SNMP sub-agent will send traps at runtime. This field is optional but if specified must be a valid IP address. Enter a value of '127.0.0.1' in this field.
<li>Enter a value for the '''TIPC Net ID'''. This value represents a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This field is required and should default to '1340'.
<li>Check the '''Create Node Specific Images''' and '''Package Images into Tarballs''' check boxes. This will create tarballs of the images making them easy to deploy to various machines.
<li>The table on this dialog will hold a row for each node instance defined in the model. In our case this is only one...SCNodeI0. For each of these instances we can define the slot number in the chassis on which the node will run and the network interface that the node will use for communication. In our case enter '1' for the Slot Number and 'eth0' for the Network Interface.
<li>Click '''OK''' to begin the make image process. A dialog box will appear and after a few seconds the the make images process will be complete.
</ul>

The images will be populated at <project_area>/target/SampleModel/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For our model containing one node (<code>SCNodeI0</code>) the following files and directories are generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+modules
| |+share
|-SCNodeI0.tgz
</pre></code>

The rest of the steps in this example are all done from the command line so we can exit the IDE. To do this use the '''File > Exit''' menu item.

==Deploying the csa101 Images==
Now that the image has been built we must deploy it so that we can run and observe our example. Since we are assuming that the example will be run on the same machine as the images were built this is a fairly trivial exercise. Use the following steps to deploy the runtime image.

<ol>
<li>First we create a directory where we will install the image. In our case we will use <code>/root/asp</code>.
<code><pre>
# cd /root
# mkdir asp
</pre></code>
<li>Next we navigate to that directory and untar the deployment package.
<code><pre>
# cd /root/asp
# tar xzvf /home/clovis/projectarea1/target/SampleModel/images/SCNodeI0.tgz
</pre></code>
</ol>

The System Controller is now installed and ready to run.

[[File:OpenClovis_Note.png]] If you were going to run the example on a machine other than the one where the images were built you would first copy the installation tarball to that machine before performing the above steps.

==Running the csa101 Example==
There are two parts to running the csa101 example. First we must start SAFplus Platform, and then we interact with the system components.

===Starting SAFplus Platform===

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>Run the following commands
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] This assumes that you are running the SAFplus Platform example on the same PC that you are executing these commands. If you are running SAFplus Platform on a different machine then you should first ssh to that machine before executing the commands.

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run on a machine which has firewall enabled. See the ''Environment Related Observation'' section of the ''SAFplus Platform Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default the network interface used by the Group Membership Service is set to eth0. During the make images phase of the tutorial we also set the ethernet interface for node SCNodeI0 to be eth0. During image generation these configuration parameters are written to two files in the deployment package.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

There may be an occasion where you want to switch this interface for a machine on which you are deploying. If you would like to switch this interface on a machine without having to go through the process of rebuilding and redeploying, you can edit these two files and change the 'eth0' references to the interface you would like to use.

===Interacting with the System Components===
Once SAFplus Platform is up and running the next step is to start csa101 by informing SAFplus Platform that it should start the application. The Evaluation System's model tells SAFplus Platform that csa101 is locked for instantiation. This means that the process will not be started when SAFplus Platform comes up. This method of starting csa's is used for the Evaluation System, allowing users to interact with csa's and clearly see their output/functionality. Usually this would not be the case with applications, where they would run when SAFplus Platform begins.

At this point it would help to be familiar with the Service Availability Forum's notions of Service Unit, Service Group, and administrative state. The Service Availability Forum's Application Interface Specification (available from http://www.saforum.org/) is a good place to start.

In brief, the sample applications in the Evaluation System are part of service units which in turn are part of service groups. Service groups (and the service units that make up the service groups) can be in "administrative" states which include "LockInstantiation", "LockAssignment", and "Unlocked". There are other states, but these are the ones we care about for the purposes of this Evaluation System. If the administrative state of a service unit is "LockInstantiation" then the application that is part of that service unit will not even be started. If the administrative state is "LockAssignment" then the application will be started, but it will not be assigned any work. If the administrative state is "Unlocked" then it will not only be started, but will have a workload assigned to it, which is to say that it will start doing work (or start providing service), rather than idly sit waiting for work.

The administrative state of a service unit or service group can change from LockInstantiation to LockAssignment, from LockAssignment to Unlocked, or back to LockInstantiation, from Unlocked to LockAssignment. A picture might help here:

 [[File:eval_AdministrativeStateDiagram.png|frame|center| '''Partial Service Group Administrative State Diagram''' ]]

As the figure shows, the administrative state of a service unit (or service group) can change from "LockInstantiation" to "LockAssignment" and from there to "Unlocked", or back to "LockInstantiation". One way to change the administrative state of a service group is with the SAFplus Platform Console command line interface.

To use the SAFplus Platform Console:
<ol>
<li> Open a terminal on the Development Machine. (Or ssh into System Controller node as root, if you are running SAFplus Platform on a machine other than the development machine.)
<li> Change to image bin directory: <code><pre># cd /root/asp/bin</pre></code>

<li> Start the SAFplus Platform Console <code><pre># ./asp_console</pre></code>

<li> From within the SAFplus Platform Console: <code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

The above changes the administrative state of the group csa101SGI0 from "locked-for-instantiation" to "locked-for-assignment".
 [[File:OpenClovis_Note.png]]For the command <code>cli[Test]-> setc 1</code>, the 1 represents the physical slot number of the System Controller within the Chassis. Remember that we set our System Controller to be in slot 1 in the make images dialog.

<li>Now lets tail the application log file so that we can see whats going on. In another window, as root, run:
<code><pre>
# tail -f /root/asp/var/log/csa101I0Log.latest
</pre></code>

You should see the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00001 : INFO)
Component [csa101I0] : PID [10950]. Initializing

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00002 : INFO)
IOC Address : 0x1

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00003 : INFO)
IOC Port : 0x81

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00004 : INFO)
csa101: Instantiated as component instance csa101I0.

Wed Nov 12 11:54:38.424 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00005 : INFO)
csa101I0: Waiting for CSI assignment...
</pre></code>
|}

<li>Next change the administrative state of the csa101SGI0 service group to "unlocked" by running (in the SAFplus Platform Console) :
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa101SGI0
</pre></code>

In the window where you're running the "tail -f" you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00163 : INFO)
csa101: ACTIVE state requested; activating service

Wed Nov 12 11:59:37.092 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00164 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:39.094 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00165 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:39.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00166 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:41.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00167 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 11:59:41.097 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00168 : INFO)
csa101: Threaded Hello World! .

Wed Nov 12 11:59:43.095 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00169 : INFO)
csa101: Unthreaded Hello World! .
</pre></code>
|}

As you can tell from the output log our component is up and running! It is continuously printing our 'Hello World!' output.

<li>Now change the state of the csa101SGI0 service group back to "locked-for-assignment" by running (in the SAFplus Platform Console):
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa101SGI0
</pre></code>

In the tail -f output you should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa101I0Log.latest
|-
|<code><pre>
Wed Nov 12 12:07:17.591 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00625 : INFO)
csa101: Unthreaded Hello World! .

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00626 : INFO)
Component [csa101I0] : PID [10950]. CSI Set Received

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00627 : INFO)
CSI Flags : [Target One]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00628 : INFO)
CSI Name : [csa101CSII0]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00629 : INFO)
HA state : [Quiesced]

Wed Nov 12 12:07:19.281 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00630 : INFO)
csa101: Acknowledging new state quiesced

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00632 : INFO)
Component [csa101I0] : PID [10950]. CSI Remove Received

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00633 : INFO)
CSI : csa101CSII0

Wed Nov 12 12:07:19.312 2014 (SCNodeI0.10950 : csa101I0.MAI.---.00634 : INFO)
CSI Flags : 0x2
</pre></code>
|}

Our component has been put into Lock Assignment state so our 'Hello World!' output has stopped printing to the log.

<li>At this point you can either unlock the service group to change its state to "unlocked" or you can lock it for instantiation to change it to state "locked-for-instantiation". The latter will cause the csa101 process to die. From state "locked-for-assignment", it is possible to change the state to "locked-for-instantiation" by running (in the SAFplus Platform Console):
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa101SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Stopping SAFplus Platform===

To stop SAFplus Platform on the System Controller
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>Once logged in, run the following command
<code><pre>
# cd /root/asp
# etc/init.d/asp stop
</pre></code>
</ol>

==Summary and Next Steps==
In the csa101 example we learned the following.

<ul>
<li>How to create a system model using the '''SAFplus Platform IDE'''.
<li>How to generate the source code.
<li>How to customize this source code to fit a specific application.
<li>How to configure and build the customized source code.
<li>How to make runtime images and deploy them to target machines.
<li>How to start and stop '''SAFplus'''.
<li>How to interact with system components using the '''SAFplus Platform Console'''.
</ul>

The next logical step would be to run through the '''SAFplus Platform Evaluation System User Guide'''. This guide goes over more complex system configurations and introduces new concepts.

For more in depth information on the '''SAFplus Platform IDE''' see the '''SAFplus Platform IDE User Guide'''.

For more in depth information on the '''SAFplus Platform SDK''' see the '''SAFplus Platform SDK User Guide'''.

==Appendix A: target.conf Settings==

Below is a description of the values in the settings in the <code>target.conf</code> file.

<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of SAFplus Platform SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1340
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

==Appendix B: AMF Configuration Details==
This appendix gives brief descriptions of configuration details for instances of different entities (like Node, Service Group, Service Unit etc) that are present in the '''Clovis''' -> '''AMF Configuration''' dialog box.

===Node Instance===
This screen displays the node instance that was created by the Node Instance Wizard. This node instance was created because the node type '''SCNode''' was selected on the wizard screen.

[[File:Tutorial_NodeInstanceDetails.png|frame|center| '''Node Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Node Instance Name''': This field holds the name of the node instance. This name must be unique. The name that was generated combines the node type (SCNode), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Node Type''': This field holds the node type that was selected on the wizard screen.
<li>'''MOID''': This is the unique identifier for the node instance. It was generated by the wizard. The format of this ID is a string representing the one and only instance of the chassis (\Chassis:0) defined in the Resource Editor followed by a string representing the first and only instance of the blade type (\SysBlade:0) that was selected in the Node Instance Wizard.
 [[File:OpenClovis_Note.png]]'''MOID''' is an acronym for Managed Object Identifier. It must be unique and is used to identify which hardware chassis and blade type this instance will run on.
</ul>

===Service Unit Instance===
This screen displays the service unit instance that was created by the Service Group Instance Wizard. This service unit instance was created because the service unit type is associated with both the selected node type (SCNode) and the selected service group type (csa101SG) in our model.

[[File:Tutorial_SUInstanceDetails.png|frame|center| '''SU Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SU Instance Name''': This field holds the name of the service unit instance. This name must be unique. The name that was generated combines the service unit type (csa101SU), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Service Unit Type''': This field holds the type of the service unit instance.
</ul>

===Component Instance===
This screen displays the component instance that was created by the Service Group Instance Wizard. This component instance was created because the component type is associated with the created parent service unit type (csa101SU) in our model.

[[File:Tutorial_ComponentInstanceDetails.png|frame|center| '''Component Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Instance Name''': This field holds the name of the component instance. This name must be unique. The name that was generated combines the component type (csa101), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''Component Type''': This field holds the type of the component instance.
</ul>

===Service Group Instance===
This screen displays the service group instance that was created by the Service Group Instance Wizard. This service group instance was created because the service group type '''csa101SG''' was selected on the wizard screen.

[[File:Tutorial_SGInstanceDetails.png|frame|center| '''Service Group Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''SG Instance Name''': This field holds the name of the service group instance. This name must be unique. The name that was generated combines the service group type (csa101SG), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceGroup Type''': This field holds the type of the service group instance.
<li>'''Associated Service Units''': This button is used to associate service unit instances with this service group instance. Creating this association indicates that the selected service unit(s) will run within this service group instance.
</ul>

Clicking the '''Associated Service Units''' Edit... button will display the following dialog.

[[File:Tutorial_SG_SI_Association.png|frame|center| '''Associated Service Units Dialog''' ]]

This dialog lists the service unit instances that can be associated with this service group instance. The list contains only one item, the service unit instance that was created by the wizard. This item is checked indicating that the wizard automatically chose this service unit instance to run within the service group instance.

===Service Instance Instance===
This screen displays the service instance that was created by the Service Group Instance Wizard. This service instance was created because the service instance type is associated with the parent service group type (csa101SG) in our model.

[[File:Tutorial_SIInstanceDetails.png|frame|center| '''Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Service Instance Name''': This field holds the name of the service instance. This name must be unique. The name that was generated combines the service instance type (csa101SI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ServiceInstance Type''': This field holds the type of the service instance.
</ul>

===Component Service Instance Instance===
This screen displays the component service instance that was created by the Service Group Instance Wizard. This component service instance was created because the component service instance is associated with the parent service instance type (csa101SI) in our model.

[[File:Tutorial_CSIInstanceDetails.png|frame|center| '''Component Service Instance Details''' ]]

The information on this screen is described below.
<ul>
<li>'''Component Service Instance Name''': This field holds the name of the component service instance. This name must be unique. The name that was generated combines the component service instance type (csa101CSI), the letter I (for Instance), and the number 0 (since this is the first instance of this type).
<li>'''ComponentServiceInstance Type''': This field holds the type of the component service instance.
</ul>

File:Workspace Launcher.png

2014-11-14T07:17:30Z

Prasad:

File:Service Instance List csa101SII0.png

2014-11-14T07:16:43Z

Prasad:

File:Service Group List csa101SGI0.png

2014-11-14T07:16:26Z

Prasad:

File:Service Group List.png

2014-11-14T07:16:13Z

Prasad:

File:Service Group Details.png

2014-11-14T07:15:55Z

Prasad:

File:SAF Service Type Name.png

2014-11-14T07:14:57Z

Prasad:

File:SAF Component Details.png

2014-11-14T07:14:36Z

Prasad:

File:Resource Editor.png

2014-11-14T07:14:17Z

Prasad:

File:Node Instance List.png

2014-11-14T07:13:52Z

Prasad:

File:Node Instance Details SCNodeI0.png

2014-11-14T07:13:29Z

Prasad:

File:Node Instance Details csa101SUI0.png

2014-11-14T07:13:05Z

Prasad:

File:Node Instance Details csa101I0.png

2014-11-14T07:12:40Z

Prasad:

File:New Project Wizard.png

2014-11-14T07:12:25Z

Prasad:

File:IDE Welcome Screen.png

2014-11-14T07:12:10Z

Prasad: