NAME
idl - Invokes the Interface Definition Language (IDL)
compiler [required for developing distributed DCE
applications]
SYNOPSIS
idl filename [argument] ...
RELATED INFORMATION
Books: OSF DCE Application Development Guide.
1 – ARGUMENTS
1.1 – -client
-client file_type
Determines which client files to generate. If you do not specify
this argument, the compiler generates all client files. The file
types are as follows:
none Does not generate client files.
stub Generates only a client stub file.
aux Generates only a client auxiliary file. A client auxiliary
file is generated only if the interface contains any out-of-
line or self-pointing types.
all Generates client stub and client auxiliary files. This is the
default and is the same as not specifying the -client argument.
1.2 – -server
-server file_type
Determines which server files to generate. If you do not specify
this argument, the compiler generates all server files. The file
types are as follows:
none Does not generate server files.
stub Generates only a server stub file.
aux Generates only a server auxiliary file. A server auxiliary
file is generated only if the interface contains any out-of-
line, self-pointing, or pipe types.
all Generates server stub and server auxiliary files. This is the
default and is the same as not specifying the -server argument.
1.3 – -standard
-standard standard_type
Allows you to specify portable or extended features of the OSF DCE.
This option is useful when you perform builds. The standard_type
argument specifies what IDL features to enable. If you do not
specify this argument, the compiler generates warning messages for
all features that are not available in the previous version of OSF
DCE.
You can specify one of the following values for the standard_type
argument:
portable Allows only the language features available in OSF DCE
Version 1.0.2.
dce_v10 Synonymous with the portable argument.
dec_v10 Allows all language features supported by the standard
dce_v10 argument, plus a set of HP extensions to
its products based on OSF DCE Version 1.0.
extended Allows all language features supported in the current
version of the compiler. This is the default.
dce_v11 Synonymous with the extended argument.
The following example command line compiles the IDL interface test.idl
and enables extended features of the OSF DCE:
$ idl test.idl -standard extended
1.4 – -cstub
-cstub filename Specifies a pathname for the client stub file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -cstub argument, the idl compiler appends _cstub.c to the C source file and _cstub.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension.
1.5 – -sstub
-sstub filename Specifies a pathname for the server stub file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -sstub argument, the idl compiler appends _sstub.c to the C source file and _sstub.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension.
1.6 – -caux
-caux filename Specifies a pathname for the client auxiliary file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -caux argument, the idl compiler appends _caux.c to the C source file and _caux.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension.
1.7 – -saux
-saux filename Specifies a pathname for the server auxiliary file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -caux argument, the idl compiler appends _saux.c to the C source file and _saux.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension.
1.8 – -header
-header header_file Allows you to specify a name for the generated header file. By default the compiler takes the basename of the IDL file and appends the .h extension to it.
1.9 – -out
-out directory Places the output files in the directory you specify. By default the compiler places the output files in the current working directory.
1.10 – -Idirectory
-Idirectory Specifies a directory name that contains imported interface definition files. You can specify more than one directory by specifying additional -Idirectory arguments on the command line. The compiler searches the directories in the order you list them. If a file is present in more than one directory, the compiler takes the first occurrence of the file. The default behavior of the compiler is to first search the current directory, then all directories you specify, then the system IDL directory. The directory you specify is also passed to the C preprocessor and the C compiler.
1.11 – -no_def_idir
-no_def_idir Specifies that the compiler search only the current directory for imported files. When you use this with -Idirectory, the compiler searches only the directories you list, not the current directory, and not the system IDL directory.
1.12 – -no_mepv
-no_mepv Causes the compiler to not generate a manager entry point vector (EPV) in the server stub. Use this argument if the manager code and IDL file do not use the same operation names. If you specify this argument you must provide an EPV within the manager code that can be used when the interface is registered with the RPC server runtime. The name of the type that you construct an EPV with is if_name_vmajor-version_minor-version_epv_t where if_name is the interface name. It is not necessary to use this argument if the operation names in the manager code and IDL file are the same. In this case, the compiler generates a manager EPV in the server stub using the names of the operations in the IDL file. (For information on registering the server, see the rpc_intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.)
1.13 – -cepv
-cepv Generates local routines in the client stub file (filename_cstub.c) and defines a Client Entry Point Vector (CEPV) of the name if_name_vmajor-version_minor-version_c_epv where if_name is the interface name. The CEPV contains the addresses of the local routines. The client code must call the routines indirectly by using the addresses in the CEPV; otherwise, the stub routines in the client stub file must have the same names as the operations in the IDL file. (For information on registering the server, see the rpc_intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.)
1.14 – -cpp_cmd
-cpp_cmd 'c_preprocessor_command_line' Allows you to specify a C preprocessor other than the default. The compiler invokes the C preprocessor found in that command line. The output of the C preprocessor is an expanded version of the input file(s) containing replacement text for any preprocessor directives (for example, the #include preprocessor directive).
1.15 – -cpp_opt
-cpp_opt 'command_options' Specifies additional options to be passed to the C preprocessor. You can add options to the command line used to invoke the C preprocessor independent of the -cpp_cmd argument. The IDL compiler concatenates the -cpp_cmd, -cpp_opt, -D, -U, -I arguments and the source filename into a command used to invoke the C preprocessor. The compiler repeats this process for each Attribute Configuration File (ACF) and IDL file.
1.16 – -no_cpp
-no_cpp Does not invoke the C preprocessor. Note that the C preprocessor must be run on files that contain preprocessor directives (such as #include) in the interface definition.
1.17 – -cc_cmd
-cc_cmd 'command_line' Invokes the C compiler and compiler options you specify in the 'command_line' argument rather than the default C compiler and compiler options. When used with the -lang cxx option, the -cc_cmd option specifies the C++ compiler.
1.18 – -cc_opt
-cc_opt 'command_options' Specifies additional options to be passed to the C compiler. You can add options to the command line used to invoke the C compiler independent of the -cc_cmd argument. The IDL compiler concatenates the -cc_cmd, -cc_opt, -I arguments and the source filename into a command that invokes the C compiler. This procedure is done for each generated stub or auxiliary file. When used with the -lang cxx option, the -cc_opt option specifies the C++ compiler options.
1.19 – -Dname
-Dname[=definition] Defines a symbol name and an optional value to be passed to the C preprocessor. You can use this method of defining a symbol instead of using #define in the source code. You can use more than one -Dname argument on the command line. This argument has no effect if you use the -no_cpp argument.
1.20 – -Uname
-Uname Removes (undefines) any initial definition of a symbol name as defined by -Dname. You can use this method to remove a symbol name instead of using #undef in the source code. You can use more than one -Uname argument on the command line. This argument has no effect if you use the -no_cpp argument. If you define and undefine a name on the same command line, undefining takes precedence.
1.21 – -space_opt
-space_opt Generates code for the marshalling and unmarshalling of data that is optimized for space, rather than speed.
1.22 – -syntax_only
-syntax_only Checks only the syntax of the IDL file, but does not generate any output files.
1.23 – -keep
-keep file_types
Specifies which files to retain. To produce the object modules,
the IDL compiler first creates C source modules, then invokes the
target C compiler to produce object modules, and finally, deletes
the C source modules. If you do not use -keep, only the object
modules are saved.
The file types are as follows:
none Does not save the C source or the object modules. Does
not invoke the C compiler.
c_source Saves only the C source modules. Does not invoke the C
compiler.
object Saves only the object modules.
all Saves both the C source and the object modules.
1.24 – -bug
-bug n -no_bug n Retains (-bug) or does not retain (-no_bug) a specified bug from earlier IDL compiler versions. (This in an NCS compatibility argument and is not supported in OSF DCE Version 1.1).
1.25 – -stdin
-stdin
Takes the standard output of a previous utility as the input to the
idl command. For example:
$ pipe type my_filename.idl | idl -stdin
1.26 – -version
-version Displays the current version of the IDL compiler.
1.27 – -v
-v Prints informational messages (verbose mode) on the screen while the compiler is running.
1.28 – -no_warn
-no_warn Suppresses compiler warning messages.
1.29 – -confirm
-confirm Displays all the idl command arguments you chose, but does not compile the source IDL file. If you use this with the -v argument, informational messages about how the compiler behaves if you do not use -confirm are displayed but no corresponding actions are performed.
1.30 – -template_client
-template_client filename Requests that the IDL compiler generate a C source file containing a template implementation of each routine that must appear in the client application to use the specified IDL interface. If you do not specify an extension for filename, the compiler assigns the file extension .c.
1.31 – -template_manager
-template_manager filename Requests that the IDL compiler generate a C source file containing a template implementation of each routine and operation that must appear in the manager module of the server side of an application to use the specified IDL interface. If you do not specify an extension for filename, the compiler assigns the file extension .c.
1.32 – -trace
-trace value
Enables event logging. You can specify one of the following values
for the value argument:
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.
1.33 – -lang
-lang {c, cxx, fortran}
Allows you to select a programming language.
If you are generating stubs and include files for application code
written in C++, you must specify cxx as the language of choice when
you compile the application's IDL file. When appropriate, you can
extend the class hierarchy and derive other classes from this one,
to implement some or all interface operations. The C++ compiler
gives a warning if any functions in the interface class have not
been implemented. Avoid overwriting the manager class header file
by using the -no_cxxmgr argument in conjunction with the -lang cxx
argument.
If you are generating stubs and include files for application code
written in FORTRAN, you must specify FORTRAN as the language of
choice when you compile the application's IDL file.
If you do not specify -lang fortran or -lang cxx, the default value
is the C programming language or -lang c.
1.34 – -no_cxxmgr
-no_cxxmgr Prevents the compiler from overwriting the manager class header file. Use this argument in conjunction with the -lang cxx argument if you implement application-specific C++ code in the manager class header file.
2 – DESCRIPTION
The idl command invokes the IDL compiler to convert an interface
definition, written in IDL, into output files. The output files include
a header file, server stub file, client stub file, and auxiliary files.
The compiler constructs the names of the output files by keeping the
basename of the interface definition source file but replacing the
filename extension with the new extension (or suffix and extension)
appropriate to the newly generated type of output file. For example,
math.idl could produce math_sstub.c or math_sstub.o for the server stub.
The idl command accepts the following input:
+ An interface definition filename.
+ Arguments to indicate either special actions to be performed by the
compiler, or special properties of the input or output files.
The IDL compiler searches through directories for any related ACF.
For example, if you compile a file named source.idl, the compiler
automatically searches for a file named source.acf. The compiler also
searches for any imported IDL file (and its related ACF). The compiler
searches for these files using the following order:
1. The current working directory. The compiler always searches this
directory unless you specify the -no_def_idir and -Idirectory
arguments together.
2. Any imported directory. The compiler searches each directory you
are specifying in the -Idirectory argument.
3. The system IDL directory. The compiler automatically imports
nbase.idl, which resides in the system IDL directory. The compiler
always searches this directory unless you specify the -no_def_idir
argument.
4. The directory specified in the source filename. If you explicitly
specify a directory in the source IDL pathname, then that directory
is searched for the corresponding ACF. For example,
$ idl usera:[my_dir]my_source.idl
causes the IDL compiler to look for usera:[my_dir]my_source.acf
if my_source.acf is not found in the directories in 1,2 and 3.
Note that this directory is not searched for any imported IDL file
or its corresponding ACF.
Restrictions
The following filenames are reserved by the IDL compiler. Naming an IDL
file with one of these names may result in unexpected behavior.
iovector.idl lbase.idl nbase.idl ncastat.idl
ndrold.idl rpc.idl rpcbase.idl rpcpvt.idl
rpcsts.idl rpctypes.idl twr.idl uuid.idl
3 – CAUTIONS
The IDL compiler generates ANSI C code. It also supports C compilers
that are not fully ANSI compliant although a warning message may occur
during compilation of the stubs by the C compiler. A C compiler that
is not fully ANSI compliant may generate the following warning messages:
+ warning: & before array or function: ignored
+ warning: enumeration type clash, operator =
4 – FILES
SYS$SYSTEM:DCE$IDL.EXE
IDL Compiler
SYS$COMMON:[DCE$LIBRARY]
System IDL directory for imported files
SYS$COMMON:[DCE$LIBRARY]NBASE.IDL
Predefined IDL types
SYS$COMMON:[DCE$LIBRARY]file.ext
All .idl or .h files that are part of DCE RPC
5 – EXAMPLES
1. Invoke the IDL compiler to compile the interface definition file
test.idl and keep the generated C source modules. Only server
files are generated. The server stub default filename is
overridden by creating a file named test_ss.c for the server
stub module.
$ idl test.idl -keep c_source -client none -sstub test_ss.c
2. Invoke the IDL compiler to compile the interface definition file
test.idl, but do not run the C preprocessor. The manager entry
point vector is not defined in the generated server stub module.
The IDL compiler searches the parent directory of the current
directory for any IDL files that test.idl could import. The
generated output files are located in the output subdirectory
under the current directory.
$ idl test.idl -no_cpp -no_mepv -I.. -out [.output]
6 – DCL Command Interface
The following is the DCL syntax for the IDL compiler. Except where
noted, IDL DCL commands are equivalent to the IDL universal command
syntax documented in the idl section of the OSF DCE Application
Development Reference. See the Reference documentation for a
complete description of the universal command syntax interface to
the IDL compiler.
NAME
IDL - Invokes the Interface Definition Language (IDL) Compiler
SYNOPSIS
IDL file-spec [qualifier]...
6.1 – QUALIFIERS
6.1.1 /CLIENT_FILES
/CLIENT_FILES [=(option[,...])]
/NOCLIENT_FILES
Specify one or more of the following options.
ALL (default)
[NO]AUXILIARY [=filename]
NONE
[NO]STUB [=filename]
This qualifier is equivalent to the -client argument
in the universal syntax.
6.1.2 /SERVER_FILES
/SERVER_FILES [=(option[,...])]
/NOSERVER_FILES
Specify one or more of the following options:
ALL (default)
[NO]AUXILIARY [=filename]
NONE
[NO]STUB [=filename]
This qualifier is equivalent to the -server argument
in the universal syntax.
6.1.3 /STANDARD
/STANDARD [=[NO]PORTABLE | DCE_V10 | DEC_V10 | EXTENDED ]
/STANDARD=PORTABLE (default)
This qualifier is equivalent to the -standard[standard_type]
argument in the universal syntax. This universal syntax
argument is documented in the section of the HP DCE
Product Guide that describes additional IDL command options.
6.1.4 /HEADER_FILE
/HEADER_FILE = filename
/HEADER_FILE=file_spec.H (default)
This qualifier is equivalent to the -header header_file
argument in the universal syntax.
6.1.5 /OUTPUT_DIRECTORY
/OUTPUT_DIRECTORY [=directory]
/NOOUTPUT_DIRECTORY (default)
This qualifier is equivalent to the -out directory
argument in the universal syntax.
6.1.6 /INCLUDE_DIRECTORY
/INCLUDE_DIRECTORY [=(pathname [,...])] (default)
/NOINCLUDE_DIRECTORY
These qualifiers are equivalent to the -Idirectory
and -no_def_idir arguments in the universal syntax.
6.1.7 /ENTRY_POINT_VECTOR
/ENTRY_POINT_VECTOR [=(option[,...])]
/NOENTRY_POINT_VECTOR
/ENTRY_POINT_VECTOR=(NOCLIENT, MANAGER) (default)
Specify one or more of the following options:
ALL
[NO]CLIENT
[NO]MANAGER
NONE
This qualifier provides a function similar to those of the
-cepv and -no_mepv arguments in the universal syntax.
The /ENTRY_POINT_VECTOR command qualifier controls
generation of the client and manager entry point vectors
through the keywords CLIENT and MANAGER. In the universal
command syntax, two separate idl options (-cepv and
-no_mepv) control generation of the client and manager
entry point vectors.
The following example universal command syntax generates
both client and server entry point vectors:
$ idl fpe_server.idl -cepv
The equivalent DCL command is as follows:
$ idl fpe-server.idl /ENTRY_POINT_VECTOR=CLIENT,MANAGER
If one or more options are specified, the DCL syntax
requires you to specify all required options. Options
that are not listed are not enabled.
6.1.8 /PREPROCESS
/PREPROCESS
/NOPREPROCESS (default)
These qualifiers are equivalent to the
-cpp_cmd 'c_preprocessor_command_line' and -no_cpp
arguments in the universal syntax.
6.1.9 /CC_COMMAND
/CC_COMMAND [=command-line]
/NOCC_COMMAND
/CC_COMMAND="CC/G_FLOAT/STANDARD=NOPORTABLE" (default)
This qualifier is equivalent to the -cc_cmd 'command_line'
argument in the universal syntax.
6.1.10 /CC_QUALIFIERS
/CC_QUALIFIERS [="command-qualifiers"]
/NOCC_QUALIFIERS (default)
This qualifier is equivalent to the -cc_opt 'command_options'
argument in the universal syntax.
6.1.11 /DEFINE
/DEFINE [=(identifier[=definition][,...])]
/NODEFINE (default)
This qualifier is equivalent to the -Dname[=definition]
argument in the universal syntax.
6.1.12 /UNDEFINE
/UNDEFINE [=(identifier[,...])]
/NOUNDEFINE (default)
This qualifier is equivalent to the -Uname argument
in the universal syntax.
6.1.13 /OPTIMIZE
/OPTIMIZE [=({SPEED | SPACE })]
/OPTIMIZE = SPEED (default)
This qualifier is equivalent to the -space_opt
argument in the universal syntax.
6.1.14 /SYNTAX_ONLY
/SYNTAX_ONLY
/NOSYNTAX_ONLY (default)
This qualifier is equivalent to the -syntax_only
argument in the universal syntax.
6.1.15 /KEEP
/KEEP [=option]
/NOKEEP
Specify one of the following options:
ALL
C_SOURCE
NONE (equivalent to /NOKEEP)
OBJECT (default)
This qualifier is equivalent to the -keep file_types
argument in the universal syntax.
6.1.16 /REPAIR
/REPAIR [=(option[,...])]
/NOREPAIR
Specify one of the following options:
[NO]BOOLEAN_CONSTANTS
[NO]EXTRA_PAD_BYTES
[NO]MISSING_PAD_BYTES
ALL (default)
NONE
These qualifiers are equivalent to the -bug n and -no_bug n
arguments in the universal syntax. The values
[NO]BOOLEAN_CONSTANTS, [NO]EXTRA_PAD_BYTES, and
[NO]MISSING_PAD_BYTES correspond to -bug 1, -bug 2, and
-bug 3 respectively in the universal syntax.
6.1.17 /VERSION
/VERSION
/NOVERSION (default)
This qualifier is equivalent to the -version
argument in the universal syntax.
6.1.18 /LOG
/LOG
/NOLOG (default)
This qualifier is equivalent to the -v argument in
the universal syntax.
6.1.19 /WARNINGS
/WARNINGS (default)
/NOWARNINGS
This qualifier is equivalent to the -no_warn
argument in the universal syntax.
6.1.20 /VERIFY
/VERIFY
/NOVERIFY (default)
This qualifier is equivalent to the -confirm
argument in the universal syntax.
6.1.21 /TRACE
/TRACE [=(option[,...)]
/NOTRACE
Specify one or more of the following options:
[NO]LOG_MANAGER
EVENTS=({ALL|CALLS|CONTEXT_HANDLES|ERRORS|NONE|MISCELLANEOUS}[,...])
/NOTRACE (default)
This qualifier is equivalent to the -trace value argument in the
universal syntax, which is documented in the HP DCE Product
Guide.
6.1.22 /LANGUAGE
/LANGUAGE [={CC | CXX | FORTRAN}]
/LANGUAGE=CC (default)
This qualifier is equivalent to the -lang argument in the
universal syntax.
6.1.23 /DIAGNOSTICS
/DIAGNOSTICS [=filename]
/NODIAGNOSTICS (default)
Specifies that a diagnostic file listing the errors reported
by a compilation should be generated for LSE. If you do not
specify a filename, the compiler uses the basename of the IDL
file and appends the .DIA extension to it.
7 – Event Logger
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"
7.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.)
7.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)
8 – rpclm
NAME
rpclm - Starts the command line interface to the RPC Event
Logger Log Manager
SYNOPSIS
rpclm "listening event string binding"
ARGUMENTS
inquire Inquire about the currently logged events and
determine the name of the active log file.
log Specify additional events to log: all,
none, calls, context, errors, or misc.
unlog Disable logging of the specified event types:
all, none, calls, context, errors, or misc.
file Change the output device or file to which events
are logged.
quit Terminate the rpclm session.
help Display a description of the rpclm command
interface commands.
8.1 – DESCRIPTION
The RPC Event Logger records information in an event log about
application execution. After enabling the Log Manager when you
compile the interface, you can use the Log Manager command line
options to modify event logging parameters at runtime.
Follow these steps to enable the RPC Log Manager:
1. Use the -trace log_manager option at IDL compilation time.
2. Create the RPC_LOG_FILE symbol and assign it to a file
name or to screen output.
3. Execute the client or server process, or both.
4. When the first call is made to an interface compiled
with the -trace option, a listening event will be
generated into the event log. Invoke the rpclm command
interface by specifying the string binding from the
listening event.
EXAMPLES
To enable the Log Manager, use the following syntax:
$ idl file-name.idl -trace log_manager
To invoke the rpclm command interface, specify the string binding
from a listening event, as in the following example:
$ rpclm ncacn_ip_tcp:16.31.48.144[3820]
RELATED INFORMATION
"HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide"