Document revision date: 5 July 2000

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.

13.3 Remote Procedure Calls Using FORTRAN --- Reference

Section 13.2 contains a comprehensive example that introduces creating distributed applications with FORTRAN program units. This section goes beyond the example to provide reference information and explain general concepts about creating these distributed applications.

13.3.1 The FORTRAN Compiler Option

If you are generating stubs and include files for application code written in FORTRAN, you must specify it as the language of choice when you compile the application's IDL file. To specify the FORTRAN language using the universal syntax, specify -lang fortran ; the default value is -lang c . To specify the 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 FORTRAN. Examples of the IDL command and specification are presented in Section 13.2.3.

Any client or server stub files that the FORTRAN option generates use the FORTRAN linkage conventions. This means that all parameters are passed by reference (see Section 13.3.5.1 for more information). In addition, all identifiers are converted to uppercase.

The FORTRAN option generates the file filename.FOR, which includes 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 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 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.

• If you specify a directory name in the header option, the compiler places the files in that directory. Otherwise, it places the files in the current default directory.
• If you specify a filename without an extension in the header option, the compiler uses that filename with the extensions .FOR and .FOR_H.
• If you specify a filename with an extension in the header option, the compiler uses that file extension instead of .FOR_H; however, the compiler does not change the extension of the .FOR file.

This section discusses restrictions on distributed applications written in FORTRAN that make remote procedure calls. These restrictions are on interfaces and stubs, and on runtime operations.

• If an interface contains any arrays that have more than seven dimensions, the IDL compiler cannot produce output that is compatible with FORTRAN.
• If an interface contains two identifiers that differ only in the case of their characters, the IDL compiler may not be able to build stubs.
• The stubs generated for FORTRAN cannot call operations that use pipes.
• If the transmit_as or represent_as attributes have been applied to a character array type used to define the parameters of an operation, then FORTRAN cannot call that operation.
• If the transmit_as or represent_as attributes have been applied to an array type that, in turn, is the base type of an array type used to define the parameters of an operation, then FORTRAN cannot call that operation.
• If the v1_array attribute has been applied to any parameter of an operation, then FORTRAN cannot call that operation.
• FORTRAN does not allow the concurrent execution of two or more threads. In particular, if a server implements remote operations in FORTRAN, it must restrict the number of threads of server execution to 1. The following statement in file SERVER.C (shown in Section 13.2.5) specifies this restriction:

  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 (?).

13.3.4 Type Mapping

An IDL type that is a synonym for another type is presented to 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 FORTRAN as of type foo .

Table 13-3 describes the mappings from IDL types to FORTRAN types:

Table 13-3 Mappings for IDL 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

Notes

1. For these IDL data types, the FORTRAN data type is chosen because it can represent all possible values of the IDL type. Note that, in each case, there are values of the FORTRAN type which cannot be represented in the IDL type. You must not attempt to pass such values in parameters. The RPC runtime code does not perform range checking.
2. Because some values that can be represented in an IDL data type cannot be represented correctly in the FORTRAN data type, the IDL compiler issues a warning.
3. You must compile FORTRAN code that uses this data type and specify the /G_FLOAT compiler option.
4. Status code mapping will occur where necessary.
5. For any structure type in the IDL file that is not defined through a typedef statement, the IDL compiler generates the name of the FORTRAN structure. To determine what name was generated, look at filename .FOR.
6. The semantics of conformant structures cannot be represented in FORTRAN. In the definition of such a structure in filename.FOR, a placeholder for the conformant array field is specified as a one-dimensional array with one element. If the first lower bound of the conformant array is fixed, this value is used as the lower and upper bounds of the placeholder. If the first lower bound of the array is not fixed and if the first upper bound of the conformant array is fixed, the upper bound is used as the lower and upper bounds of the placeholder. Otherwise, the lower and upper bounds of the placeholder are zero.
7. Note that IDL encapsulated union types and nonencapsulated union types are represented as FORTRAN structures containing unions.
8. IDL array types are converted to arrays of a nonarray base type.
9. Arrays that do not have a specified lower bound have a lower bound of zero. Consider the following two statements in an IDL file:

   double d[10][20]; short e[2..4][3..6];

   
   The statements map into the following FORTRAN constructs:

   REAL*8 D(0:9,0:19) INTEGER*2 E(2:4,3:6)

10. The size of the pointer depends on the platform. It is INTEGER*4 for OpenVMS systems and INTEGER*8 for Compaq Tru64 UNIX Alpha systems.

Operations can pass parameters and return function results. This section explains these topics.

13.3.5.1 Parameter Passing by Reference

The following rules explain the mapping between IDL parameters and FORTRAN parameters:

• If the IDL parameter contains an asterisk (*) and does not have a [ptr] or [unique] attribute, this signifies a parameter of the indicated type passed by reference. The FORTRAN parameter is of the same type.
• If the IDL parameter contains an asterisk and does have a [ptr] or [unique] attribute, the FORTRAN parameter is a pointer.
• If the IDL parameter is an array and has the [ptr] or [unique] attribute, the FORTRAN parameter is a pointer.
• If none of the preceding cases is true, then the FORTRAN parameter is of the same type as the IDL parameter.

The only possible function result types in FORTRAN are scalars and CHARACTER*n. The mappings from IDL to FORTRAN never produce CHARACTER*n, where n is greater than 1.

IDL hyper integers are not scalars in terms of function results, but IDL pointers are treated as scalars because they are mapped to INTEGER*4.

