Oracle Enterprise Manager Oracle Trace Developer's Guide Release 1.4.0 A53697_01

Library Product Contents Index

7
Oracle Trace Routines

This chapter describes the Oracle Trace routines. These routines allow you to record events that occur during execution of your application. Table 7-1 lists the routines described in this chapter.

The description of each routine has the following parts:

Be sure to read the introductory material to this chapter. It contains important information about data structures, datatypes, and parameters specific to the Oracle Trace routines.

Table 7-1 lists the Oracle Trace routines and briefly describes their use. The complete routine descriptions are in alphabetical order later in this chapter.

Table 7-1 Oracle Trace Routines

Calling Oracle Trace Routines

This section provides information about data structures, datatypes, and parameter-passing conventions for Oracle Trace routines.

Datatypes

The datatypes used in the Oracle Trace routines are defined in the epc.h file. This file is operating-system specific. The types defined, such as sb2 and ub4, can take different C types on different systems.

The online location of epc.h is system-specific. See your Oracle installation or user's guide for the location of the file on your system. For UNIX systems, the file is located in $ORACLE_HOME/otrace/public. For Windows NT systems, the file is located in $ORACLE_HOME\otracexx\public where xx refers to the version of the database.

Data Structures

Oracle Trace uses two types of data structures: event collection flags arrays and user-defined buffers.

An event collection flags array is used to communicate to the application which events should be collected. A user-defined buffer is used only for product-specific items. Each of these data structures is described in the following sections.

A product must allocate virtual memory (statically or dynamically) for each data structure it uses, and pass the address of the structures in the call to any Oracle Trace routines.

Event Collection Flags Array

The event collection flags array is a list of up to 128 integer values. Oracle Trace designates events for collection by setting bits in the event collection flags array.

Each array element corresponds to a particular event number in your application beginning with 1. Element 0 is reserved for Oracle Trace. To test whether or not an event should be logged, use the event ID as a subscript into the array. Your application should be instrumented so that epc_init allocates and returns to you the address of these event flags.

When a collection is scheduled for your product, Oracle Trace uses the product definition and collection event set to determine which events should be collected. Oracle Trace then sets event collection flags for those events to a value of 1; otherwise the value is 0. Your product then tests the 4-byte integer associated with each event to determine whether or not it is set (has a value of 1) before calling an Oracle Trace event routine for that event. This sequence minimizes overhead because routines are called only when collections are active for the event.

User-Defined Buffer

The user-defined buffer is a data structure that contains the data for product-specific items. The event_rec parameter in the Oracle Trace event routines specifies the address of the user-defined buffer. A product uses the user-defined buffer to pass product-specific items to Oracle Trace.

Oracle Trace expects items to immediately follow one another in the buffer in the order in which they were listed in the product definition. (This does not include resource and cf items.) If structures are used to build event records, make sure the compiler does not align individual items on address boundaries.

The items in the user-defined buffer can be unsigned integers or counted strings. The unsigned integers are:

• unsigned byte
• unsigned 2 bytes
• unsigned 4 bytes
• unsigned 8 bytes

A counted string is a data structure in which a count of the number of characters in the string precedes the string. The counted strings are:

• ASCIC: a variable-length string. The first byte contains the size of the string; the remainder is the string itself.
• ASCIW: a variable-length string. The first two bytes contain the size of the string; the remainder is the string itself.
• ASCIL: a variable-length string. The first four bytes contain the size of the string; the remainder is the string itself.
• FIXED ASCIC: a fixed-length string. The first byte contains the size of the string. Some programmers use the FIXED ASCIC string because the user-defined buffer can be a compile-time structure rather than constructed at each event occurrence. However, as illustrated in the following figure, records in the FIXED ASCIC structure take up more space if the item is less than the maximum size.

Parameter Classification

There are two types of parameters:

• required
• optional

Required Parameters

Required parameters are used by Oracle Trace, and your product must supply valid values for them.

Optional Parameters

The use of optional parameters depends on the requirements of your product. The Format section for each routine in this chapter indicates optional parameters using square brackets, [].

For any optional parameter without a value, you must specify 0 (if the parameter is passed by value) or a null value (if the parameter is passed by reference). This is true for all optional parameters in all Oracle Trace routines.

Parameter Descriptions

Each Oracle Trace routine description provides the following information for all parameters:

• datatype
• access
• passing mechanism

There are several parameters that are used in almost all of the Oracle Trace routines. The rest of this section provides descriptions for those common parameters, rather than repeating the information in each routine description.

api_version

A version number corresponding to the API version. For Oracle Enterprise Manager releases 1.2 and 1.3, the value should be 1. For Oracle Enterprise Manager release 1.4, the value should be 2. By passing the API version, Oracle Trace routines can handle programs that make calls using older versions of the API.

vendor

A unique number used to identify the vendor who developed the application for which you are collecting data. The number must match the vendor ID specified in the product definition file.

