Oracle Enterprise Manager Oracle Trace User's Guide

Library

Product

Contents

Index

Oracle Trace Routines

Calling Oracle Trace Routines
epc_add_reg_id
epc_cancel
epc_cf_value
epc_collect
epc_context
epc_delete_context
epc_end_event
epc_event
epc_flush
epc_get_cf_items
epc_init
epc_remove_reg_id
epc_set_cf_items
epc_start_event

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

The description of each routine has the following parts:

Purpose

What the routine does

Format

The routine call with its parameter list

C Binding

The format, specific to C

Parameters

A detailed description of each parameter

Description

A detailed description of the routine

Return Values

A list of possible values returned for the routine

See Also

A list of other routines that affect or are used with this routine. Not included if not applicable.

Purpose	What the routine does
Format	The routine call with its parameter list
C Binding	The format, specific to C
Parameters	A detailed description of each parameter
Description	A detailed description of the routine
Return Values	A list of possible values returned for the routine
See Also	A list of other routines that affect or are used with this routine. Not included if not applicable.

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 8-1 lists the Oracle Trace routines and briefly describes their use. The complete routine descriptions are in alphabetical order later in this chapter.

Table 8-1: Oracle Trace Routines

For All Applications

Use this routine

If you want to...

epc_init

register the product with Oracle Trace. This routine only needs to be called once for each image activation. It must be called before any other Oracle Trace calls take place.

epc_add_reg_id

add a registration ID for a product. This routine can be called multiple times by a product.

epc_remove_reg_id

remove a registration ID for a product.

For All Applications Collecting Duration and Point Events

Use this routine

If you want to record the...

epc_start_event

start of a duration event.

epc_end_event

end of a duration event.

epc_event

execution of a point event.

For Applications Using Cross-Product Data

Use this routine

If you want to...

epc_set_cf_items

pass cross-product item values from a client process to a server process.

epc_cf_value

assign values to cross-product items.

epc_get_cf_items

retrieve all cross-product items to a buffer.

For Multi-Threaded Applications Collecting Items on a Per-Thread Basis

Use this routine

If you want to denote the...

epc_context

start of a new thread or resumption of an existing thread. This routine is used in multi-threaded products to collect resource utilization items on a per-thread basis.

epc_delete_context

end of a thread.

For Applications Wishing to Control Collections from Within the Application

Use this routine

If you want to...

epc_collect

start a collection from within a product.

epc_cancel

stop a collection that was started with epc_collect.

epc_flush

flush the record cache of collections for which the process is currently collecting data, or of collections to which the process has previously been bound.

Table 8-1: Oracle Trace Routines
For All Applications
Use this routine	If you want to...
epc_init	register the product with Oracle Trace. This routine only needs to be called once for each image activation. It must be called before any other Oracle Trace calls take place.
epc_add_reg_id	add a registration ID for a product. This routine can be called multiple times by a product.
epc_remove_reg_id	remove a registration ID for a product.
For All Applications Collecting Duration and Point Events
Use this routine	If you want to record the...
epc_start_event	start of a duration event.
epc_end_event	end of a duration event.
epc_event	execution of a point event.
For Applications Using Cross-Product Data
Use this routine	If you want to...
epc_set_cf_items	pass cross-product item values from a client process to a server process.
epc_cf_value	assign values to cross-product items.
epc_get_cf_items	retrieve all cross-product items to a buffer.
For Multi-Threaded Applications Collecting Items on a Per-Thread Basis
Use this routine	If you want to denote the...
epc_context	start of a new thread or resumption of an existing thread. This routine is used in multi-threaded products to collect resource utilization items on a per-thread basis.
epc_delete_context	end of a thread.
For Applications Wishing to Control Collections from Within the Application
Use this routine	If you want to...
epc_collect	start a collection from within a product.
epc_cancel	stop a collection that was started with epc_collect.
epc_flush	flush the record cache of collections for which the process is currently collecting data, or of collections to which the process has previously been bound.

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.

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 256 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 added to 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 bytes or counted strings. The unsigned bytes 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 of a predetermined size. The first byte contains the size of the string; the remainder is the string itself.
ASCIW: a variable-length string of a predetermined size. 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.

