NAME
idl -trace - Starts the RPC Event Logger
The idl -trace command enables event logging for an application
interface. The event logger records information about the
following types of events: interface calls, context handles,
errors, event logging itself, and a miscellaneous group of events.
SYNOPSIS
idl file-spec -trace {arguments}
ARGUMENTS
all Log all events
none Disable all previously specified trace options
calls Log events relating to start and end of all RPC calls
context Log events relating to context handle creation,
deletion, and rundown
errors Log errors
misc Log all miscellaneous events
log_manager Enable command interface support which allows
modification at runtime of event logging options
RELATED_INFORMATION
"HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide"
1 – DESCRIPTION
The RPC Event Logger records event information in an event
log, which can be directed to the terminal screen or to a file.
Use the -trace universal syntax (or /TRACE DCL interface) to
enable and modify event logging prior to linking the interface.
After linking the interface, you can use the Log Manager command
line interface (rpclm) or an OpenVMS symbol (RPC_LOG_FILE) to
modify event logging options at runtime.
The DCL interface to the event logger has the following syntax:
/[NO]TRACE =(option[,...])
Specify one or more of the following options:
[NO]LOG_MANAGER
EVENTS=({ALL|NONE|ERRORS|CALLS|CONTEXT_HANDLES|MISCELLANEOUS}[,...])
RPC events are as follows:
activate
A thread was assigned to process an RPC call on a
server, and the server stub has started
processing input arguments. The Event Data field
of the event log contains the string binding of
the client application making the call.
await_reply
The transmission of input arguments in a call
from a client application to a server has
completed. The event is generated by the client
stub. The client application is waiting for
output arguments from the server.
call_end
A call from a client application is complete and
the client stub is returning to the caller.
call_failure
A client stub terminated abnormally because
either an exception occurred or due to a failing
status. The Event Data field of the event log
contains the error text associated with the
exception or RPC status code.
call_start
A client application attempted to make a call to
a server. The event is generated by the stub
within the client application. The Event Data
field of the event log displays the string
binding of the server being contacted.
client_ctx_created
A client application has allocated a context
handle on a particular server. The Event Data
field of the event log contains the following
information about this event:
* The address representing the context handle in
the client address space (an opaque pointer)
* The UUID which can be used to identify the
corresponding context handle on the server
* The string binding of the server on which
the actual context resides
client_ctx_deleted
The client application representation of a
context handle is being deleted to reflect the
deletion of the context handle on the server. The
Event Data field of the event log contains the
following information about this event:
* The address representing the context handle
in the client address space (an opaque pointer)
* The UUID which can be used to identify the
corresponding context handle on the server
* The string binding of the server on
which the actual context resided
client_ctx_destroyed
A client application has destroyed the client
representation of a context handle through the
rpc_ss_destroy_client_context routine. The Event
Data field of the event log contains the
following information about this event:
* The address representing the context handle
in the client address space (an opaque pointer)
* The UUID which can be used to identify the
corresponding context handle on the server
* The string binding of the server on
which the actual context resided
context_created
A new context handle was created on a server and
returned from the application manager routine.
The Event Data field of the event log contains
both the application value of the context handle
and the UUID assigned to represent this context
handle.
context_deleted
A context handle on a server has been deleted by
the application manager routine. The Event Data
field of the event log contains both the
application value of the context handle and the
UUID assigned to represent this context handle.
context_modified
A context handle on a server was returned from
the application manager routine with a value that
is different from its previous value. The Event
Data field of the event log contains both the
application value of the context handle and the
UUID assigned to represent this context handle.
context_rundown
A context handle on a server was freed by the
context rundown procedure. The Event Data field
of the event log contains both the application
value of the context handle and the UUID assigned
to represent this context handle.
exception
An exception was detected in the server stub, and
the exception caused the call to terminate. The
Event Data field of the event log contains a text
description of the exception.
internal_error
A failure occurred in the support routines that
manage the event logger. Check the Event Data
field of the event log for a description of the
cause of the event. If the error does not seem
to indicate a transient network problem or an
environmental failure, report the failure in a
Software Performance Report (SPR).
listening
The RPC Log Manager has started to listen for
rpclm commands. The listening event is generated
by the portion of the RPC Log Manager built into
your application by the RPC run time when you
specify the -trace log_manager option on your IDL
compilation. The RPC Log Manager services the
requests generated by the rpclm command. You use
one of the string bindings from a listening event
to invoke the rpclm command interface.
log_events
Event logging was modified through the Log
Manager command interface rpclm. The Event Data
field of the event log contains the new set of
events being logged.
log_file
Event logging was modified through the Log
Manager command interface rpclm. The Event Data
field of the event log contains the new file name
for the event log. If no file name is displayed,
events are being logged to the screen.
log_start
A new event log was created or event logging was
resumed after being suspended by a user command
to the Log Manager command interface rpclm. The
Event Data field in the event log contains a list
of event types being logged.
log_stop Event logging was stopped through the Log Manager
interface rpclm.
manager_call
The server stub is about to call the application
manager routine.
manager_return
Control has just returned from the application
manager routine to the server stub.
rebind
A call from a client application to a server
failed. The Event Data field in the event log
shows the reason for the failure to contact the
server. The event is generated by the stub
within the client application. The call failed on
an auto_handle operation and the client is
attempting to rebind to the next server.
receive
Following the transmission of input arguments
from a client application call to a server, the
client received a reply and started processing
output arguments.
receive_fault
The client received a fault indicating a failure
on the server. The Event Data field of the event
log contains the RPC status that identifies the
failure. All failures have fault codes which you
can find in the file ncastat.idl. If the fault
code in the ncastat.idl file is too general (such
as "unspecified fault"), examine the server event
log for precise failure information.
status_fail
A failure status was encountered in the server
stub. The Event Data field of the event log
describes the failure.
terminate The server thread has completed processing the call
and has terminated.
transmit_fault
The server runtime is sending fault information
to the client application. The Event Data field
of the event log indicates the name of the fault
being sent. The fault information in this field
is listed in the ncastat.idl file. The fault
information in this field may be less descriptive
than the information logged about the actual
error. (See the exception or status_fail events
in the event log to obtain precise failure
information.)
2 – EXAMPLES
Compile the binopwk interface and enable event logging for all
events:
$ idl binopwk.idl -trace all
Compile the binopwk interface and enable event logging for errors:
$ idl binopwk.idl -trace errors
Compile the binopwk interface, enabling event logging for all
events as well as enabling the log manager interface:
$ idl binopwk.idl -trace all -trace log_manager
The event logger universal interface has the following DCL command
equivalents:
-trace all /TRACE=EVENTS=ALL
-trace log_manager /TRACE=LOG_MANAGER
-trace all -trace log_manager /TRACE=(LOG_MANAGER,EVENTS=ALL)
-trace errors -trace calls /TRACE=EVENTS=(ERRORS,CALLS)