| Previous | Contents | Index |
<TIME> murp:17868/15 RPC Log Mgr log_events none |
rpclm> log calls Event types: calls Events logged to terminal |
<TIME> murp:17868/15 RPC Log Mgr log_events calls |
rpclm> file server_calc.log Event types: calls Events logged to file 'server_calc.log' |
<TIME> murp:17868/15 RPC Log Mgr log_file server_calc.log |
$ client ncacn_ip_tcp 16.31.48.86 [3123] PASS 3 |
$ TYPE server_calc.log |
<TIME> murp:17868/15 RPC Log Mgr log_start server_calc.log <TIME> murp:17868/15 fpe.setup activate ncacn_ip_tcp:16.31.48[2905] <TIME> murp:17868/15 fpe.setup terminate ncacn_ip_tcp:16.31.48[2905] <TIME> murp:17868/15 fpe.flt_overflw activate ncacn_ip_tcp:16.31.48[2905] <TIME> murp:17868/15 fpe.flt_overflw terminate <TIME> murp:17868/15 fpe.flt_underflw activate ncacn_ip_tcp:16.31.48[2905] <TIME> murp:17868/15 fpe.flt_underflw terminate <TIME> murp:17868/15 fpe.flt_divbyzer activate ncacn_ip_tcp:16.31.48[2905] <TIME> murp:17868/15 fpe.flt_divbyzer terminate <TIME> murp:17868/15 fpe.dble_overflw activate ncacn_ip_tcp:16.31.48[2905] <TIME> murp:17868/15 fpe.dble_overflw terminate <TIME> murp:17868/15 fpe.dble_underflw activate ncacn_ip_tcp:16.31.48[2905] <TIME> murp:17868/15 fpe.dble_underflw terminate <TIME> murp:17868/15 fpe.dble_divbyzer activate ncacn_ip_tcp:16.31.48[2905] <TIME> murp:17868/15 fpe.dble_divbyzer terminate |
rpclm> file New File Name: <RETURN> Event types: calls Events logged to terminal rpclm> |
<TIME> murp:17868/15 RPC Log Mgr log_file |
The RPC Event Logger is designed to help you debug your distributed application and is an enhancement over the basic diagnostics in the RPC product. The diagnostics alone provide minimal information. For example, the sample program called test2, which is provided with the Digital DCE software kit, generates the rpc_x_no_more_bindings exception when the client fails to contact the server. Without the aid of RPC event logging, this is the only diagnostic information available.
The following example shows the basic RPC diagnostic information that an application displays when an error occurs.
$ run test2 %CMA-F-EXCCOPLOS, exception raised; some information lost -DCERPC-E-NOMOREBINDINGS, no more bindings (dce / rpc) *** Unable to obtain server binding information $ |
If you enable RPC event logging by defining the symbol RPC_LOG_FILE, then the details of client execution can be captured in a file. From the event log, you can determine which servers the client tried to contact and the reason each attempt failed.
In the following event log example, the Event Data field on the rebind events indicates that the interface is not registered in the end point map and that a communications failure occurred. This information indicates that the server either is not running or it failed to register properly with the end point mapper.
The final event, call_failure, indicates that the call was terminated with the no more bindings status. This event indicates that the client tried all available servers but failed to communicate with any of them. (Note that in the first column the word <TIME> represents the actual value for time.)
$ run test2
<TIME> ko:11436/1 test2.test2_add log_start all
<TIME> ko:11436/1 test2.test2_add call_start ncacn_ip_tcp:16.20.16.27[]
<TIME> ko:11436/1 test2.test2_add rebind not registered in endpoint
map(dce/rpc)
<TIME> ko:11436/1 test2.test2_add call_start ncacn_dnet_nsp:4.262[]
<TIME> ko:11436/1 test2.test2_add rebind not registered in endpoint
map(dce/rpc)
<TIME> ko:11436/1 test2.test2_add call_start ncadg_ip_udp:16.20.16.27[]
<TIME> ko:11436/1 test2.test2_add rebind communic failure (dce/rpc)
<TIME> ko:11436/1 call_failure no more bindings (dce/rpc)
%CMA-F-EXCCOPLOS, exception raised; some information lost
-DCERPC-E-NOMOREBINDINGS, no more bindings (dce / rpc)
*** Unable to obtain server binding information
$
|
Table 17-5 lists and describes RPC events.
| 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 is 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 a failing status was returned. 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:
|
| 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:
|
| 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:
|
| 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 runtime 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 filename for the event log. If no filename 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 command 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 has 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.) |
This chapter explains how to use VAX FORTRAN in the development of distributed applications that make remote procedure calls.
This chapter provides the following information:
In general, an application you create in the Digital DCE RPC environment will interoperate with other DCE RPC applications and will port to other DCE platforms if it complies with the appropriate programming language standards. More specifically:
Typically, applications created in the DCE RPC environment are written in the C programming language. However, if you use the VAX FORTRAN support in the Digital DCE for OpenVMS VAX and OpenVMS Alpha software, the application will be subject to the following portability constraint:
The OpenVMS IDL compiler provides similar support for applications written in VAX FORTRAN as that provided for applications written in C. That is, you can write an RPC client in VAX FORTRAN or you can write one or more manager routines in the server side of the application in VAX FORTRAN. If you are unfamiliar with the tasks involved in developing an RPC application, see the chapter about application building in the OSF DCE Application Development Guide.
The VAX FORTRAN support consists of stubs that use VAX FORTRAN linkage conventions and a file that contains VAX FORTRAN definitions of the constants and types declared in an interface definition. (These conventions and definitions are explained in Section 18.3)
The following sections present a comprehensive example that demonstrates how you can create the various parts of a simple, distributed payroll application using VAX FORTRAN. The important features of this example are as follows:
All of the example application files referenced in this chapter are located in the following directory in your kit:
SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.PAYROLL]
Table 18-1 lists application files that normally would be created by the programmer for an application. To demonstrate application building, these application files are provided for you in the software kit. Table 18-2 in Section 18.2.3 lists the files generated by the IDL compiler for the example application.
Before you execute any of the example compilations, builds, or run commands in this chapter, copy all of the files listed in Table 18-1 to an empty directory. Compaq recommends that you read the file named README in the same subdirectory. Then build and run the examples.
| Filename | File Description |
|---|---|
| PAYROLL.IDL | The interface definition file that contains the application programming interface (API) to the remote procedure call calculate_pay(). |
| PRINT_PAY.FOR | The FORTRAN source file for the client side of the application. |
| SERVER.C | The FORTRAN source file that contains the initialization code for the server side of the application. |
| MANAGER.FOR | The FORTRAN source file for the server side of the application. |
| PAYROLL.COM | The command file that builds and runs the example application. |
| PAYROLL.DAT | The data input file for the example application. |
The programs, procedures, and data files in the payroll example should be the same in this chapter and in the specified subdirectory that came with your Digital DCE for OpenVMS VAX or OpenVMS Alpha software. For example, file PAYROLL.IDL as it appears in Section 18.2.2 should be identical to the following file:
SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.PAYROLL]PAYROLL.IDL
For all of the example files, if there is a difference between the file
as shown in this chapter and the file in the subdirectory, assume that
the file in the subdirectory is the correct one.
18.2.2 The Interface File and Data File (PAYROLL.IDL and PAYROLL.DAT)
The following interface, named PAYROLL.IDL, is part of the example application. The name of the remote procedure in the interface is calculate_pay(). The interface does not indicate that this procedure is written in VAX FORTRAN.
/*
** Copyright (c) 1993 by
** Digital Equipment Corporation, Maynard, Mass.
**
*/
[
uuid(d1b14181-6543-11ca-ba11-08002b17908e),
version(1.0)
]
interface payroll
{
const long string_data_len = 7;
typedef struct {
[string] char grade[string_data_len + 1];
/* Storage for a string must include space for a null terminator */
short regular_hours;
short overtime_hours;
} timecard;
void calculate_pay(
[in] timecard cards[1..7],
[out] long *pay
);
}
|
The next part of the example is the data file PAYROLL.DAT, which the client side of the application reads. The facts about each employee appear in 8 records. The first record contains the employee's name (40 characters) and grade (7 characters). Records 2 to 8 contain the number of regular hours and overtime hours worked on Monday to Sunday. Note that the time card structure defined in PAYROLL.IDL does not specify the employee's name in the data going to the remote procedure.
Jerry Harrison FOREMAN 8 1 8 1 8 2 8 2 8 1 0 4 0 0 Tony Hardiman WORKER 8 0 8 0 8 0 8 2 8 0 0 4 0 0 Mary Flynn WORKER 8 1 8 1 8 2 8 0 8 1 0 4 0 0 |
| Previous | Next | Contents | Index |