courier.tbl.me

早期freebsd实现

\" $Header: courier.tbl.me,v 1.8 87/03/17 09:32:52 ed Exp $
\" $Header: courier.tbl.me,v 1.8 87/03/17 09:32:52 ed Exp $
\" $Log:	courier.tbl.me,v $
\" Revision 1.8  87/03/17  09:32:52  ed
\" Added -I switch to establish search path for DEPENDS UPON files.
\" 
\" Revision 1.7  86/11/22  07:12:05  jqj
\" small changes reflecting differences between 4.3bsd and 4.2 Maryland XNS.
\" 
\" Revision 1.6  86/05/12  09:02:43  jqj
\" minor revisions
\" 
\" Revision 1.5  85/03/26  06:30:58  jqj
\" Revised public alpha-test version, released 26 March 1985
\" 
\" Revision 1.4  85/03/11  16:46:01  jqj
\" Public alpha-test version, released 11 March 1985
\" 
.lg 0
.fo ''%''
.(l C
.ps +4
.b
XNS Courier under UNIX (4.3BSD)
.ps -4
.sp 2
.r
.he $ XNS Courier $ $Date: 87/03/17 09:32:52 $
J.Q. Johnson
Computer Science Department
Cornell University
405 Upson Hall
Ithaca, NY  14853
.)l
.sh 1 "Introduction"
.pp
This document describes the implementation and use
of the Courier remote procedure call protocol for Berkeley UNIX
(version 4.3), with XNS.
.sp 1
.nf
.b
.(c
********************************************************
Warning:  this document is a DRAFT design specification.
It has not yet been fully implemented, and the details of
the interface it specifies (particularly with respect to 
Courier servers) are subject to change.  Send design
comments to [e-mail] or [e-mail].
********************************************************
.)c
.r
.fi
.sp 1
.uh "Changes since previous revision:"
.np
Added discussion of encapsulated protocols.
.np
Added discussion of Clearinghouse library calls for finding a connection,
and relationship of connections to outstanding RPCs.
.uh "Earlier changes:"
.np
Changed names of generated file names to include version number.
Added discussion on scope of names vs. DEPENDS UPON modules.
.np
Users must now link Courier program ``Foo'' with Foo1_support.o.
.np
Added some discussion of freeing dynamic storage via clear_Foo.
.np
Changed
.i CourierOpen()
to take ns_addr structure rather than a string host name.  Routines for
converting from name to address (using Clearinghouse) have not yet been
designed. 
.np
Changed ERROR discussion to indicate that an ERROR is mapped to a long
with value > 65535.
.np
Changed description of BDT to reflect use of 
.i BDTread()
and
.i BDTwrite() .
.np
Added SPPMAXDATA.
.np
Changed discussion of BulkData constants to indicate that things now
work correctly.
.sh 2 "General Description"
.pp
Courier is both a protocol and a specification language.
The protocol describes how remote procedures are invoked and
how parameters and results of various data types are transmitted.
The specification language, somewhat reminiscent of Mesa,
provides a simple way of defining the remote interfaces of distributed
programs.
.pp
This implementation is an attempt to allow UNIX C programmers to
construct distributed Courier programs to communicate with other
Courier implementations layered on XNS.  It thus requires kernel
support for XNS Sequenced Packet Protocol sockets.
.pp
The simplest form of distributed program using Courier
consists of three parts.
The first is the specification,
written in the Courier language.
The specification must declare all procedures of
the program that will be called remotely (the
.i "server procedures" ).
The next part is the implementation, in C, of the server procedures.
Finally, there is the client portion of the program, also in C, which calls
the server procedures.
Note that either the client or server portion of the program may be
omitted if the UNIX program is designed to act with a non-UNIX
partner; for example, a simple printing client under UNIX might send
files to a Xerox laser printer using the Printing protocol published
and supported by Xerox.
.sh 2 "Acknowledgements"
.pp
Contributors to the current implementation have included
JQ Johnson, the primary implementor of the current version of the
Courier compiler under UNIX,
Eric Cooper, the author of the original UNIX Courier/TCP compiler,
Jeff Mogul, the author of the exception signalling mechanism used
here to handle abort and reject messages,
James O'Toole, Chris Torek, and Mark Weiser,
the authors of the 4.2BSD version of UNIX kernel support for XNS,
Keith Sklower, the author of the present (4.3BSD) version of UNIX kernel support,
Lee Moore, and Bill Nesheim.
.pp
Some of the software is copyright 1984 by Eric Cooper, and is for
research use only; it may be freely distributed but may not be
sold as a commercial product.
.sh 2 "References"
.pp
This document assumes familiarity with the Courier language,
details of which may be found in
the Courier protocol definition,
.i "Courier: The Remote Procedure Call Protocol" ,
Xerox System Integration Standard 038112,
December 1981, and ``Appendix F, Bulk Data Transfer,'' Xerox System
Integration Standard 038112 Add. 1, October 1982.
However, for reference purposes, a grammar for the Courier language
may be found in the appendix to this document.
.pp
Users of Bulk Data Transfer will need to interact with SPP 
(Sequenced Packet Protocol)
streams, and may wish to see
.i "Internet Transport Protocols" ,
Xerox System Integration Standard 028112, December 1981.
.pp
Those interested in the workings of UNIX networking might consult
``A 4.2bsd Interprocess Communications Primer,''
(DRAFT of March 11, 1983), by Samuel J. Leffler, Robert S. Fabry, and
William N. Joy, and the 
``4.2BSD System Manual,''
(Revised July, 1983), by William Joy 
.i "et al" .
.pp
This document is also supplemented by various UNIX manual pages, notably
.i "xnscourier(3) " ,
and
.i "except(3)" .
.sh 2 "Software and Hardware Dependencies"
.pp
This package requires the following software to operate:
.(l
4.3BSD (currently tested only for VAX and Gould versions)
PCC, 4.3BSD version (probably\-limited testing has been done with Tartan C)
.)l
.pp
To communicate with Xerox products you will need an Ethernet
interface.  Most of the existing example applications depend heavily on
the existence of a Xerox Clearinghouse somewhere on the local network.
.sh 1 "The Courier Specification Language"
.pp
The Courier specification language is documented (loosely) in the Xerox
``Courier: The Remote Procedure Call Protocol.''  Our compiler
implements a large subset of the specification.  Note that the embedding
of Courier constructs in a message or bit stream is usually irrelevant to the
applications programmer, who need only be concerned with the semantics
of the Courier datatypes.  The courier compiler and runtimes translate
Courier datatypes into more easily managed C constructs and handle the
protocol of communication with the remote system.
.pp
This implementation places several restrictions on the specifications
it will accept:
.np
No forward references are permitted in the courier
specification.  The user must reorder type specifications so that all
types and constants are defined before they are used.
Special provisions are made for recursive type declarations of the form
typically found in Bulk Data ``StreamOf'' declarations; see the
discussion of BDT below for details.  General recursive declarations,
e.g. that of the Filing ``Filter,'' are not supported.
.np
The Courier specification is unclear as to lexical issues, 
name scope, and name overloading.
In the current compiler, names should contain only upper and lower case
letters or digits.  Also, all constants, types, and
enumeration tags within a module should have distinct names.  Enumeration
tag names are currently global; thus, different enumeration types, even
in different modules, may not have the same tags.
.np
Constants of type CHOICE are not fully supported.  In particular, they
are allowed only if the active arm of the choice is a nill record.
.np
Constants of type SEQUENCE are not supported.  Constants of type ARRAY
(which have the same syntax as SEQUENCE constants) are supported, but are
not rangechecked; ``Vect: ARRAY 10 OF INTEGER = {1,2,3}'' is accepted,
though illegal.
.np
This implementation supports DEPENDS UPON and
referenced types and constants.  However, the semantics of referenced
enumeration constants is unclear.  Also, this implementation
does not support recursive dependencies.
.lp
We think we've eliminated all other restrictions, but we're probably wrong.
.sh 2 "Predefined types"
.pp
The following typedefs correspond to predefined Courier types:
.(b
.TS
c c c
l l l.
Courier type	C typedef	Implemented (on VAX) as

BOOLEAN	Boolean	char (0==TRUE, 1==FALSE)
CARDINAL	Cardinal	unsigned short
LONG CARDINAL	LongCardinal	unsigned long
INTEGER	Integer	short
LONG INTEGER	LongInteger	long
STRING	String	char*
UNSPECIFIED	Unspecified	unsigned short
LONG UNSPECIFIED	LongUnspecified	unsigned long
.TE
.)b
Note that the representations of these types as seen by the applications
programmer are quite different from those sent over a Courier SPP connection.
For example, on the VAX a Cardinal's bytes are swapped before being
sent out in network byte order.  A UNIX String corresponds to a pointer to
a null-terminated array of characters while a Courier serialized STRING
contains a count directly followed by an array of characters.  Note
in particular that this implementation does
not support Courier STRINGs containing the ascii character NUL.
.sh 2 "Constructed types"
.pp
The Courier enumeration, array, and (non-null) record types
correspond to C enumerations, arrays, and structures respectively.
The Courier null record corresponds to an int.
.pp
The Courier sequence and choice types
pose some problems when they are mapped into C.
This is because an object of one of these types
must contain run-time information (the length of the sequence
or which choice is present)
that is implicit in Courier, but must be made explicit
in C.
Furthermore, the C programmer must bear the responsibility of keeping
this information consistent.
.pp
A sequence type is mapped into a structure consisting
of a Cardinal called
.i "length" ,
and a pointer to the sequence elements called
.i "sequence" .
The consistency requirement is that
.i "length"
indicate the number of elements in the array pointed to
by
.i "sequence" .
.pp
A choice type is mapped into a structure consisting
of an enumeration element called
.i "designator" ,
and a union of all the possible choices.
The designator is of the enumeration type defined
(implicitly or explicitly)
in the declaration of the choice type.
If this enumeration consists of elements
.i A ,
.i B ,
and
.i C ,
then the choices are accessible as
.i A_case ,
.i B_case ,
and
.i C_case .
The consistency requirement is that
.i "designator"
contain the enumeration value corresponding to
which choice currently occupies the union.
.sh 2 "Constants"
.pp
The Courier specification is silent on the precise representations of
numbers and strings.  In this implementation, numbers may be represented
as an optional minus sign followed by a
sequence of decimal digits or a sequence of octal digits followed
by ``B''.  A constant of type STRING 
is represented by a sequence of characters enclosed in
double quotation marks; it has the same restrictions as a C literal string (no
embedded newlines, use ``\e'' as a prefix character, etc.) except that double
double quotes are permitted to indicate quotations inside the string.
.sp 1
.nf
minInt: INTEGER = -2147483648;		-- or 20000000000B --
lastCard: CARDINAL = 177777B;		-- or 65535 --
quotedName: STRING = "my name is \"jqj""\en";
.fi
.sp 1
.pp
Although the Courier language allows constants of
any type to be declared,
it is difficult to define constants of constructed types
in C programs.
This implementation normally handles constants by creating
static variables initialized to the values of the (possibly structured)
constants.  The technique is not in general possible for structured 
constants of type CHOICE
since they are implemented as C ``unions'', so this implementation does not
support constants which contain a non-null CHOICE.  As a special case,
constants whose selected variant is a null record are allowed, e.g.
.sp 1
	myImmediate: BulkData.Immediate = immediate [];
