Updated: 24 May 2001

Digital DCE for OpenVMS VAX and OpenVMS Alpha
Product Guide

<TIME> murp:17868/15 RPC Log Mgr log_events none

9. rpclm Window --- The user issues a log calls command to enable logging of call events.

   rpclm> log calls Event types: calls Events logged to terminal

10. Server Window --- The newest event log entry indicates that the Event Logger will start logging call events.

    <TIME> murp:17868/15 RPC Log Mgr log_events calls

11. rpclm Window --- Because logging output will increase now that call events are being logged, the user issues an rpclm command to redirect logging output to a file named server_calc.log. When the application terminates and logging is complete, the user can use a text editor to view and search for entries in the log. This log file will contain only those call events from the server process.

    rpclm> file server_calc.log Event types: calls Events logged to file 'server_calc.log'

12. Server Window --- The newest event log entry indicates that the logger will start redirecting logging information to file server_calc.log.

    <TIME> murp:17868/15 RPC Log Mgr log_file server_calc.log

13. Client Window --- The user invokes the client process a third time. The call events that occur during server execution are logged to file server_calc.log. The client process displays the output PASS 3 upon completion.

    $ client ncacn_ip_tcp 16.31.48.86 [3123] PASS 3

14. Server Log --- This is log file server_calc.log:

    $ 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

15. rpclm Window --- The user issues a file command to redirect event logging output from server_calc.log to the terminal screen. To do this, press the Return key without specifying a filename when the Log Manager prompts for one.

    rpclm> file New File Name: <RETURN> Event types: calls Events logged to terminal rpclm>

16. Server Window --- The final event in the server_calc.log file is a log_file event, which indicates that event logging output is being redirected, in this case to the terminal screen. Therefore, no filename is displayed to the right of the event name.

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

17.6 Event Names and Descriptions

Table 17-5 lists and describes RPC events.

Table 17-5 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: 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_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 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:

• Interoperability and portability issues as they relate to applications written in VAX FORTRAN
• A comprehensive example that introduces and illustrates several concepts
• General reference information about VAX FORTRAN and remote procedure calls, including a discussion about restrictions

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:

• Any client that you have correctly created in a Digital DCE RPC environment to use a DCE interface expressed in an IDL file will interoperate with any DCE RPC server that supports the interface.
• Any server that you have correctly created in a Digital DCE RPC environment to use a DCE interface expressed in an IDL file will interoperate with any DCE RPC client that makes calls on the interface.

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:

• Digital DCE RPC applications that contain code written in VAX FORTRAN in an OpenVMS environment and that use a DCE interface expressed in an IDL file will interoperate with any corresponding DCE server or DCE client. However, you can port these applications only to other Digital DCE environments.

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:

• The example client application reads time-card information, passes it to a server that calculates wages, and prints the results.
• Both the client and the portion of the server that calculates gross pay (the manager routine) are written in VAX FORTRAN.
• The initialization portion of the server application is written in C.

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.

Table 18-1 Example Files Created by the Programmer

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

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6532_DCE_PG_PRO_016.HTML