OPE User Guide

Retriever API Classes and Methods

The Retriever API provides you with the following classes and related methods:

You must include interface information for these classes by specifying #include <ostore/client/ope.hh> in the source code of your application.

The following section describes the purpose of the classes and their public interface.

Class os_ope

This class provides you with static methods that help you to control tracing of your application. Using these methods, you can

The os_ope class methods take effect only when OPE is in manual trace mode (this is the case when OS_OPE_TRACE is set to manual).

After you start ObjectStore processing using objectstore::initialize, you can start and stop, and resume OPE tracing at any point during your application's processing. The following section tells you in detail what you can achieve by using the methods of the os_ope class.

Start and stop methods

With start and stop methods you can trace selected parts of your application. By invoking these methods at various points during an application's processing, you can create several trace files for a single application.

You can specify the trace file name as a parameter of the methods. Note that Retriever API parameters take precedence over environment variables. If neither environment variables nor Retriever API parameters are defined, the default values determined by OPE apply.

Use the following method to start manual tracing and to specify the trace file name as a parameter value:

static void os_ope::start( char const * fp =0);

If tracing is already started, this call is ignored. With the fp parameter, you specify the name of the trace file. If you do not specify this parameter, OPE uses the file name specified in the OS_OPE_TRACE_FILE environment variable. If his variable is not defined, the file is given the default name trace.. The file is located in the current directory. You can specify a relative or an absolute path name.

If tracing is started several times, you must specify a different file name for each start. Otherwise each new trace overwrites the results of the previous

To stop manual tracing, you must use the following method:

static void os_ope::stop();

Manual tracing is stopped and the trace file is ready for formatting. If tracing is not started, this method call is ignored.

Suspend and resume methods

With suspend and resume methods you can trace selected parts of your application and keep the context of a single application trace.

The application invokes suspend and resume methods to suspend tracing temporarily and resume it at a later point. If tracing is suspended and resumed several times during an application's processing, only one trace file is created. This is different from the start and stop methods.

You can use the following suspend and resume methods:

static void os_ope::suspend();

Stops tracing until it is explicitly resumed. This method is ignored if there is no active application trace, or if tracing is already suspended.

static void os_ope::resume();

Restarts suspended application tracing. This method is ignored if an active application trace already exists, or if tracing is already resumed.

After you start or resume tracing manually, OPE might not be able to show the correct state of the pages to which your application has access. In this case, OPE the page state as Not Encached. With the next event that changes the state of a page after a start or resume, OPE the correct page state.

Class os_ope_generic_event

The os_ope_generic_event class lets you include application-specific information in the trace. You can supply identifying information including numbers, strings, and object addresses, which are displayed in the Analyzer diagrams in the same manner as ObjectStore events.

To insert a generic event into the trace, you first create an instance, supplying a name and other information. Then, you raise the event by calling one of several methods defined on the class. Generic events that are raised are automatically integrated into the OPE Analyzer diagrams.

Generic events are shown on the generic events line of the TimeLine or PageState diagram. Depending on the information that is supplied with the event, they can also be displayed in other diagrams, such as the PageState Diagram and the Client Counters/Ratios diagrams.

Defining a generic event

With each instance, you define the name of the generic event, its position in the hierarchy with other events, and the actions that OPE performs when this event is raised.

An instance of the os_ope_generic_event class is defined as follows:

os_ope_generic_event( char*  name,

	os_unsigned_int32 options = 0,

	os_ope_generic_event *parent = 0);

All parameters except for the name parameter are optional and have default values as shown in the function signature. The parameters are described as follows:

The name parameter defines an identifier for the generic event instance. This is the name that is shown in the Analyzer diagrams.

You also use the generic event name

For details refer to Defining the Control Data.

Note that in this case the name must not contain blanks.

Generic event instances can form a hierarchy of parent and child relationships. Use the parent parameter to form such a hierarchy within your application. Thus, you can enable or disable complete hierarchy branches of generic events in your application. To insert parent and children generic events in your application trace, enable the parent generic event by specifying the environment variable OS_OPE_ENV_name.

The following gives you an example of creating a generic event and enabling it with an environment variable:

os_ope_generic_event *e =
new os_ope_generic_event
("Person",os_ope_generic_event::counter, 0);

OS_OPE_ENV_Person=1

The option parameter contains one of the following values:

Enables the generic event independent from the environment variable OS_OPE_ENV_< generic_event_name>.

Gets values for the OPE client counters and ratios that are inserted in the application trace at the time when the generic event is raised.

You can specify any option or combine them as a single option by using the Boolean or operator ( | ).

Raising a generic event

To insert a generic event into the application trace, use one of the following methods. They are represented by different symbols in the diagrams:

(Represented by a square)

(Represented by a right arrowhead)

(Represented by a left arrowhead)

You can use the raise_before and raise_after methods to identify blocks of processing within your application. Apart from drawing different symbols for these events, OPE treats the raise_single, raise_before, and raise_after methods in the same way.

Each raise method can have one of the following signatures:

void os_ope_generic_event::raise_... ( const char* message,...);
void os_ope_generic_event::raise_... ( void* adr,

			const char* message=0, ...);
void os_ope_generic_event::raise_... ( os_unsigned_int32 value,

			const char* message=0, ...);
void os_ope_generic_event::raise_... ( os_segment*,

			const char* message=0, ...);
void os_ope_generic_event::raise_... ( os_database*,

			const char* message=0, ...);

The message parameter is a printf-style format string. Any additional parameters, if specified in the format string, should be specified after the message parameter. For each raise of a generic event you can specify a message with a maximum of 4096 bytes containing format parameters.

also optionally pass an additional parameter to provide more information to OPE to place the event on the appropriate diagrams. You can pass an object address, an integer value, a pointer to an ObjectStore segment, or a pointer to an ObjectStore database, depending on which overloading is used.

If you pass integer values, you can display them in the Client Counters/Ratios diagrams like other ObjectStore counters. This can show you important application values over the duration of the trace. Note that integer values are not displayed in the Storage Counters/Ratios diagrams since no storage location is associated with it.

If you pass an object address, a pointer to an ObjectStore segment, or a pointer to an ObjectStore database, the generic event is also shown on the appropriate storage bar of the PageState diagram.

For example: 

char* name = "Fred";
Person *fred = new(db,...) Person (name);
...
os_ope_generic_event *e =

   new os_ope_generic_event("Person_Event",

   os_ope_generic_event::always_enabled);
e->raise_before ((void*) fred, "Accessing %s", name);
...
e->raise_after ((void*)fred, "Done.");

This code defines a new persistent instance fred of the class person. You define a generic event with the name Person_Event. You do not have to enable the event explicitly by specifying OS_OPE_ENV_Person_Event=1 because it is defined to be always enabled.

To avoid possible overloading conflicts with compilers, cast the message by using (const char*).

Note: If the message is a persistent object, you have the following possibilities:

For example, e->raise fred is an ambiguity for

raise_... (const char*)
raise_... (void*)

When the raise methods are called, the address of fred is specified with a message. As a result, the generic event is shown on the generic event lines of the TimeLine and PageState diagram and on the page that contains fred in the PageState diagram.

If an object address is passed to the generic event, and the address is not dereferenced by the application during the trace, the generic event is not shown on the storage object bar of the PageState diagram.


support@objectstore.net
Copyright © 2004 Progress Software Corporation. All rights reserved.