| Previous | Contents | Index |
To compile an RPC interface, you must invoke the IDL compiler. To compile an RPC interface for a VAX FORTRAN application, you must select the following IDL options:
The following example commands illustrate how to invoke the IDL compiler using the universal and DCL interfaces, respectively, to compile the sample VAX FORTRAN application interface:
$ idl payroll.idl -lang fortran -standard extended $ IDL/LANGUAGE=FORTRAN/STANDARD=EXTENDED PAYROLL.IDL |
As a result of this command, the IDL compiler generates the files listed in Table 18-2.
| Filename | File Description |
|---|---|
| PAYROLL_CSTUB.OBJ | The stub file generated by the IDL compiler for the client side of the application. |
| PAYROLL_SSTUB.OBJ | The stub file generated by the IDL compiler for the server side of the application. |
| PAYROLL.FOR | An include file that emulates the C language header file (.H) and that documents the valid syntax for subroutine calls that are used in the FORTRAN source files. This file will be called out by PAYROLL.COM and linked with the other application files because it refers to constants and types defined in the interface definition. |
| PAYROLL.FOR_H | A file generated by the IDL compiler that is used to build the stub files. |
File PAYROLL.FOR, as generated by the IDL compiler, is next.
C Generated by IDL compiler version DEC DCE Vn.n.n-n
C
C The following statements must appear in application code
C INCLUDE 'NBASE.FOR'
INTEGER*4 STRING_DATA_LEN
PARAMETER (STRING_DATA_LEN=7)
STRUCTURE /TIMECARD/
CHARACTER*8 GRADE
INTEGER*2 REGULAR_HOURS
INTEGER*2 OVERTIME_HOURS
END STRUCTURE
C SUBROUTINE CALCULATE_PAY(CARDS, PAY)
C RECORD /TIMECARD/ CARDS(7)
C INTEGER*4 PAY
|
As you read this chapter, it is important to remember that the
interface defined in file PAYROLL.IDL appears as VAX FORTRAN statements
in file PAYROLL.FOR. As a specific instance, consider the overtime
hours field. Its definition appears in PAYROLL.IDL as the statement
short overtime_hours, and in PAYROLL.FOR as the statement
INTEGER*2 OVERTIME_HOURS. The overtime hours data in file
PAYROLL.DAT is read into a data item of this type.
18.2.4 The Client Application Code for the Interface (PRINT_PAY.FOR)
Suppose that the directory in which the interface was compiled also contains file PRINT_PAY.FOR. This is the source file for the client side of the distributed application. Its contents follow.
C This is the client side of a payroll application that
C uses remote procedure calls.
C
PROGRAM PRINT_PAY
INCLUDE 'PAYROLL.FOR' ! Created by the IDL compiler from
! file PAYROLL.IDL.
C COPYRIGHT (C) 1993 BY DIGITAL EQUIPMENT CORP., MAYNARD MASSACHUSETTS.
C The structure of a time card is described in the included file.
RECORD /TIMECARD/ CARDS(7)
CHARACTER*40 NAME
CHARACTER*8 GRADE
INTEGER*4 PAY
INTEGER*4 I
C
C Read eight records for the current employee.
10 READ (4, 9000, END=100) NAME, GRADE ! First record
9000 FORMAT (A40, A8)
DO 20 I = 1, 7 ! Second through eighth records
READ (4,9010) CARDS(I).REGULAR_HOURS, CARDS(I).OVERTIME_HOURS
9010 FORMAT (I2, I2)
CARDS(I).GRADE = GRADE
20 CONTINUE
C
C Call remote procedure CALCULATE_PAY to calculate the gross pay.
CALL CALCULATE_PAY (CARDS, PAY)
C Display the current employee's name and gross pay.
WRITE (6, 9020) NAME, PAY
9020 FORMAT (1X, A40, 1X, I4 )
GO TO 10
C
100 STOP
C
END
|
To compile and link the client program PRINT_PAY.FOR, which at runtime makes remote procedure calls to a server that supports the payroll interface, use the following DCL commands. After you enter the LINK command, press <CTRL/Z>.
$ FORTRAN PRINT_PAY.FOR $ LINK PRINT_PAY, PAYROLL_CSTUB, DCE:DCE/OPT, DCE:DCE_VAXC/OPT |
Instead of using these two commands directly to build the client part of the application, you can invoke procedure PAYROLL.COM to build the entire application. See Section 18.2.8 for information about building and running this example.
This program reads its data from VAX FORTRAN logical unit 4. A DCL
command in procedure PAYROLL.COM defines the logical unit.
18.2.5 The Server Initialization File (SERVER.C)
Because all programming interfaces to the RPC runtime are specified in C, you must write the code that sets up the server in C. In this example, the server setup code (also called the initialization code) is in file SERVER.C.
This file is shown next. Both SERVER.C and PAYROLL.COM (shown in this section and in Section 18.2.8, respectively) contain the literal FORTRAN_payroll_mynode. Do not substitute a node name for mynode. The code in SERVER.C always exports its bindings using the entry name ".:/FORTRAN_payroll_mynode".
/* This is program SERVER.C that sets up the server for the application
code whose origin is FORTRAN subroutine CALCULATE.PAY. */
/*
** Copyright (c) 1993 by
** Digital Equipment Corporation, Maynard, Mass.
**
*/
#include <STDIO.H>
#include <FILE.H>
#include <DCE/DCE_ERROR.H>
#include "payroll.for_h" /* The IDL compiler created this file from
file PAYROLL.IDL. */
static char error_buf[dce_c_error_string_len+1];
static char *error_text(st)
error_status_t st;
{
error_status_t rst;
dce_error_inq_text(st, error_buf, &rst);
return error_buf;
}
main()
{
error_status_t st;
rpc_binding_vector_p_t bvec;
/* Register all supported protocol sequences with the runtime. */
rpc_server_use_all_protseqs(
rpc_c_protseq_max_calls_default,
&st
);
if (st != error_status_ok)
{
fprintf(stderr, "Can't use protocol sequence - %s\\n", error_text(st));
exit(1);
}
/* Register the server interface with the runtime. */
rpc_server_register_if(
payroll_v1_0_s_ifspec, /* From the IDL compiler; */
/* "v1_0" comes from the statement */
/* "version(1.0)" in file PAYROLL.IDL. */
NULL,
NULL,
&st
);
if (st != error_status_ok)
{
printf("Can't register interface - %s\\n", error_text(st));
exit(1);
}
/* Get the address of a vector of server binding handles. The
call to routine rpc_server_use_all_protseqs() directed the
runtime to create the binding handles. */
rpc_server_inq_bindings(&bvec, &st);
if (st != error_status_ok)
{
printf("Can't inquire bindings - %s\\n", error_text(st));
exit(1);
}
/* Place server address information into the local endpoint map. */
rpc_ep_register(
payroll_v1_0_s_ifspec,
bvec,
NULL,
(idl_char*)"FORTRAN Payroll Test Server",
&st
);
if (st != error_status_ok)
{
printf("Can't register ep - %s\\n", error_text(st));
}
/* Place server address information into the name service database. */
rpc_ns_binding_export(
rpc_c_ns_syntax_default,
(idl_char*)".:/FORTRAN_payroll_mynode",
payroll_v1_0_s_ifspec,
bvec,
NULL,
&st
);
if (st != error_status_ok)
{
printf("Can't export to name service - %s\\n", error_text(st));
}
/* Tell the runtime to listen for remote procedure calls.
Also, FORTRAN cannot support multiple threads of execution. */
rpc_server_listen((int)1, &st);
if (st != error_status_ok)
fprintf(stderr, "Error listening: %s\\n", error_text(st));
}
|
The server application code, written in VAX FORTRAN, is declared in file PAYROLL.IDL as calculate_pay(). The file MANAGER.FOR provides some additional application code for the server and it contains subroutine CALCULATE_PAY as follows:
SUBROUTINE CALCULATE_PAY(CARDS, PAY)
INCLUDE 'PAYROLL.FOR' ! Created by the IDL compiler from
! file PAYROLL.IDL.
C
C COPYRIGHT (C) 1993 BY DIGITAL EQUIPMENT CORP., MAYNARD MASSACHUSETTS.
C The structure of a time card is described in included file PAYROLL.FOR.
RECORD /TIMECARD/ CARDS(7)
INTEGER*4 PAY
INTEGER*4 I
PAY = 0
DO 10 I = 1, 7
C The basic hourly wage is $6.00.
PAY = PAY + 6 * CARDS(I).REGULAR_HOURS
C The following comparison does not include last character of GRADE,
C because it arrives as a null terminator.
IF (CARDS(I).GRADE(1:STRING_DATA_LEN) .EQ. 'FOREMAN') THEN
C The overtime hourly wage for a foreman is $12.00.
PAY = PAY + 12 * CARDS(I).OVERTIME_HOURS
ELSE
C The overtime hourly wage for a worker is $9.00.
PAY = PAY + 9 * CARDS(I).OVERTIME_HOURS
END IF
10 CONTINUE
RETURN
END
|
To create the file SERVER.EXE, which at runtime responds to remote procedure calls from a client that supports the payroll interface, use the following DCL commands. After you enter the LINK command, press <CTRL/Z>.
$ CC SERVER $ FORTRAN MANAGER $ LINK SERVER, MANAGER, PAYROLL_SSTUB, DCE:DCE/OPT, DCE:DCE_VAXC/OPT |
Instead of using these commands directly to build the server part of
the application, you can invoke procedure PAYROLL.COM to build the
entire application (see Section 18.2.8).
18.2.7 Client and Server Bindings
In order to make remote procedure calls, client applications must be bound to server applications. This is illustrated in the client program PRINT_PAY.FOR shown in Section 18.2.4. The source code in the client program uses the default [auto_handle] binding, which is enabled by the following source code:
C Call remote procedure CALCULATE_PAY to calculate the gross pay.
CALL CALCULATE_PAY (CARDS, PAY)
|
When you invoke procedure PAYROLL.COM (shown in Section 18.2.8), it displays a message about assuming [auto_handle].
For more information about client and server bindings, see the chapter
on basic DCE RPC runtime operations in the OSF DCE Application
Development Guide.
18.2.8 Building and Running the Example (PAYROLL.COM)
You can build, run, or both build and run the payroll example by using command file PAYROLL.COM. Its contents follow.
$!
$! This is file PAYROLL.COM to build, run, or both build and run
$! the distributed payroll application.
$!
$! COPYRIGHT (C) 1993 BY
$! DIGITAL EQUIPMENT CORPORATION, MAYNARD
$! MASSACHUSETTS. ALL RIGHTS RESERVED.
$!
$! THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
$! ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE INCLUSION
$! OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER COPIES
$! THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER
$! PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED.
$!
$! THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE AND
$! SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION.
$!
$! DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
$! SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL.
$!
$!
$! @PAYROLL is the default -- to build and run.
$! @PAYROLL BUILD does only the build.
$! @PAYROLL RUN does only a sample run.
$!
$ SAY := WRITE SYS$OUTPUT
$ IF P1 .eqs. "RUN" then goto DO_RUN
$!
$! Build the application.
$ SAY "Building..."
$
$! Enable the universal IDL command interface
$ idl := $sys$system:dce$idl.exe
$
$! Compile the interface definition
$! -keep all is used to keep the IDL output for training purposes
$ idl PAYROLL.IDL -keep all -trace all -trace log_manager -lang fortran -
-standard extended
$
$! Compile the client application files
$ FORTRAN PRINT_PAY
$
$! Link the client application
$ LINK PRINT_PAY,PAYROLL_CSTUB, DCE:DCE/OPT, DCE:DCE_VAXC/OPT
$
$! Compile the server application files
$ CC SERVER
$ FORTRAN MANAGER
$
$! Link the server application
$ LINK SERVER,MANAGER,PAYROLL_SSTUB,DCE:DCE/OPT,DCE:DCE_VAXC/OPT
$ IF P1 .eqs. "BUILD" then exit
$
$DO_RUN:
$! Run the application.
$ SAY "Activating server image..."
$ DEFINE/NOLOG RPC_DEFAULT_ENTRY ".:/FORTRAN_payroll_mynode"
$ SPAWN/NOWAIT/INPUT=NL:/OUTPUT=SERVER.LOG/PROCESS=FORTRAN_SERVER -
RUN SERVER
$ WAIT 00:00:10 ! Allow 10 seconds for the server to start.
$ DEFINE/NOLOG FOR004 PAYROLL.DAT
$ SAY "Activating client image..."
$ RUN PRINT_PAY
$ SAY "Deleting server process..."
$ STOP FORTRAN_SERVER
$ SAY "End of sample application"
|
If you prefer to use OpenVMS DCL syntax for the command to the IDL compiler, then one way to modify file PAYROLL.COM follows.
Consider these seven lines:
$! Enable the universal IDL command interface
$ idl := $sys$system:dce$idl.exe
$
$! Compile the interface definition
$! -keep all is used to keep the IDL output for training purposes
$ idl PAYROLL.IDL -keep all -trace all -trace log_manager -lang fortran -
-standard extended
|
Change the second, third, sixth, and seventh lines to comments by adding a "$!" at the beginning of each line (or delete all seven lines). Then, add the following three lines before the two lines:
$
$! Compile the client application files
$! Use OpenVMS DCL syntax for the command to the IDL compiler.
$ IDL/KEEP=ALL/TRACE=(EVENTS=ALL,LOG_MANAGER)/LANGUAGE=FORTRAN -
/STANDARD=EXTENDED PAYROLL.IDL
|
This modification works only if you do not otherwise have the symbol
IDL defined.
18.2.9 Example Output
The output from building and running the sample application looks like this:
Building... Operation calculate_pay has no binding handle parameter; [auto_handle] assumed Activating server image... %DCL-S-SPAWNED, process FORTRAN_SERVER spawned Activating client image... Jerry Harrison 372 Tony Hardiman 294 Mary Flynn 321 FORTRAN STOP Deleting server process... End of sample application |
The next time you need to run this application, enter this command:
$ @PAYROLL RUN |
The output from building this application includes files PRINT_PAY.EXE
(client) and SERVER.EXE (server). You can use these executable programs
in separate client and server processes.
18.3 Remote Procedure Calls Using FORTRAN --- Reference
Section 18.2 contains a comprehensive example that introduces creating
distributed applications with VAX FORTRAN program units. This section
goes beyond the example to provide reference information and explain
general concepts about creating these distributed applications.
18.3.1 The FORTRAN Compiler Option
If you are generating stubs and include files for application code written in VAX FORTRAN, you must specify it as the language of choice when you compile the application's IDL file. To specify the VAX FORTRAN language using the universal syntax, specify -lang fortran; the default value is -lang c. To specify the VAX FORTRAN language using DCL syntax, specify /LANGUAGE=FORTRAN; the default value is /LANGUAGE=CC.
In the remainder of this chapter, the phrase "FORTRAN option" refers to the IDL command that specifies VAX FORTRAN. Examples of the IDL command and specification are presented in Section 18.2.3.
Any client or server stub files that the FORTRAN option generates use the VAX FORTRAN linkage conventions. This means that all parameters are passed by reference (see Section 18.3.5.1 for more information). In addition, all identifiers are converted to uppercase.
The FORTRAN option generates the file filename.FOR, which includes VAX FORTRAN declarations of the constants and types declared in the IDL file. The .FOR file also includes, for each operation declared in the IDL file, a set of comments that describes the signature of the operation in VAX FORTRAN terms.
In addition, the FORTRAN option generates the file filename.FOR_H. This file is used for generating the client and server stubs. It is also needed for generating VAX FORTRAN stubs for any interface that imports this interface.
Consider the header option whose syntax is -header (universal) or /HEADER= (OpenVMS DCL). If you specify both the FORTRAN option and the header option to the IDL compiler, the following rules govern the compiler's placement of the files filename.FOR and filename.FOR_H.
This section discusses restrictions on distributed applications written in VAX FORTRAN that make remote procedure calls. These restrictions are on interfaces and stubs, and on runtime operations.
rpc_server_listen((int)1, &st); |
A constant declaration either gives a name to an integer or string constant or gives a second name to a constant that has already been given a name. Examples of these declarations follow:
const long array_size = 100; const char jsb = "Johann \\"Sebastian' Bach"; const long a_size = array_size; const boolean untruth = FALSE; |
For all IDL constant declarations, equivalent PARAMETER statements are generated in the corresponding file filename.FOR. For example:
INTEGER*4 ARRAY_SIZE PARAMETER (ARRAY_SIZE=100) CHARACTER*(*) JSB PARAMETER (JSB='Johann "Sebastian'' Bach') INTEGER*4 A_SIZE PARAMETER (A_SIZE=ARRAY_SIZE) LOGICAL*1 UNTRUTH PARAMETER (UNTRUTH=.FALSE.) |
All integer constants are declared as INTEGER*4.
All void * constants are ignored.
A nonprinting character that appears within a character or string
constant is replaced by a question mark (?).
18.3.4 Type Mapping
An IDL type that is a synonym for another type is presented to VAX FORTRAN as the type for which the synonym is defined. For example, suppose that the IDL file contains the following statement:
typedef foo bar; |
Then, all instances of IDL type \*Cbar) are presented to VAX FORTRAN as of type foo.
Table 18-3 describes the mappings from IDL types to VAX FORTRAN types:
| IDL Data Type | FORTRAN Data Type | Comments |
|---|---|---|
| arrays | See notes 8 and 9 | |
| boolean | LOGICAL*1 | |
| byte | BYTE | |
| char | CHARACTER | |
| context handle | INTEGER*4 | |
| double | REAL*8 | See note 3 |
| enum | INTEGER*4 | |
| error_status_t | INTEGER*4 | See note 4 |
| float | REAL*4 | |
| handle_t | HANDLE_T | See description of NBASE.FOR in this chapter |
| hyper | IDL_HYPER_INT | See description of NBASE.FOR |
| ISO_MULTI_LINGUAL | ISO_MULTI_LINGUAL | See description of NBASE.FOR |
| ISO_UCS | ISO_UCS | See description of NBASE.FOR |
| long | INTEGER*4 | |
| pipe | No mapping | |
| pointer | INTEGER*4 | See note 10 |
| short | INTEGER*2 | |
| small | INTEGER*2 | See note 1 |
| struct | STRUCTURE | See notes 5 and 6 |
| union | UNION | See note 7 |
| unsigned hyper | IDL_UHYPER_INT | See description of NBASE.FOR |
| unsigned long | INTEGER*4 | See note 2 |
| unsigned short | INTEGER*4 | See note 1 |
| unsigned small | INTEGER*2 | See note 1 |
| Previous | Next | Contents | Index |