String items must be passed to the Oracle Trace user-defined buffer as counted strings. In counted strings, a count of the number of characters in the string precedes the string itself, for example, a business function name such as accounts payable.

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.

Return Values

Each routine has a possible set of return values that correspond to the informational and error messages displayed by Oracle Trace.

epc_add_reg_id

Purpose

Adds a registration ID for a product and can also be used to relate an internal string with 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])

C Binding

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

text *registration_id;

ub4 cf_item_number;

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

version

text

read

reference

registration_id

text

read

reference

cf_item_number

ub4

read

by value

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
vendor	sb4	read	value
product	sb4	read	value
version	text	read	reference
registration_id	text	read	reference
cf_item_number	ub4	read	by value

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

vendor

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

product

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

registration_id

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

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.

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

epc_s_badcfitem

Bad cross-product item number.

epc_s_badfac

Bad product ID displayed.

epc_s_badfacver

Bad product version passed.

epc_s_badregid

Bad product registration ID passed.

epc_s_badvendor

Bad vendor ID passed.

epc_s_facverreq

Product version required.

epc_s_nodcfexists

No data collection file exists.

epc_s_notinstall

Oracle Trace software is not installed.

epc_s_success

The call was successful.

epc_s_badcfitem	Bad cross-product item number.
epc_s_badfac	Bad product ID displayed.
epc_s_badfacver	Bad product version passed.
epc_s_badregid	Bad product registration ID passed.
epc_s_badvendor	Bad vendor ID passed.
epc_s_facverreq	Product version required.
epc_s_nodcfexists	No data collection file exists.
epc_s_notinstall	Oracle Trace software is not installed.
epc_s_success	The call was successful.

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, [writable_eventflags])

C Binding

sb4 epc_cancel(api_version,vendor,product,version,collection_name, [writable_eventflags])

text *collection_name;

text *writable_eventflags;

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

version

text

read

reference

collection_name

text

read

reference

writable_eventflags

sb4

read

value

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
vendor	sb4	read	value
product	sb4	read	value
version	text	read	reference
collection_name	text	read	reference
writable_eventflags	sb4	read	value

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

vendor

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

product

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

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.

writable_eventflags

The address of event flags that should be modified when this collection is canceled. This allows the user to have multiple copies of event flags per product, per process, and to pass in the exact event flags they wish to have modified in the call to the epc_cancel routine. This address of this parameter should be the same for the epc_event, epc_start_event, and epc_end_event routines.

If this parameter is not used, the event flags specified in the call to the epc_init routine are modified.

This parameter is optional. Pass a 0 if it is not specified. Oracle Corporation recommends that you do not use this parameter.

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

epc_s_colnotfound

Collection not found.

epc_s_datafilereq

Datafile required.

epc_s_initreq

epc_init call required.

epc_s_noheap

Not enough heap space.

epc_s_success

The call was successful.

epc_s_colnotfound	Collection not found.
epc_s_datafilereq	Datafile required.
epc_s_initreq	epc_init call required.
epc_s_noheap	Not enough heap space.
epc_s_success	The call was successful.

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])

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

item_num

sb4

read

value

item_val

sb4

read

value

context

sb4

read

value

item_adr

sb4

modify

reference

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
item_num	sb4	read	value
item_val	sb4	read	value
context	sb4	read	value
item_adr	sb4	modify	reference

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

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_s_badcfitem

Bad cross-product item number.

epc_s_baditem_adr

Bad item_adr parameter passed.

epc_s_baditem_num

Bad item_num parameter passed.

epc_s_baditem_val

Bad item_val parameter passed.

epc_s_badthread

Bad context parameter passed.

epc_s_disabled

Collection is disabled.

epc_s_insargs

Insufficient parameters passed.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_success

The call was successful.

epc_s_badcfitem	Bad cross-product item number.
epc_s_baditem_adr	Bad item_adr parameter passed.
epc_s_baditem_num	Bad item_num parameter passed.
epc_s_baditem_val	Bad item_val parameter passed.
epc_s_badthread	Bad context parameter passed.
epc_s_disabled	Collection is disabled.
epc_s_insargs	Insufficient parameters passed.
epc_s_notinstall	Oracle Trace is not installed.
epc_s_success	The call was successful.

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, [writable_eventflags],col_max_size)

