Defining the Control Data

---

You specify the control data as environment variables for the 
environment in which your application runs. OS_ALLOW_OPE_
AUTO_START = 1 

With this option you define that the following method is not invoked: objectstore::disable_ope_auto_start(). This method disables automatic tracing.

yes | no 

With this option you define whether the trace file name gets a process identification number (PID) for the process that loads the Retriever. By default, the PID is added to the trace file name. For example, if the trace file name is defined as trace.trf, and the PID of your application's run is "12345", the resulting trace file name is trace.trf.12345.

stringstring defines the command with which you start your application. OPE saves this string with the application trace and displays it in the diagrams together with other trace settings. This helps you identify the application trace when you analyze it. You can specify any string because OPE does not analyze it. This specification is optional.

OS_OPE_ENV_ top_event_name = 1 | " list_of_event_names" 

With this option you specify whether a generic event is enabled. Note top_event_name is place holder for the name of a generic event. Based on the event name, you can enable or disable specific generic events and categories of generic events. A category consists of several generic events in hierarchical order. If you want to enable only subevents of this category, you pass the subevent names as a string to the environment variable. For example, OS_OPE_ENV_DEBUG = "DEBUG2 SPECIAL" enables the subevents DEBUG2 and SPECIAL of the category DEBUG. For details on generic event names refer to Class os_ope_generic_event.

OS_OPE_OBJECT_ALLOCATION = yes | no

With this option you define whether OPE collects statistical information on object allocation per transaction. You can see this information in the Client Counters/Ratios diagram as objects allocated and objects deleted, and in the transaction summary. For details see "Objects allocated" and "Transaction summary".

OS_OPE_REPORT_QUERY_EVENTS = 0 | 1 

Enables tracing of collection events, such as index and query events. For a detailed description of collection events see Collection events (start and stop) on page 42. This environment variable is only valid for ObjectStore Release 4 or higher.

OS_OPE_STOP_TRACING =  number 

number specifies the number of seconds after which the OPE Retriever automatically stops tracing of an application. Note that the Retriever does not stop tracing before the current transaction ends.

autoStarts tracing implicitly when your application starts the first ObjectStore transaction. Tracing is then performed automatically until the application finishes processing. For automatic tracing, any invocation of the OPE Retriever API, including the specification of the parameters, is ignored. The only exception is that the application can still raise generic events (for details see Class os_ope_generic_event).

With the automatic start mode you measure the complete processing of your application; you cannot trace only selected parts. To trace selected parts of the application, use the manual start mode.

manual tracing means that the application itself controls the starting stopping of tracing by invoking the method os_ope::start() or os_ope::stop() of the OPE API. This enables you to trace selected parts of the application.

If tracing is started and stopped several times during an application's processing, several trace files can be created.

The application also suspends tracing and resumes it at a later point by invoking the method os_ope::suspend() or os_ope::resume() of the OPE Retriever API. This enables you to trace selected parts of the application and keep the overall context of a single application trace.

If tracing is suspended and resumed several times during an application's processing, only one trace file is created. For a detailed description of the different OPE Retriever API methods see "Suspend and resume methods".

file_namefile_name defines the trace file where the collected data is be stored. If the specified file already exists, it is overwritten without warning. If you specify a partial pathname, the appropriate substitutions of your operating system apply. The name of the trace file is optional. If you do not specify a file name, the file gets the name trace.trf.PID, where PID is the process identification number (see also OS_OPE_APPEND_PID). This file is created in the current directory. Note that the trace file names can vary according to the ObjectStore release. For detailed information on these names refer to the ObjectStore C++ Interface Release Notes.

Note: Do not specify a trace file if your application starts and stops manual tracing several times during one application run. Otherwise, each new start of tracing overwrites the results of the previous tracing. To specify several trace files, use the trace file parameter of the OPE Retriever API start method (for details see "Start and stop methods").

numbernumber specifies the buffer size that OPE uses to ccess to the trace file. The default value is 65536 bytes (64 kilobytes), the minimum value is 100 bytes, and the maximum value is 2 gigabytes. The value represents a tuning parameter. If you specify a value less than 100 bytes, the minimum value is set automatically. This specification is optional.

To achieve the lowest impact of OPE's tracing on your application's performance try to find the optimum value and look at the ElapsedTime diagram to verify the results. To ensure that a maximum part of the trace file is created in case your application ends abnormally, set the following environment variable:

OS_OPE_TRACE_FILE_FLUSH =  txn |  event
OS_OPE_TRACE_FILE_FLUSH =  no |  txn |  event 

With txn you define whether the trace file is flushed to the disk after an ObjectStore transaction commits or ends abnormally. Thus, the trace file contains performance data of the last finished transaction even if an error occurs.

With event you define whether the trace file is flushed to the disk after OPE processes an ObjectStore event. Thus, the trace file contains the most recent event in case an application ends abnormally. Note that this option might increase the processing time of the OPE Retriever.

By default, the trace file is not flushed to the disk.

OS_OPE_TRACE_FILE_VERSION = 1.5 | 1.0

This environment variable controls the version of the written trace file. A trace file with version number 1.5 can only be formatted with an Analyzer of OPE Version 1.5. Note that a trace file with version number 1.0 contains only information that is retrieved with a Retriever of OPE Version 1.0.