For an operation that has a result type that is not allowed by FORTRAN, the stubs treat the operation result as an extra [out] parameter added to the end of the parameter list.

If the type of an operation is not void , you must state the type of the function result in FORTRAN.

13.3.6 Include Files

Usually, a FORTRAN routine that is part of an RPC client or manager for the interface defined in filename.IDL must include the following files:

• filename.FOR
• NBASE.FOR
• The .FOR files for any imported interfaces

Program units PRINT_PAY.FOR and MANAGER.FOR (containing subroutine subprogram CALCULATE_PAY) in the example of a distributed payroll application do not include NBASE.FOR because the units contain none of the IDL data types in Table 13-2. Otherwise, the program units would include NBASE.FOR. Furthermore, these units could safely include NBASE.FOR even though it is unnecessary in the example.

13.3.7 The NBASE.FOR File

DCE:NBASE.FOR declares standard data types used in mapping IDL to FORTRAN. The declarations include those listed in Table 13-4.

Table 13-4 Standard Declarations

IDL Data Type	FORTRAN Declaration	Comments
hyper	STRUCTURE /IDL_HYPER_INT/
	INTEGER*4 LOW
	INTEGER*4 HIGH
	END STRUCTURE
unsigned hyper	STRUCTURE /IDL_UHYPER_INT/
	INTEGER*4 LOW
	INTEGER*4 HIGH
	END STRUCTURE
handle_t	STRUCTURE /HANDLE_T/ INTEGER*4 OPAQUE_HANDLE END STRUCTURE	Size of pointer is platform specific: INTEGER*4 on OpenVMS systems INTEGER*8 on Compaq Tru64 UNIX Alpha systems
ISO_MULTI_LINGUAL	STRUCTURE /ISO_MULTI_LINGUAL/
	BYTE ROW
	BYTE COLUMN
	END STRUCTURE
ISO_UCS	STRUCTURE /ISO_UCS/
	BYTE GROUP
	BYTE PLANE
	BYTE ROW
	BYTE_COLUMN
	END STRUCTURE

13.3.8 IDL Attributes

This section describes IDL attributes that apply to RPC applications containing FORTRAN modules.

13.3.8.1 The transmit_as Attribute

The presented type must be expressible in FORTRAN. Because addresses are involved, the routines used for data conversion cannot be written in VAX FORTRAN.

13.3.8.2 The string Attribute

A FORTRAN data item corresponding to an IDL string contains the number of characters specified for the IDL string. Because IDL strings are usually terminated with a null byte, the following transmission rules apply:

• If a FORTRAN routine contains data for transmission, and a null byte appears before the last character of the FORTRAN data item, then the characters up to and including the null byte are transmitted.
• If a FORTRAN routine contains data for transmission, and a null byte does not appear before the last character of the FORTRAN data item, then all the characters of the data item except the last are transmitted, followed by a null character.
• If data is transmitted to a FORTRAN routine, then the FORTRAN data item receives a null terminated string. If the FORTRAN data item contains more characters than the string, then the additional characters are not affected.

An IDL operation can have a conformant string parameter. Such a parameter is presented to FORTRAN as type CHARACTER*(*). If the base type of the string consists of w bytes and the string consists of n characters, then the parameter size is n*w. The maximum parameter size supported is 65535.

A conformant string field of a structure will have type CHARACTER*w, where w is the number of bytes in the base type of the string.

In all other cases where a string is not the target of a pointer, the IDL file specifies the string. Such a string is presented to FORTRAN as CHARACTER*s, where s is the product of the string length and the number of bytes in the base type of the string. Furthermore, s must be between 1 and 65535 inclusive.

13.3.8.3 The context_handle Attribute

A context handle rundown routine cannot be written in FORTRAN because the routine must handle address information.

13.3.8.4 The Array Attributes on [ref] Pointer Parameters

A [ref] pointer parameter that has array attributes attached to it is presented to FORTRAN as the equivalent array.

13.3.9 ACF Attributes

The following items can occur in an Attribute Configuration File (ACF). They require special consideration when you are using FORTRAN.

13.3.9.1 The implicit_handle ACF Attribute

You must supply a COMMON block whose name is the name given in the implicit handle clause. This COMMON block must contain the binding handle as its only data item.

For example, suppose an ACF contains the following interface attribute:

[implicit_handle(handle_t i_h)]

Then, any FORTRAN routine that calls an operation which uses the implicit binding must include statements with the following form:

RECORD /HANDLE_T/ BINDING_HANDLE COMMON /I_H/ BINDING_HANDLE

13.3.9.2 The represent_as ACF Attribute

The local type must be expressible in FORTRAN. Because addresses are involved, you cannot write the data conversion routines in FORTRAN.

A type name in a represent_as attribute that does not occur in the interface definition and is not an IDL base type is assumed to be a STRUCTURE type.

Suppose that the represent_as type is not an IDL base type or a type defined in your IDL source. Then, you must supply a .h file whose unextended name is given in an include statement in the ACF. (An unextended name is a filename without the file extension that follows the dot (.) in the name. For example, the unextended filename for file EXAMPLE.H is EXAMPLE.) This file must include a definition of the local type in C syntax. You will need a filename.FOR file containing a FORTRAN definition of the local type. Compaq recommends that you assign this file the same unextended name.

	privacy and legal statement
6532_DCE_PG_PRO_010.HTML