C Binding

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

sb4 *overriding_eventflags;

text *collection_name;

text *fdf_name;

sb4 *writable_eventflags;

ub4 col_max_size;

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

version

text

read

reference

overriding_eventflags

sb4

read

value

collection_name

text

read

reference

fdf_name

text

read

reference

writable_eventflags

sb4

read

value

col_max_size

ub4

read

value

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
vendor	sb4	read	value
product	sb4	read	value
version	text	read	reference
overriding_eventflags	sb4	read	value
collection_name	text	read	reference
fdf_name	text	read	reference
writable_eventflags	sb4	read	value
col_max_size	ub4	read	value

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

vendor

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

product

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

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.

writable_eventflags

The address of event flags that should be modified when this collection is canceled. This allows the user to have multiple copies of event flags per product, per process, and to pass in the exact event flags to be modified in the call to the epc_cancel routine. For most applications, only one set of event flags is needed. It should be allocated using the epc_init routine.

This parameter is optional. Pass a 0 if it is not specified. Oracle Corporation recommends that you do not use this parameter.

col_max_size

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

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 writable 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.

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

Return Values

epc_s_appendrd

File append read failed.

epc_s_appendseek

File append seek failed.

epc_s_appendwrt

File append write failed.

epc_s_badfac

Bad product ID displayed.

epc_s_badfacver

Bad product version passed.

epc_s_cdfseek

Seek error in collection definition file.

epc_s_colactive

Collection already active.

epc_s_colnotfound

Collection not found.

epc_s_crecdf

Error creating collection definition file.

epc_s_datafilereq

Datafile required.

epc_s_facnotcol

Product not collecting.

epc_s_facverreq

Product version required.

epc_s_fdffilereq

Product definition file required.

epc_s_fdfrderr

Error reading product definition file.

epc_s_initreq

epc_init call required.

epc_s_noheap

Not enough heap space.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_ogetmach

Get os name, machine name error.

epc_s_opecdf

Error opening collection definition file.

epc_s_opedcf

Error opening data collection file.

epc_s_opefdf

Error opening product definition file.

epc_s_success

The call was successful.

epc_s_writdcf

Error writing to data collection file.

epc_s_wrtver

Error writing version record.

epc_s_wrtcdf

Error writing collection definition file.

epc_s_appendrd	File append read failed.
epc_s_appendseek	File append seek failed.
epc_s_appendwrt	File append write failed.
epc_s_badfac	Bad product ID displayed.
epc_s_badfacver	Bad product version passed.
epc_s_cdfseek	Seek error in collection definition file.
epc_s_colactive	Collection already active.
epc_s_colnotfound	Collection not found.
epc_s_crecdf	Error creating collection definition file.
epc_s_datafilereq	Datafile required.
epc_s_facnotcol	Product not collecting.
epc_s_facverreq	Product version required.
epc_s_fdffilereq	Product definition file required.
epc_s_fdfrderr	Error reading product definition file.
epc_s_initreq	epc_init call required.
epc_s_noheap	Not enough heap space.
epc_s_notinstall	Oracle Trace is not installed.
epc_s_ogetmach	Get os name, machine name error.
epc_s_opecdf	Error opening collection definition file.
epc_s_opedcf	Error opening data collection file.
epc_s_opefdf	Error opening product definition file.
epc_s_success	The call was successful.
epc_s_writdcf	Error writing to data collection file.
epc_s_wrtver	Error writing version record.
epc_s_wrtcdf	Error writing collection definition file.

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

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

context

sb4

read/write

reference

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
context	sb4	read/write	reference

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

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

epc_s_badthread

Bad context parameter passed.

epc_s_disabled

Collection is disabled.

epc_s_insargs

Insufficient parameters passed.

epc_s_nothread

No context parameter was passed.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_success

The call was successful.

epc_s_badthread	Bad context parameter passed.
epc_s_disabled	Collection is disabled.
epc_s_insargs	Insufficient parameters passed.
epc_s_nothread	No context parameter was passed.
epc_s_notinstall	Oracle Trace is not installed.
epc_s_success	The call was successful.

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

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

context

sb4

read

value

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
context	sb4	read	value

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

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