The vendor ID number is the same as the network ID section of the vendor's Internet address. The section of a vendor's Internet address that is considered to be the network ID depends upon whether the Internet address is an event set A, B, or C address.

A sample event set A address is 16.31.128.90. For event set A addresses the network ID is the first section of the address, in this case 16. Therefore, the vendor ID is 16.

A sample event set B Internet address is 128.3.0.5. For event set B addresses, the network ID is made up of the first two sections, in this case 128.3. Therefore, the vendor ID is 1283.

As another example, Oracle Corporation uses event set C Internet addresses. A sample event set C Internet address is 192.216.243.3. For event set C addresses the network ID is made up of the first three sections of the address, in this case 192.216.243. Therefore, Oracle Corporation's vendor ID is 192216243.

Vendors who do not have an Internet address can obtain one by contacting the Network Information Center (NIC) located at SRI International. Addresses are available even to vendors who do not plan to join the Internet.

See the UNIX System Administration Handbook, Prentice Hall, Englewood Cliffs, N.J., 1989 for details on obtaining an Internet address.

product

A number for the calling product. The number must match the product number specified in the product definition file.

Vendors can assign numbers of their own choosing to their products. The only restriction is that the number be unique among the vendor's own products.

version

A null-terminated string of up to 10 characters containing the version of the product. The string must be identical to the version specified in the product definition.

registration_id

For epc_init: A null-terminated string that describes a specific function in a product. For data collection to occur, the string must be identical to the registration ID specified when the collection was scheduled.

For epc_add_reg_id and epc_remove_reg_id: A text string that correlates to the current value of the cross-product item.

epcfctx_ptr

A type of EPCFCTX that is defined in epc.h. This context parameter is filled in by the epc_init routine and used by other Oracle Trace routines. This parameter is passed by reference to all routines that use it.

Return Values

Each routine has a possible set of return values that correspond to the informational and error messages displayed by Oracle Trace. If you receive an error that does not include associated text, lookup the error number in the epc.h file, and read the associated description.

epc_add_reg_id

Purpose

Adds a registration ID for a product or for the value of a cross-product item. This routine can be called multiple times by a product.

Format

status=epc_add_reg_id(api_version,vendor,product,version, registration_id,[cf_item_number],epcfctx_ptr)

C Binding

sb4 epc_add_reg_id(api_version,vendor,product,version, registration_id,[cf_item_number],epcfctx_ptr)

sb4 api_version;

sb4 vendor;

sb4 product;

text *version

text *registration_id;

ub4 cf_item_number;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

version

For a description of this parameter, refer to "Parameter Descriptions".

registration_id

A null-terminated string that describes a specific function in a product. For data collection to occur, the string must be identical to the registration ID specified when the collection was scheduled.

cf_item_number

Ties the registration ID string to the value of a cross-product item at the time of the call. This allows cross-product item values to be directly related to string values. If this parameter is omitted, the registration ID is associated with the process.

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_add_reg_id routine adds a registration ID for a product. A product can call this routine as often as necessary, depending upon the number of registration identifiers it wishes to associate with an application process.

Return Values

See Also

epc_remove_reg_id

epc_cancel

Purpose

Cancels a collection for the specified collection name. This routine is only for use by products that wish to control collections from within their application, rather than through the Oracle Trace Manager.

Format

status=epc_cancel(api_version,vendor,product,version,collection_name, [product_instance_eventflags],epcfctx_ptr)

C Binding