.sp 1
.sh 2 "Procedures"
.pp
PROCEDURE constants correspond to C functions plus a numeric jump table
index used in serialization of procedure calls on the network.
Procedure declarations may include argument lists, result lists, and
error lists.  The argument list of the corresponding C function 
contains one parameter for each parameter specified in the declaration,
but is
expanded by the addition of 2 parameters (see below).  The result list
specifies a C structure to be returned by the C function containing the
results; for a procedure, Foo, this result list is of type FooResults.
Thus, a procedure declared
.sp 1
	Example: PROCEDURE [ ] RETURNS [ a: Foo, b: Baz ] = 0;
.sp 1
would be implemented by a C function with no arguments
returning a structure of type ExampleResults with definition
something like
.sp 1
.nf
	typedef struct {
		Foo a;
		Baz b;
	} ExampleResults
.fi
.sp 1
Note that Foo and Baz might be arbitrarily complex structures;
see ``Constructed Types'' above.
.pp
Importing a PROCEDURE from a DEPENDS UPON module imports only its jump
table index.
.sh 2 "ERROR constants"
.pp
An ERROR constant corresponds to a defined numeric value, and possibly
to a C structure describing its argument list.  For example,
.sp 1
	OtherError: ERROR [ errorstring: STRING ] = 1;