epc_s_badthread

Bad context parameter passed.

epc_s_disabled

Collection is disabled.

epc_s_insargs

Insufficient parameters passed.

epc_s_nothread

No context parameter was passed.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_success

The call was successful.

epc_s_badthread	Bad context parameter passed.
epc_s_disabled	Collection is disabled.
epc_s_insargs	Insufficient parameters passed.
epc_s_nothread	No context parameter was passed.
epc_s_notinstall	Oracle Trace is not installed.
epc_s_success	The call was successful.

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],[eventflags])

C Binding

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

sb4 event_rec_size;

sb4 option;

sb4 *cf_items;

sb4 *eventflags;

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

event_id

sb4

read

value

handle

sb4

write

value

context

sb4

read

value

event_rec

text

modify

reference

event_rec_size

sb4

read

value

option

sb4

read

value

cf_items

sb4

read

reference

eventflags

sb4

read

reference

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
vendor	sb4	read	value
product	sb4	read	value
event_id	sb4	read	value
handle	sb4	write	value
context	sb4	read	value
event_rec	text	modify	reference
event_rec_size	sb4	read	value
option	sb4	read	value
cf_items	sb4	read	reference
eventflags	sb4	read	reference

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

vendor

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

product

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

event_id

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

handle

An address value that identifies the duration event. It must be identical to the one passed on the epc_start_event routine.

context

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

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 supported for Oracle Trace release 1.3. 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.

eventflags

The address of an event flags array that replaces any event flags specified in the call to the epc_init routine. This parameter is for use only by applications that use epc_collect and epc_cancel to control collections from within the application.

If the writable_eventflags parameter is used in the call to epc_collect, the same address must be passed to the epc_end_event routine.

Using this parameter can prevent data files from becoming too large for products that have multiple threads and perform work within the context of a single process on behalf of many outside resources. For these products, it might be desirable to limit collection to each thread or outside resource request.

If the product is controlling its own collections through the epc_collect routine and has a per-thread or per-resource context block, it can use per-thread collections. Each thread calls the epc_collect routine with the event flags array from its context block. Subsequent calls to event routines will pass the event flags array from the threads context block to determine if an event should be logged.

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

Description

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

Return Values

epc_s_badevnt

Bad event ID parameter passed.

epc_s_badevntrec

Bad event record parameter passed.

epc_s_badfac

Bad product ID displayed.

epc_s_badhandl

Bad handle parameter passed.

epc_s_badthread

Bad context parameter passed.

epc_s_disabled

Collection is disabled.

epc_s_evtnotcol

Event is not being collected.

epc_s_excdmaxeve

event_id exceeds maximum on epc_init.

epc_s_facnotcol

Product not collecting.

epc_s_illbuflen

Record buffer larger than maximum.

epc_s_insargs

Insufficient parameters specified.

epc_s_nodcfexists

No data collection file exists.

epc_s_noevnt

No event ID parameter specified.

epc_s_nofac

No product parameter specified.

epc_s_nohandl

No handle parameter specified.

epc_s_notinstall

Oracle Trace software is not installed.

epc_s_success

The call was successful.

epc_s_thread_not_cur

Thread ID not current thread.

epc_s_writdcf

Error writing to data collection file.

epc_s_badevnt	Bad event ID parameter passed.
epc_s_badevntrec	Bad event record parameter passed.
epc_s_badfac	Bad product ID displayed.
epc_s_badhandl	Bad handle parameter passed.
epc_s_badthread	Bad context parameter passed.
epc_s_disabled	Collection is disabled.
epc_s_evtnotcol	Event is not being collected.
epc_s_excdmaxeve	event_id exceeds maximum on epc_init.
epc_s_facnotcol	Product not collecting.
epc_s_illbuflen	Record buffer larger than maximum.
epc_s_insargs	Insufficient parameters specified.
epc_s_nodcfexists	No data collection file exists.
epc_s_noevnt	No event ID parameter specified.
epc_s_nofac	No product parameter specified.
epc_s_nohandl	No handle parameter specified.
epc_s_notinstall	Oracle Trace software is not installed.
epc_s_success	The call was successful.
epc_s_thread_not_cur	Thread ID not current thread.
epc_s_writdcf	Error writing to data collection file.

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],[eventflags])