sb4 epc_cancel(api_version,vendor,product,version,collection_name,
[product_instance_eventflags],epcfctx_ptr

sb4 api_version;

sb4 vendor;

sb4 product;

text *version

text *collection_name;

sb4 *product_instance_eventflags;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

version

For a description of this parameter, refer to "Parameter Descriptions".

collection_name

Points to the path and filename of the collection definition file, minus any suffix. It must be the same collection_name as specified in the call to the epc_collect routine.

product_instance_eventflags

For Oracle Trace Collection Services release 7.3, these flags support products that wish to keep track of multiple instances of a product within one process. For Oracle Trace Collection Services release 8.0, Oracle Trace handles this directly through the introduction of the epcfctx_ptr parameter.

The product_instance_eventflags parameter passed to the epc_collect call will be modified to reflect the eventflags specified in the event set within the product definition file also specified in the call.

Correct use of the product_instance_eventflags parameter requires the same flags to be passed to all the event logging routines as well.

When the collection is to be canceled, the same product_instance_eventflags parameter is passed to the epc_cancel routine where the events for this particular collection will be reset.

Multiple instance support is built in with Oracle Trace Collection Services release 8.0. The epc_init routine can be called once per instance and the epcfctx_ptr parameter will provide Oracle Trace with enough context to manage the eventflags properly. This removes the need for the product_instance_eventflags parameter, other than for backwards compatibility with Oracle Trace Collection Services release 7.3 and lower.

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_cancel routine cancels a collection for the specified collection filename. Any data remaining in the cache at that time is written to the .dat file. The .dat file and the .cdf file are then closed and values for the event flags parameter that were set in the epc_init routine are restored to their previous settings.

Return Values

See Also

epc_collect, epc_init

epc_cf_value

Purpose

Assigns a value to a cross-product item.

Format

status=epc_cf_value(api_version,item_num,item_val,[context], [item_adr])

C Binding

sb4 epc_cf_value(api_version,item_num,item_val,[context], [item_adr])

sb4 api_version;

sb4 item_num;

sb4 item_val;

sb4 context;

sb4 **item_adr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

item_num

The cross-product item number whose value is to be set to the value indicated by the item_val parameter.

item_val

The numeric value (in decimal) used to set the cross-product item number, indicated by the item_num parameter.

context

An integer value that corresponds to the context parameter returned from the call to the epc_context routine.

This parameter is optional. Pass a null value if it is not specified.

item_adr

Contains a pointer to the location of the corresponding cross-product item. The location will be user-mode accessible memory, created by Oracle Trace at the time of the epc_init routine. Thus, the location is accessible during the entire image execution, avoiding any potential access violations. The product can subsequently assign a value to the item without having to call the epc_cf_value routine, thereby avoiding call overhead.

Description

The epc_cf_value routine sets the value of a cross-product item. It optionally returns the address of the cross-product item in the item_adr parameter, so that it can be assigned later (more efficiently) by the product.

Return Values

epc_check_ef (Specific to Oracle8 Databases)

Purpose

Checks to see if an event flag is turned on.

Format

status=epc_check_ef(api_version,event_id,epcfctx_ptr)

C Binding

sb4 epc_check_ef(api_version,event_id,epcfctx_ptr)

sb4 api_version;

sb4 event_id;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

event_id

The event identifier (numeric) for the event. An event_id can range in value from 1 to 128.

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

Most applications can check whether an event is collecting by referencing the event flag array directly:

if (eventflags[event-id])  {

     <collect event>

}

However, complex applications, which can have multiple instances executing within the same process, might find it difficult to reference the correct set of event flags. These applications can use epc_check_ef to determine whether an event is collecting for a particular instance of the application.

Return Values

See Also

epc_end_event, epc_event, epc_start_event

epc_collect

Purpose

Starts a collection for the specified product and version from within the application itself. This routine is only for use by products that wish to control collections from within their application, rather than through the Oracle Trace Manager.

Format

status=epc_collect(api_version,vendor,product,version,
[overriding_eventflags],collection_name,fdf_name,
[product_instance_eventflags],col_max_size,epcfctx_ptr)

C Binding

sb4 epc_collect(api_version,vendor,product,version,
[overriding_eventflags],collection_name,fdf_name,
[product_instance_eventflags],col_max_size,epcfctx_ptr)

sb4 api_version;

sb4 vendor;

sb4 product;

text *version

sb4 *overriding_eventflags;

text *collection_name;

text *fdf_name;

sb4 *product_instance_eventflags;

ub4 col_max_size;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

version

For a description of this parameter, refer to "Parameter Descriptions".

overriding_eventflags

A way to override the event flags in the product definition file (.fdf) for the collection. A product can use this parameter as a shortcut to specify sub-event sets of events from a single .fdf file. For example, every time a product called the epc_collect routine, it could provide only the ALL .fdf file, which contains all possible events for that product. Then, using the overriding_eventflags parameter, individual events from the ALL event set could be set for collection.

This method of collecting only certain event sets of data is contrary to the method used by the Oracle Trace collection specification mechanism. However, it may prove worthwhile for those products that want to minimize the number of .fdf files installed on a given system or the number of hard-coded filenames in their code.

Overriding_eventflags are different than the event flags passed in or returned in the call to the epc_init routine, because they represent what the caller wants to log. The overriding_eventflags in epc_collect are compared with the event flags in epc_init to set the proper state of the epc_init event flags. Because multiple collections might be active at the same time, comparing the two sets of event flags ensures that the right data is collected for all active collections.

For example, suppose an application had a debug section in its code for which it wanted to start a special collection. The application could call epc_collect and use the overriding_eventflags parameter to set only certain debug events. This would override the ALL event set and also alleviate the need to create a special debug event set.

This parameter is optional. Pass a 0 if it is not specified.

collection_name

Points to the file specification for the collection definition file, minus any suffix. The suffix is appended by Oracle Trace when it uses this filename to create both the collection definition file (.cdf) and the data file (.dat). The .cdf file contains information about the collection, such as image and process names, product registration records, and a full path specification and name for the .fdf file. The .dat file contains the collected event data.

fdf_name

The product definition file that determines the events and their associated items that are logged for each event.

product_instance_eventflags

For Oracle Trace Collection Services release 7.3, these flags support products that wish to keep track of multiple instances of a product within one process. For Oracle Trace Collection Services release 8.0, Oracle Trace handles this directly through the introduction of the epcfctx_ptr parameter.

The product_instance_eventflags parameter passed to the epc_collect call will be modified to reflect the eventflags specified in the event set within the product definition file also specified in the call.

Correct use of the product_instance_eventflags parameter requires the same flags to be passed to all the event logging routines as well.

When the collection is to be canceled, the same product_instance_eventflags parameter is passed to the epc_cancel routine where the events for this particular collection will be reset.

Multiple instance support is built in with Oracle Trace Collection Services release 8.0. The epc_init routine can be called once per instance and the epcfctx_ptr parameter will provide Oracle Trace with enough context to manage the eventflags properly. This removes the need for the product_instance_eventflags parameter, other than for backwards compatibility with Oracle Trace Collection Services release 8.0 and higher.

col_max_size

The maximum size in bytes of the .dat file. Once the .dat file reaches this maximum, the collection is canceled.

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_collect routine starts a collection for the specified product and version. It does this by creating .cdf and .dat files using the name passed in the collection_name parameter.

Before creating a .cdf file, Oracle Trace checks to see if the file already exists. If it does, Oracle Trace parses the file and looks for the product name (.fdf file) specified in the call to the epc_collect routine. If the .fdf file is found, Oracle Trace assumes that multiple epc_collect calls were made from the same or different processes and that each call used the same collection and product names. Oracle Trace appends the process, image, and product registration records to the .cdf file. Data is appended to the .dat file.

This method of operation allows products such as SQL*Net to turn on collections from within multiple processes and to have those collections share common .dat and .cdf files after reading a common startup file.

If a .cdf file does not already exist, the epc_collect call creates and populates one. The .fdf is appended to the .cdf, as are the process, image, and product registration records. Either the product instance event flags (if they were specified) or the event flags specified in the epc_init routine are updated. The updates are based on either the overriding_eventflags, if they were specified, or on the events in the product definition file used in the collection. The epc_init routine must be called before the epc_collect routine or an error is returned.

The collection scheduled by epc_collect affects only the particular instance of the product that made the call to epc_collect. The epc_collect routine schedules a single collection that consists of only the product listed in the product definition file specified on the call. The epc_cancel routine is the corresponding routine used to cancel collections started through the epc_collect routine.

Refer to Chapter 5, Creating Product Definitions, for additional information regarding product definition files and event sets.

Return Values

See Also

epc_cancel, epc_init

epc_context

Purpose

Records a context variable for a new or existing thread so that resource use and/or cross-product items can be collected for multi-threaded products. This routine should be used by applications that perform their own thread switching. Correct usage of this routine requires that it be called for every thread switch.

Format

status=epc_context(api_version,context)

C Binding

sb4 epc_context(api_version,context)

sb4 api_version;

*sb4 context;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

context

A value used to set context for a new or existing thread.

Description

The epc_context routine sets the context for a new thread or an existing thread so that resource utilization and cross-product items can be collected on a per-thread basis in multi-threaded products. This routine is called by a product when a context switch is used to create or re-enter a thread context.

If a zero value is passed at the address specified (in the context parameter), then epc_context returns a value that identifies the new thread context. If a non-zero value is passed, it indicates to Oracle Trace that a context change has occurred. Oracle Trace associates the correct resource utilization and cross-product items with the corresponding thread.

To delete context information that Oracle Trace maintains for multi-threaded products, the epc_delete_context routine must be called when a thread executes to completion.

Return Values

See Also

epc_delete_context

epc_delete_context

Purpose

Deletes all associated context for the given context variable. This routine should be used by applications that perform their own thread switching. Correct usage of this routine requires that it be called for every thread termination.

Format

status=epc_delete_context(api_version,context)

C Binding

sb4 epc_delete_context(api_version,context)

sb4 api_version;

*sb4 context;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

context

An integer value that corresponds to the context parameter returned from the call to the epc_context routine.

Description

The epc_delete_context routine deletes all context required for Oracle Trace to collect resource utilization and/or cross-product items for a particular context variable.

Return Values

See Also

epc_context

epc_drop_fac (Oracle Server Release 8.0 Only)

Purpose

Notifies Oracle Trace that an instrumented product is no longer using Oracle Trace at or near the image exit.

Format

status=epc_drop_fac(api_version,vendor,product,version,epcfctx_ptr)

C Binding

sb4 epc_drop_fac(api_version,vendor,product,version,epcfctx_ptr)

sb4 api_version;

sb4 vendor;

sb4 product;

text *version;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

version

For a description of this parameter, refer to "Parameter Descriptions".

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_drop_fac routine informs Oracle Trace that the instance of the product as represented by the epcfctx_ptr has ended. Oracle Trace removes references to this instance of the product from its administration files and detaches from any collections to which it may be currently writing. Event buffer caches are flushed and the files closed.

The combined use of epc_init and epc_drop_fac allow for multiple instances of a product to be run within the context of a single process and allow for collection control to be performed on a per-instance level. Oracle Trace routines that require a product context will state so in their interface. Some routines, such as cross-product related routines, do not have such requirements.

Return Values

See Also

epc_init

epc_end_event

Purpose

Posts an occurrence of the end of a duration event.

Format

status=epc_end_event(api_version,vendor,product,event_id,handle,
[context],[event_rec],[event_rec_size],[option],[cf_items],[product_instance_eventflags],
epcfctx_ptr)

C Binding

sb4 epc_end_event(api_version,vendor,product,event_id,handle,
[context],[event_rec],[event_rec_size],[option],[cf_items],[product_instance_eventflags],
epcfctx_ptr)

sb4 api_version;

sb4 vendor;

sb4 product;

sb4 event_id;

sb4 handle;

sb4 context

text *event_rec;

sb4 event_rec_size;

sb4 option;

sb4 *cf_items;

sb4 *product_instance_eventflags;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

event_id

The event identifier (numeric) for the event. It ranges in value from 1 to 128.

handle

An address value that identifies the duration event used to match the start and end records. It must be identical to the one passed on the epc_start_event routine.

context

The thread context parameter passed to the epc_start_event routine. Events cannot start on one thread and end on another.

This parameter is optional. Pass a null value if it is not specified.

event_rec

The address of a record buffer containing the product-specific item values for an event.

This parameter is optional. Pass a null value if it is not specified.

event_rec_size

The length in bytes of the contents of the event_rec parameter.

This parameter is optional, unless event_rec is specified. Pass a 0 if event_rec_size is not specified.

option

This parameter is not yet supported for Oracle Trace. Pass a 0.

cf_items

The address of a cross-product items array that replaces the default cross-product items array. Normally, if the product definition states that a cross-product item is to be logged for a certain event, the value for that cross-product item is obtained from the internal Oracle Trace cross-product items array. This default method requires no product intervention and is well-suited to applications that do not have multiple threads of execution.

For products that have multiple threads of execution, use this parameter to track cross-product items on a per-thread basis. Call the epc_get_cf_items routine to get the values of the cross-product items for the thread, and save them in a per-thread storage area. On each subsequent Oracle Trace event call you can pass the address of those stored cross-product items as the cf_items parameter. This tells Oracle Trace that you wish to use the values stored at that address rather than the values stored in the normal internal Oracle Trace cross-product items array.

This parameter is optional. Pass a 0 if it is not specified.

product_instance_eventflags

This parameter is provided for the Oracle Trace Collection Services release 7.3 and allows a product to keep track of collections for multiple instances within the same process. This support is inherent in Oracle Trace Collection Services release 8.0 and is supplied through the epcfctx_ptr parameter.

The product_instance_eventflags parameter should be the same as the one passed on the epc_collect and epc_cancel calls for this instance of the product. Oracle Trace will use the eventflag settings in this array to determine if the event should be collected or not.

If your product does not have multiple instances per process or is using Oracle Trace Collection Services release 8.0 or higher, this parameter should be passed as a 0.

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_end_event routine enables a given product to post the end of a duration event.

Return Values

See Also

epc_event, epc_start_event

epc_event

Purpose

Posts an occurrence of a point event.

Format

status=epc_event(api_version,vendor,product,event_id,[context],
[event_rec],[event_rec_size],[option],[cf_items],[product_instance_eventflags],epcfctx_ptr)

C Binding

sb4 epc_event(api_version,vendor,product,event_id,[context],
[event_rec],[event_rec_size],[option],[cf_items],[product_instance_eventflags],epcfctx_ptr)

sb4 api_version;

sb4 vendor;

sb4 product;

sb4 event_id;

sb4 context

text *event_rec;

sb4 event_rec_size;

sb4 option;

sb4 *cf_items;

sb4 *product_instance_eventflags;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

event_id

The event identifier (numeric) for the event. An event_id can range in value from 1 to 128.

context

The thread context parameter passed to the epc_context routine.

This parameter is optional. Pass a 0 if it is not specified.

event_rec

The address of a record buffer containing the product-specific item values for an event.

This parameter is optional. Pass a null value if it is not specified.

event_rec_size

The length in bytes of the contents of the event_rec parameter.

This parameter is optional, unless event_rec is specified. Pass a 0 if event_rec_size is not specified.

option

This parameter is not yet supported for Oracle Trace. Pass a 0.

cf_items

The address of a cross-product items array that replaces the default cross-product items array. Normally, if the product definition states that a cross-product item is to be logged for a certain event, the value for that cross-product item is obtained from the internal Oracle Trace cross-product items array. This default method requires no product intervention and is well-suited to applications that do not have multiple threads of execution.

For products that have multiple threads of execution, use this parameter to track cross-product items on a per-thread basis. Call the epc_get_cf_items routine to get the values of the cross-product items for the thread, and save them in a per-thread storage area. On each subsequent Oracle Trace event call you can pass the address of those stored cross-product items as the cf_items parameter. This tells Oracle Trace that you wish to use the values stored at that address rather than the values stored in the normal internal Oracle Trace cross-product items array.

This parameter is optional. Pass a 0 if it is not specified.

product_instance_eventflags

This parameter is provided for the Oracle Trace Collection Services release 7.3 and allows a product to keep track of collections for multiple instances within the same process. This support is inherent in Oracle Trace Collection Services release 8.0 and is supplied through the epcfctx_ptr parameter.

The product_instance_eventflags parameter should be the same as the one passed on the epc_collect and epc_cancel calls for this instance of the product. Oracle Trace will use the eventflag settings in this array to determine if the event should be collected or not.

If your product does not have multiple instances per process or is using Oracle Trace Collection Services release 8.0 or higher, this parameter should be passed as a 0.

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_event routine enables a given product to post the occurrence of a point event.

Return Values

epc_flush

Purpose

Flushes the record cache of collections for which the process is currently collecting data. This routine should be used only by applications that wish to maintain control over their I/O.

Format

status=epc_flush(api_version)

C Binding

sb4 epc_flush(api_version,)

sb4 api_version;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_flush routine flushes the record cache of collections for which the process is currently collecting data. If the record cache for a particular collection is empty, a counter is incremented for that collection. If the counter reaches 20, the collection is canceled for the process and all associated collection files are closed. Therefore, caution should be used when making calls to the epc_flush routine.

Return Values

See Also

Not Applicable

epc_get_cf_items

Purpose

Returns all values for the cross-product items for this process or thread of execution if a context parameter is specified.

Format

status=epc_get_cf_items(api_version,[cf_items],[context],[item_adr])

C Binding

sb4 epc_get_cf_items(api_version,[cf_items],[context],[item_adr])

sb4 api_version;

sb4 cf_items[];

sb4 context;

sb4 **item_adr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

cf_items

The address of an array of integers used to return cross-product item values. The number of elements in this list, currently 14, is indicated by the constant EPC_K_MAXCFITEM in the epc.h file.

This parameter is optional. Pass a 0 if it is not specified. If the value is 0 and item_adr is specified, Oracle Trace fills in the item_adr.

context

An integer value that corresponds to the thread context parameter returned from the call to the epc_context routine. Oracle Trace returns the cross-product items related to this context variable.

This parameter is optional. Pass a null value if it is not specified.

item_adr

A pointer to the location of the start address for the 14-element cross-product array. The location will be application-accessible memory created by Oracle Trace during image activation. The location is accessible during the entire image execution, avoiding any potential access violations. By using array offsets, the product can subsequently assign values to items without having to call the epc_cf_value routine (thereby avoiding call overhead).

This parameter is applicable to products that want to get the address of the array on a one-time basis and then, at a later time, use direct references to offsets within the array to get specific cross-product items.

If the context parameter is specified, the returned address is valid only until the epc_delete_context routine is called. If the address is used after that, erroneous data will be returned.

This parameter is optional. Pass a null value if it is not specified.

Description

The epc_get_cf_items routine returns all values for the cross-product items for this process or thread of execution if a context-variable parameter is specified.

This routine is used by client/server products that need to pass cross-product item values from the client process of the product to the server process of the product.

The product's client process must call the epc_get_cf_items routine to retrieve a list of cross-product item values of the client process. It is the responsibility of the product to transport the cross-product item values to the server process. If the product client process is multi-threaded, it must also call the epc_context routine prior to calling the epc_get_cf_items routine in order to create context for the thread running in the client process.

The product server process must call the associated epc_set_cf_items routine to set the values of the cross-product item values.

Return Values

See Also

epc_set_cf_items, epc_context

epc_init

Purpose

Registers with Oracle Trace that a process is using an instrumented product.

Format

status=epc_init(api_version,vendor,product,version,
[registration_id],[product_instance_eventflags],[returned_eventflags],
max_event,[eventflag_option],[offset],[shmem_id],[filename],
[callback_routine],epcfctx_ptr)

C Binding

sb4 epc_init(api_version,vendor,product,version,
[registration_id],[product_instance_eventflags],[returned_eventflags],
max_event,[eventflag_option],[offset],[shmem_id],[filename],
[callback_routine],epcfctx_ptr)

sb4 api_version;

sb4 vendor;

sb4 product;

text *version

text *registration_id;

sb4 *product_instance_eventflags;

sb4 **returned_eventflags;

sb4 max_event;

sb4 eventflag_option;

ub4 offset;

sb4 shmem_id;

text *filename;

void(*callback_routine)( );

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

version

For a description of this parameter, refer to "Parameter Descriptions".

registration_id

A null-terminated string that describes a specific function in a product. For data collection to occur, the string must be identical to the registration ID specified when the collection was scheduled.

product_instance_eventflags

Oracle Trace Collection Services release 7.3 did not inherently support multiple instances of a product running within a single process. To keep track of events on a per instance level, a product could keep a separate set of eventflags for each instance and pass them to all the Oracle Trace calls to allow per-instance level tracing.

With the addition of the epcfctx_ptr parameter on the epc_init and other calls, Oracle Trace now directly supports multiple instances within a single process. Each instance of a product calls epc_init directly and Oracle Trace manages the eventflags and collections, drastically reducing the complexity for products that fall into this paradigm.

For products using the Oracle Trace Collection Services release 8.0 or higher, there should be no reason to use the product_instance_eventflags; they are kept for backwards compatibility only.

For products using Oracle Trace Collection Services prior to release 8.0 and with the need for this functionality, please read on.

The product_instance_eventflags parameter is an eventflags array preallocated by the product with a size of max_event +1. By specifying these flags on the epc_init call, the product instance gives up the ability to have collections scheduled for it by the Oracle Trace Manager. Oracle Trace uses its own eventflags structure to communicate collection activation and deactivation. This communication mechanism is not available with product_instance_eventflags in use.

The instance of the product can control collections only through the use of the epc_collect and epc_cancel routines. Passing the product_instance_eventflags on the epc_collect and epc_cancel routines ensures the proper events get turned on and off.

To ensure the proper events are logged, the product_instance_eventflags must also be passed to all Oracle Trace event logging routines.

In Oracle Trace Collection Services release 8.0 and higher, the per-instance identifier of a product is the epcfctx_ptr parameter returned on the epc_init call and passed on to the other Oracle Trace routines. No other coordination is required.

You must specify the product_instance_eventflags parameter if you use the EPC_K_LOCAL value in the eventflag_option parameter.

returned_eventflags

Use this parameter if you wish to control collections using the Oracle Trace Manager or the Oracle Trace command line interface. The product calling the epc_init routine passes an address to which the read-only address can be written.

You must specify this parameter if you use the EPC_K_ALLOC value in the eventflag_option parameter because EPC_K_ALLOC has Oracle Trace allocate space for the event flags within a shared memory region created by Oracle Trace.

max_event

The largest event number defined in the product.

eventflag_option

Where and how event flag arrays are stored. The event flag options are as follows:

• EPC_K_ALLOC - For products that do not contain their own shared memory regions or that do not want to alter their current shared memory regions. Oracle Trace connects to its own available shared region and returns the address of an array within that region for use by the product. Oracle Trace recommends the use of EPC_K_ALLOC.
• EPC_K_LOCAL - For products that allocate local storage for an event flag array. This option is offered for compatibility with previous Oracle Trace versions; however, for most applications the recommended option is EPC_K_ALLOC.

This parameter is optional. Pass a 0 if it is not specified.

offset

This parameter is not yet supported in Oracle Trace. Pass a 0.

shmem_id

This parameter is not yet supported in Oracle Trace. Pass a 0.

filename

This parameter is not yet supported in Oracle Trace. Pass a 0.

callback_routine

Routine to call whenever the product takes part in a new collection. This is useful if global flags are used or if anything needs to be reset each time a new collection is activated.

epcfctx_ptr

This parameter is filled in by Oracle Trace upon successful completion of this routine. This context uniquely describes to Oracle Trace that particular instance of the product. This parameter is passed on future Oracle Trace calls to identify the instance of the product for the proper tagging of events and the starting and stopping of collections.

The caller should allocate a variable of type EPCFCTX and pass its address on all Oracle Trace calls. This parameter must persist for the lifetime of the product instance. Care must be taken to ensure it is available to all event logging points.

Description

The epc_init routine registers a product with Oracle Trace. If specified, the initial values for either the product_instance_eventflags or the returned_eventflags are returned synchronously. This allows the product to determine which events are to be collected immediately following the call to the epc_init routine. However, the values of the event flags change to reflect the requested events in the event sets for the product in any active eollections.

As collections become active, Oracle Trace notifies the product process of the returned_eventflags for that specific collection. Because of the communication involved and the asynchronous nature by which you can schedule data collections, the values of the returned_eventflags can change asynchronously.

Product_instance_eventflags are set and cleared through calls to the epc_collect and epc_cancel routines.

Return Values

epc_remove_reg_id

Purpose

Removes a registration ID from a product.

Format

status=epc_remove_reg_id(api_version,vendor,product,version,
registration_id,[cf_item_number],epcfctx_ptr)

C Binding

sb4 epc_remove_reg_id(api_version,vendor,product,version,
registration_id,[cf_item_number],epcfctx_ptr)

sb4 api_version;

sb4 vendor;

sb4 product;

text *version

text *registration_id;

ub4 cf_item_number;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

version

For a description of this parameter, refer to "Parameter Descriptions".

registration_id

A null-terminated string that describes a specific function in a product. For data collection to occur, the string must be identical to the registration ID specified when the collection was scheduled.

cf_item_number

Ties the registration ID string to the value of a cross-product item at the time of the call. This allows cross-product item values to be directly related to string values.

This parameter is optional. Pass a 0 if it is not specified.

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_remove_reg_id routine removes a registration ID for a product. A product can call this routine as often as necessary, depending upon the number of registration identifiers it wishes to disassociate from a process.

Return Values

See Also

epc_add_reg_id

epc_set_cf_items

Purpose

Sets values for all the cross-product items for this process or thread of execution if a context parameter is specified.

Format

status=epc_set_cf_items(api_version,cf_items,[context])

C Binding

sb4 epc_set_cf_items(api_version,cf_items,[context])

sb4 api_version;

sb4 cf_items[];

sb4 context;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

cf_items

The address of a list of integers used to return cross-product item values. The number of elements in this list, currently 14, is indicated by the constant EPC_K_MAXCFITEM in the epc.h file. The list of cross-product items values is returned from the call to epc_get_cf_items by the client portion of the product.

context

An integer value that corresponds to the context parameter returned from the call to the epc_context routine.

This parameter is optional. Pass a null value if it is not specified.

Description

The epc_set_cf_items routine sets all values for the cross-product items for this process or thread of execution if a context-variable parameter is specified.

This routine is used by client/server products that need to pass cross-product item values from the client process of the product to the server process of the product.

The product's client process must call the epc_get_cf_items routine to retrieve a list of cross-product item values of the client process. It is the responsibility of the product to transport the cross-product item values to the server process. If the product client process is multi-threaded, it must also call the epc_context routine prior to calling the epc_get_cf_items routine in order to create context for the thread running in the client process.

The product server process must call the epc_set_cf_items routine to set the values of the cross-product items.

Return Values

See Also

epc_get_cf_items, epc_context

epc_start_event

Purpose

Posts an occurrence of the start of a duration event.

Format

status=epc_start_event(api_version,vendor,product,event_id,handle,
[context],[event_rec],[event_rec_size],[option],[cf_items],[product_instance_eventflags],
epcfctx_ptr)

C Binding

sb4 epc_start_event(api_version,vendor,product,event_id,handle,
context],[event_rec],[event_rec_size],[option],[cf_items],[product_instance_eventflags],
epcfctx_ptr)

