CERN -> IPT Group -> FrameMaker at CERN
Information Service User's Guide

2.2 Publishing and updating information

As it was explained in the introduction an application can add a new information to the IS repository, update an existing information and remove it if necessary. The update function has two working modes:

  1. Default mode: in this mode the old value of the updated information is removed from the IS and is lost forever.
  2. History mode: in this mode the old information value is stored in the IS and can be retrieved later.

The number of history values, which can be stored by the IS repository for a single information object is limited by the dedicated parameter of the IS server application, which implements the corresponding part of the IS repository. This limit is the same for all the information items, which are stored on that IS server. In the current implementation this number is defined at the server start up time and can not be changed dynamically. When the number of history values for any information object exceeds the limit the IS server removes the oldest value from the history list and destroy it.

2.2.1 Adding new information to the IS

"Listing 2.1" shows how an application can make several instances of the simple information available for any other interesting application via IS, i.e. publish information.

First the user program has to include the is/infoT.h header file. This file contains declarations for the simple IS information types and also includes internally the main IS header file is/info.h which declares the ISInfoDictionary class which provides the main interface for the information providers. Then the program creates an instance of the IPCPartition class. This instance represents the partition in which the Information Service will be used. For more information about IPCPartition class see [9]. The ISInfoDictionary class constructor takes this partition object as parameter. Then, lines 22-23 show how the ISInfoDictionary object can be used to insert new information to the IS.

Listing 2.1   Publishing simple information
1: #include <is/infoT.h>
2: #include <is/infodictionary.h>
3: #include <ipc/core.h>
4:
5: int main( int ac, char ** av ){
6: // Initialise communication library
7: IPCCore::init( ac, av );
8:
9: // Create the instance of partition
10: IPCPartition partition("MyPartition");
11:
12: // Create the IS dictionary in the specific partitition
13: ISInfoDictionary dict(partitition);
14:
15: // Create the instances of the information
16: // that will be published, and initialise them
17: ISInfoInt voltage( 220 );
18: ISInfoFloat temperature( 22.3 );
19:
20: // Publish information in the MyServer IS server
21: dict.insert( "MyServer.DeviceVoltage", voltage );
22: dict.insert( "MyServer.DeviceTemperature", temperature );
23:
24: return 0;
25: }

If information object with the given name already exists in the IS repository the insert function throws daq::is::InfoAlreadyExist exception and does not change the content of the information repository.

When the published information is changed, it is necessary to inform the IS about those changes. Next chapters explain how one can do this. This can be done in two ways: one can instruct the IS repository to keep the previous value of the updated information or to drop it. The next two chapters explain how this can be done.

2.2.2 Replace the last information value

The update method of the ISInfoDictionary class tells to the IS that already existing information, identified by the first parameter of the update call, has been changed. If there is no information with this name in the IS the update function throws daq::is::InfoNotFound exception and does not change the content of the information repository.

Listing 2.2   Updating simple information without keeping information history
1: #include <is/infoT.h>
2: #include <is/infodictionary.h>
3: #include <ipc/core.h>
4:
5: int main( int ac, char ** av ){
6: ...
7: voltage = 360;
8: temperature = 31.54;
9:
10: // Update information in the MyServer IS server
11: dict.update( "MyServer.DeviceVoltage", voltage );
12: dict.update( "MyServer.DeviceTemperature", temperature );
13:
14: return 0;
15: }

This example requests the IS repository to store the new information value and drop the previous one. The previous information value will be lost forever.

2.2.3 Update information using history mode

Contrary to the example in the previous chapter the one, which is shown on Listing 2.3. requests the IS repository to keep the old information value, which can be retrieved later by using the technic described in the Listing 2.3.

Listing 2.3   Updating simple information with history
1: #include <is/infoT.h>
2: #include <is/infodictionary.h>
3: #include <ipc/core.h>
4:
5: int main( int ac, char ** av ){
6: ...
7: voltage = 360;
8: temperature = 31.54;
9:
10: // Update information in the MyServer IS server
11: dict.update( "MyServer.DeviceVoltage", voltage, true );
12: dict.update( "MyServer.DeviceTemperature", temperature, true );
13: return 0;
14: }

Note the use of an additional parameter for the update function. It is set to true, which means that the old information value has to be kept. If this parameter is omitted then the default value, which is false, is taken and the old information value is removed from the IS.

2.2.4 Update information using specific tags

Each history value for the given information object has a unique identity called tag. Tag is a 32-bit number which is uniquely identifying each history value for the given object. When the object value is updated using the method, described in the previous chapter, the IS assigns the value tags by itself - in this case the new value will be assigned a tag which is equal to the maximum tag for the given information object plus 1. IS also provides a way of updating values in the history by using tags of those values as identifiers. Listing 2.4 shows hoe this can be done.

Listing 2.4   Updating simple information with specific history tags
1: #include <is/infoT.h>
2: #include <is/infodictionary.h>
3: #include <ipc/core.h>
4:
5: int main( int ac, char ** av ){
6: ...
7: voltage = 360;
8:
9: // Update information in the MyServer IS server
10: dict.update( "MyServer.DeviceVoltage", voltage, 1 );
11:
12: voltage = 220;
13: dict.update( "MyServer.DeviceVoltage", voltage, 2 );
14: return 0;
15: }

If the IS repository already contains the information object called "MyServer.DeviceVoltage" then the call to the update function in the line 10 will do one of the folloiwng: adds new value to the history values list of the given object if there was no history value with the ID=1, or replace the value with the ID=1 in the history list with the new one. LIne 13 does the same but for the values with the ID=2.

If after that an application will ask for the most recent information value using the ISInfoDictionary::getValue function, it will get the value with the ID=2, since it was the last one being updated.

2.2.5 Atomic combination of the insert and update functions

While sometimes it's necessary to have separate insert and update functions, in most cases it's much more convenient to use an atomic operation, which creates new object is it does not yet exist or otherwise updates the existing object's value. ISInfoDictionary class provides such function, which is called checkin (see Listing 2.5).

Listing 2.5   Use atomic checkin operation
1: #include <is/infoT.h>
2: #include <is/infodictionary.h>
3: #include <ipc/core.h>
4:
5: int main( int ac, char ** av ){
6: ...
7: voltage = 360;
8: temperature = 31.54;
9:
10: // Create information if it's not there or update its value
11: dict.checkin( "MyServer.DeviceVoltage", voltage );
12:
13: return 0;
14: }

2 July 1998 - WebMaster
Copyright © CERN 1998