C Binding

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

sb4 event_rec_size;

sb4 option;

sb4 *cf_items;

sb4 *eventflags;

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

event_id

sb4

read

value

handle

sb4

write

value

context

sb4

read

value

event_rec

text

modify

reference

event_rec_size

sb4

read

value

option

sb4

read

value

cf_items

sb4

read

reference

eventflags

sb4

read

reference

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
vendor	sb4	read	value
product	sb4	read	value
event_id	sb4	read	value
handle	sb4	write	value
context	sb4	read	value
event_rec	text	modify	reference
event_rec_size	sb4	read	value
option	sb4	read	value
cf_items	sb4	read	reference
eventflags	sb4	read	reference

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

vendor

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

product

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

event_id

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

context

The 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 supported for Oracle Trace release 1.3. Pass a 0.

cf_items

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

eventflags

The address of an event flags array that replaces any event flags specified in the call to the epc_init routine.

If the product is controlling its own collections through the epc_collect routine and has a per-thread or per-resource context block, it can use per-thread collections. Each thread calls the epc_collect routine with the event flags array from its context block. Subsequent call to epc_event routines will pass the event flags array from the threads context block to determine if an event should be logged.

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

Description

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

Return Values

epc_s_badevnt

Bad event ID parameter passed.

epc_s_badevntrec

Bad event record parameter passed.

epc_s_badfac

Bad product ID displayed.

epc_s_badhandl

Bad handle parameter passed.

epc_s_badthread

Bad context parameter passed.

epc_s_disabled

Collection is disabled.

epc_s_evtnotcol

Event is not being collected.

epc_s_excdmaxeve

event_id exceeds maximum on epc_init.

epc_s_facnotcol

Product not collecting.

epc_s_illbuflen

Record buffer larger than maximum.

epc_s_insargs

Insufficient parameters specified.

epc_s_nodcfexists

No data collection file exists.

epc_s_noevnt

No event ID parameter specified.

epc_s_nofac

No product parameter specified.

epc_s_nohandl

No handle parameter specified.

epc_s_notinstall

Oracle Trace software is not installed.

epc_s_success

The call was successful.

epc_s_thread_not_cur

Thread ID not current thread.

epc_s_writdcf

Error writing to data collection file.

epc_s_badevnt	Bad event ID parameter passed.
epc_s_badevntrec	Bad event record parameter passed.
epc_s_badfac	Bad product ID displayed.
epc_s_badhandl	Bad handle parameter passed.
epc_s_badthread	Bad context parameter passed.
epc_s_disabled	Collection is disabled.
epc_s_evtnotcol	Event is not being collected.
epc_s_excdmaxeve	event_id exceeds maximum on epc_init.
epc_s_facnotcol	Product not collecting.
epc_s_illbuflen	Record buffer larger than maximum.
epc_s_insargs	Insufficient parameters specified.
epc_s_nodcfexists	No data collection file exists.
epc_s_noevnt	No event ID parameter specified.
epc_s_nofac	No product parameter specified.
epc_s_nohandl	No handle parameter specified.
epc_s_notinstall	Oracle Trace software is not installed.
epc_s_success	The call was successful.
epc_s_thread_not_cur	Thread ID not current thread.
epc_s_writdcf	Error writing to data collection file.

epc_flush

Purpose

Flushes the record cache of collections for which the process is currently collecting data, or collections to which the process has previously been bound. This routine should only be used 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

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

Description

The epc_flush routine flushes the record cache of collections for which the process is currently collecting data, or collections to which the process has previously been bound. 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

epc_s_colnofound

Collection not found.

epc_s_datafilereq

Datafile required.

epc_s_initreq

epc_init call required.

epc_s_noheap

Not enough heap space.

epc_s_success

This call was successful.

epc_s_writdcf

Error writing to data collection file.

epc_s_colnofound	Collection not found.
epc_s_datafilereq	Datafile required.
epc_s_initreq	epc_init call required.
epc_s_noheap	Not enough heap space.
epc_s_success	This call was successful.
epc_s_writdcf	Error writing to data collection file.

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])

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

cf_items

sb4 array

modify

reference

context

sb4

read

value