.sp 1
corresponds approximately to the C declarations:
.sp 1
.nf
	#define OtherError (1+ERROR_OFFSET)
	typedef struct {
		String errorstring;
	} OtherErrorArgs;
.fi
.sp 1
Note that ERROR values must be specified in the range 0 to 65535, but
that they produce a symbol which appears to the C programmer
with values of type int
in the range 65536 to 131171 (in some contexts, the user may wish to
treat C error values in the range 0 to 65535 as Unix error numbers).
The structure corresponding to the error
may be useful in creating and referencing error arguments
in C functions.
.sh 2 "Scope of Names"
.pp
Given a courier program beginning
.sp
	Example : PROGRAM 537 VERSION 1 =
.sp
types and constants declared in this program belong to the module ``Example1'';
Their full names have prefixed to them the program name and version number.
Given the declaration of ``minInt'' above, the XNS Courier compiler actually
produces a header file (here
.i Example1.h )
containing the C declaration:
.sp 1
.nf
static Integer Example1_minInt = {-2147483648};
.fi
.sp 1
.pp
This prefixing implies that a C programmer may refer to several different
remote Courier programs without risk of name collision.
For programmer convenience a second header file (here
.i Example1_defs.h )
is also created by the compiler containing macro definitions which widen
the scope to ``Example1'' and allow the programmer to refer to types and
constants without explicit qualification.  The programmer may include
whichever header file he prefers.
.pp
Note that types and constants obtained from a DEPENDS UPON inclusion must
be referenced using fully qualified form.  Note also that structure members,
procedure arguments, and enum tags are not currently qualified; beware
potential name conflicts!
.sh 1 "Running the Courier Compiler"
.pp
The specification file is expected to have the extension
.i ".cr" .
Consider the following skeletal Courier program definition:
.sp
	Example : PROGRAM 537 VERSION 1 = BEGIN ... END.
.sp
The name of this Courier program is ``Example''; it is version 1.
By convention, this specification would stored in the file
.i "Example1.cr" .
The ``537'' in this example is illustrative only;
the program number is uniquely allocated from the range of LongCardinals
by Xerox.  See Appendix B of the Courier standard for program number
assignment procedures.
.pp
The first step is to use the Courier compiler on the specification.
Assuming
.i "xnscourier"
is in your path (it is 
.i "/usr/new/xnscourier"
on the Berkeley distribution), type
.sp 1
	xnscourier Example1.cr
.sp 1
If there are no errors in compilation,
the following files will be produced:
.(b
.TS