sb4 api_version;

sb4 vendor;

sb4 product;

sb4 event_id;

sb4 *handle;

sb4 context

text *event_rec;

sb4 event_rec_size;

sb4 option;

sb4 *cf_items;

sb4 *product_instance_eventflags;

EPCFCTX *epcfctx_ptr;

Parameters

api_version

For a description of this parameter, refer to "Parameter Descriptions".

vendor

For a description of this parameter, refer to "Parameter Descriptions".

product

For a description of this parameter, refer to "Parameter Descriptions".

event_id

The event identifier (numeric) for the event. The event_id can range in value from 1 to 128.

handle

The address of an integer to return a process unique event handle for a particular event instance. The handle is passed in the corresponding call to the epc_end_event routine for the event.

context

The thread context parameter passed to the epc_end_event routine. Events cannot start in one thread and end in another.

This parameter is optional. Pass a 0 if it is not specified.

event_rec

The address of a record buffer containing the product-specific item values for an event.

This parameter is optional. Pass a null value if it is not specified.

event_rec_size

The length in bytes of the contents of the event_rec parameter.

This parameter is optional, unless event_rec is specified. Pass a 0 if event_rec_size is not specified.

option

This parameter is not yet supported in Oracle Trace. Pass a 0.

cf_items

The address of a cross-product items array that replaces the default cross-product items array. Normally, if the product definition states that a cross-product item is to be logged for a certain event, the value for that cross-product item is obtained from the internal Oracle Trace cross-product items array. This default method requires no product intervention and is well-suited to applications that do not have multiple threads of execution.