item_adr

sb4

modify

reference

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
cf_items	sb4 array	modify	reference
context	sb4	read	value
item_adr	sb4	modify	reference

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

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_C_NUM_CROSS_FAC_ITEMS. The list of cross-product items values is returned from the call to epc_get_cf_items by the client portion of the product.

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 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

epc_s_badcfitms

Bad list of cross-product items passed.

epc_s_badthread

Bad context parameter passed.

epc_s_insargs

Insufficient parameters passed.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_success

The call was successful.

epc_s_badcfitms	Bad list of cross-product items passed.
epc_s_badthread	Bad context parameter passed.
epc_s_insargs	Insufficient parameters passed.
epc_s_notinstall	Oracle Trace is not installed.
epc_s_success	The call was successful.

epc_init

Purpose

Registers a process using a product with Oracle Trace to enable collection for that product.

Format

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

C Binding

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

text *registration_id;

sb4 *predefined_eventflags;

sb4 **returned_eventflags;

sb4 max_event;

sb4 eventflag_option;

ub4 offset;

sb4 shmem_id;

text *filename;

void(*callback_routine)( );

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

version

text

read

reference

registration_id

text

read

reference

predefined_eventflags

sb4

read

reference

returned_eventflags

sb4

write

reference

max_event

sb4

read

value

eventflag_option

sb4

read

value

offset

ub4

read

value

shmem_id

sb4

read

value

filename

text

read

reference

callback_routine( )

void

read

reference

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
vendor	sb4	read	value
product	sb4	read	value
version	text	read	reference
registration_id	text	read	reference
predefined_eventflags	sb4	read	reference
returned_eventflags	sb4	write	reference
max_event	sb4	read	value
eventflag_option	sb4	read	value
offset	ub4	read	value
shmem_id	sb4	read	value
filename	text	read	reference
callback_routine( )	void	read	reference

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

vendor

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

product

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

registration_id

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

predefined_eventflags

Use this parameter if you wish to control collections solely by use of the epc_collect and epc_cancel routines. If you use this parameter, the process cannot participate in collections started by the Oracle Trace Manager. The product calling the epc_init routine allocates an integer array (size of max_event parameter plus 1) and then passes the array address to Oracle Trace.

You must specify this 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. 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 supported in Oracle Trace release 1.3. Pass a 0.

shmem_id

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

filename

This parameter is not supported in Oracle Trace release 1.3. 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.

Description

The epc_init routine registers a product with Oracle Trace. If specified, the initial values for either the predefined_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 values in the corresponding product for the active collections.

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 collection, the values of the returned_eventflags can change asynchronously.

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

Return Values

epc_s_badevntflgs

Bad eventflags passed.

epc_s_badfac

Bad product ID displayed.

epc_s_badfacver

Bad product version passed.

epc_s_badoffset

Bad offset value.

epc_s_badoption

Bad option value.

epc_s_badregid

Bad product registration ID passed.

epc_s_badvendor

Bad vendor ID passed.

epc_s_disabled

Collection is disabled.

epc_s_fac_limit_excd

Product limit exceeded.

epc_s_facverreq

Product version required.

epc_s_filnamreq

Filename required.

epc_s_init2

epc_init called twice for product.

epc_s_maxevent

max_event must be greater than 0.

epc_s_not_impl

Not yet implemented.

epc_s_noheap

Not enough heap space.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_preeflagsreq

predefined_eventflags required.

epc_s_proallocerr

alloc failed process file.

epc_s_ret_eflgsreq

Eventflags required.

epc_s_shmemreq

shmem ID or filename required.

epc_s_success

The call was successful.

epc_s_badevntflgs	Bad eventflags passed.
epc_s_badfac	Bad product ID displayed.
epc_s_badfacver	Bad product version passed.
epc_s_badoffset	Bad offset value.
epc_s_badoption	Bad option value.
epc_s_badregid	Bad product registration ID passed.
epc_s_badvendor	Bad vendor ID passed.
epc_s_disabled	Collection is disabled.
epc_s_fac_limit_excd	Product limit exceeded.
epc_s_facverreq	Product version required.
epc_s_filnamreq	Filename required.
epc_s_init2	epc_init called twice for product.
epc_s_maxevent	max_event must be greater than 0.
epc_s_not_impl	Not yet implemented.
epc_s_noheap	Not enough heap space.
epc_s_notinstall	Oracle Trace is not installed.
epc_s_preeflagsreq	predefined_eventflags required.
epc_s_proallocerr	alloc failed process file.
epc_s_ret_eflgsreq	Eventflags required.
epc_s_shmemreq	shmem ID or filename required.
epc_s_success	The call was successful.

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])

C Binding

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

text *registration_id;

ub4 cf_item_number;

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

version

text

read

reference

registration_id

text

read

reference

cf_item_number

ub4

read

by value

Parameter	Datatype	Access	Passed by...
status	sb4	write	not applicable
api_version	sb4	read	value
vendor	sb4	read	value
product	sb4	read	value
version	text	read	reference
registration_id	text	read	reference
cf_item_number	ub4	read	by value

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

vendor

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

product

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

registration_id

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

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.

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

epc_s_badfac

Bad product ID displayed.

epc_s_badfacver

Bad product version passed.

epc_s_badregid

Bad product registration ID passed.

epc_s_badvendor

Bad vendor ID passed.

epc_s_facverreq

Product version required.

epc_s_insargs

Insufficient parameters specified.

epc_s_nodcfexists

No data collection file exists.

epc_s_notinstall

Oracle Trace software is not installed.

epc_s_success

The call was successful.

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

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

cf_items

sb4 array

modify

reference

context

sb4

read

value

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

cf_items

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 server process must call the epc_set_cf_items routine to set the values of the cross-product items.

Return Values

epc_s_badcfitms

Bad list of cross-product items passed.

epc_s_badthread

Bad context parameter passed.

epc_s_insargs

Insufficient parameters passed.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_success

The call was successful.

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],[eventflags])

C Binding

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

sb4 event_rec_size;

sb4 option;

sb4 *cf_items;

sb4 *eventflags;

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

event_id

sb4

read

value

handle

sb4

write

value

context

sb4

read

value

event_rec

structure

modify

reference

event_rec_size

sb4

read

value

option

sb4

read

value

cf_items

sb4

read

value

eventflags

sb4

read

value

api_version

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

vendor

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

product

For a description of this parameter, refer to Parameter Descriptions on page 8-6.

event_id

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

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 context parameter passed to the epc_end_event routine. Events cannot start on one thread and end on 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 supported in Oracle Trace release 1.3. Pass a 0.

cf_items

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

eventflags

If the writable_eventflags parameter is used in the call to epc_collect, the same address must be passed to the epc_end_event routine.

If the product is controlling its own collections through the epc_collect routine and has a per-thread or per-resource context block, it can use per-thread collections. Each thread calls the epc_collect routine with the event flags array from its context block. Subsequent calls to epc_event routines will pass the event flags array from the threads context block to determine whether an event should be logged.

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

Description

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

Return Values

epc_s_badevnt

Bad event ID parameter passed.

epc_s_badevntrec

Bad event record parameter passed.

epc_s_badfac

Bad product ID displayed.

epc_s_badhandl

Bad handle parameter passed.

epc_s_badthread

Bad context parameter passed.

epc_s_disabled

Collection is disabled.

epc_s_evtnotcol

Event is not being collected.

epc_s_facnotcol

Product not collecting.

epc_s_illbuflen

Record buffer larger than maximum.

epc_s_insargs

Insufficient parameters specified.

epc_s_nodcfexists

No data collection file exists.

epc_s_noevnt

No event ID parameter specified.

epc_s_nofac

No product parameter specified.

epc_s_nohandl

No handle parameter specified.

epc_s_notinstall

Oracle Trace software is not installed.

epc_s_success

The call was successful.

Oracle Trace Routines

Table 8-1: Oracle Trace Routines

Required Parameters

Purpose

Parameters Parameter Datatype Access Passed by... status sb4 write not applicable api_version sb4 read value vendor sb4 read value product sb4 read value version text read reference registration_id text read reference cf_item_number ub4 read by value

api_version

See Also

Purpose

Parameters Parameter Datatype Access Passed by... status sb4 write not applicable api_version sb4 read value vendor sb4 read value product sb4 read value version text read reference collection_name text read reference writable_eventflags sb4 read value