For products that have multiple threads of execution, use this parameter to track cross-product items on a per-thread basis. Call the epc_get_cf_items routine to get the values of the cross-product items for the thread, and save them in a per-thread storage area. On each subsequent Oracle Trace event call you can pass the address of those stored cross-product items as the cf_items parameter. This tells Oracle Trace that you wish to use the values stored at that address rather than the values stored in the normal internal Oracle Trace cross-product items array.

This parameter is optional. Pass a 0 if it is not specified.

product_instance_eventflags

This parameter is provided for the Oracle Trace Collection Services release 7.3 and allows for a product to keep track of collections for multiple instances within the same process. This support is inherent in Oracle Trace Collection Services release 8.0 and is supplied through the epcfctx_ptr parameter.

The product_instance_eventflags parameter should be the same as the one passed on the epc_collect and epc_cancel calls for this instance of the product. Oracle Trace will use the eventflag settings in this array to determine if the event should be collected or not.

If your product does not have multiple instances per process or is using Oracle Trace Collection Services release 8.0 or higher, this parameter should be passed as a 0.

epcfctx_ptr

For a description of this parameter, refer to "Parameter Descriptions".

Description

The epc_start_event routine enables a given product to post the start of a duration event.

Return Values

See Also

epc_event, epc_end_event

Prev Next

Copyright © 1997 Oracle Corporation. All Rights Reserved.

Library Product Contents Index