api_version

Return Values epc_s_colnotfound Collection not found. epc_s_datafilereq Datafile required. epc_s_initreq epc_init call required. epc_s_noheap Not enough heap space. epc_s_success The call was successful.

See Also

Purpose

Parameters Parameter Datatype Access Passed by... status sb4 write not applicable api_version sb4 read value item_num sb4 read value item_val sb4 read value context sb4 read value item_adr sb4 modify reference

api_version

epc_collect

Purpose

api_version

See Also

Purpose

Parameters Parameter Datatype Access Passed by... status sb4 write not applicable api_version sb4 read value context sb4 read/write reference

api_version

Return Values epc_s_badthread Bad context parameter passed. epc_s_disabled Collection is disabled. epc_s_insargs Insufficient parameters passed. epc_s_nothread No context parameter was passed. epc_s_notinstall Oracle Trace is not installed. epc_s_success The call was successful.

See Also

Purpose

Parameters Parameter Datatype Access Passed by... status sb4 write not applicable api_version sb4 read value context sb4 read value

api_version

Return Values epc_s_badthread Bad context parameter passed. epc_s_disabled Collection is disabled. epc_s_insargs Insufficient parameters passed. epc_s_nothread No context parameter was passed. epc_s_notinstall Oracle Trace is not installed. epc_s_success The call was successful.

See Also

Purpose

api_version

See Also

Purpose

api_version

epc_flush

Purpose

Parameters Parameter Datatype Access Passed by... status sb4 write not applicable api_version sb4 read value

api_version

Return Values epc_s_colnofound Collection not found. epc_s_datafilereq Datafile required. epc_s_initreq epc_init call required. epc_s_noheap Not enough heap space. epc_s_success This call was successful. epc_s_writdcf Error writing to data collection file.

See Also

Purpose

Parameters Parameter Datatype Access Passed by... status sb4 write not applicable api_version sb4 read value cf_items sb4 array modify reference context sb4 read value item_adr sb4 modify reference

api_version

Return Values epc_s_badcfitms Bad list of cross-product items passed. epc_s_badthread Bad context parameter passed. epc_s_insargs Insufficient parameters passed. epc_s_notinstall Oracle Trace is not installed. epc_s_success The call was successful.

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

version

text

read

reference

registration_id

text

read

reference

cf_item_number

ub4

read

by value

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

vendor

sb4

read

value

product

sb4

read

value

version

text

read

reference

collection_name

text

read

reference

writable_eventflags

sb4

read

value

Return Values

epc_s_colnotfound

Collection not found.

epc_s_datafilereq

Datafile required.

epc_s_initreq

epc_init call required.

epc_s_noheap

Not enough heap space.

epc_s_success

The call was successful.

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

item_num

sb4

read

value

item_val

sb4

read

value

context

sb4

read

value

item_adr

sb4

modify

reference

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

context

sb4

read/write

reference

Return Values

epc_s_badthread

Bad context parameter passed.

epc_s_disabled

Collection is disabled.

epc_s_insargs

Insufficient parameters passed.

epc_s_nothread

No context parameter was passed.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_success

The call was successful.

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

context

sb4

read

value

Return Values

epc_s_badthread

Bad context parameter passed.

epc_s_disabled

Collection is disabled.

epc_s_insargs

Insufficient parameters passed.

epc_s_nothread

No context parameter was passed.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_success

The call was successful.

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

Return Values

epc_s_colnofound

Collection not found.

epc_s_datafilereq

Datafile required.

epc_s_initreq

epc_init call required.

epc_s_noheap

Not enough heap space.

epc_s_success

This call was successful.

epc_s_writdcf

Error writing to data collection file.

Parameters

Parameter

Datatype

Access

Passed by...

status

sb4

write

not applicable

api_version

sb4

read

value

cf_items

sb4 array

modify

reference

context

sb4

read

value

item_adr

sb4

modify

reference

Return Values

epc_s_badcfitms

Bad list of cross-product items passed.

epc_s_badthread

Bad context parameter passed.

epc_s_insargs

Insufficient parameters passed.

epc_s_notinstall

Oracle Trace is not installed.

epc_s_success

The call was successful.