4.4BSD/usr/src/contrib/xns/doc/courier.tbl.me
\" $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 jqj@cornell.ARPA or jqj@cornell.UUCP.
********************************************************
.)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
c c
l l.
File Contents
Example1_defs.h scope widening macros (includes Example1.h)
Example1.h definitions, typedefs, and constant declarations
Example1_support.c routines to map between C and Courier
Example1_server.c server main program and support routines
Example1_client.c client routines to support applications calling Example
.TE
.)b
.pp
The header file
.i "Example1_defs.h"
should be included via
.sp
#include ``Example1_defs.h''
.sp
in all user-written parts of the Courier program
(i.e., the implementations of the client program and server procedures.)
.pp
The
.i "\fB-I\fIinclude-directory"
switch may be used on the command line of
.i xnscourier
to establish a search path for Courier specification files named in a
DEPENDS UPON clause. By default, the compiler looks first in the current
directory followed by the courier-description-file named in the
.i /etc/Courierservices
file.
.sh 2 "Calling Remote Procedures \- Client Implementation"
.pp
A remote procedure appears to the C programmer to look almost like
a local procedure (although it typically makes use of resources not
available on the local machine or else runs many times slower
than would a local procedure). A C client program (i.e. the caller
of a remote procedure) actually calls a stub function generated by
the courier compiler, which in turn executes the code necessary to
invoke the corresponding procedure on the remote machine.
.pp
Before calling the remote procedure it is necessary to establish a
Courier SPP connection (in the process binding a local socket to
a remote machine). This may be done by the calling the function
CourierOpen(), passing it as argument a structure identifying the remote
host. This structure
is of type ``ns_addr''
as defined in the include file
.i "#include <netns/ns.h>" .
CourierOpen() returns an anonymous pointer
(of type CourierConnection*) to a structure containing
the socket to be used for this courier call, which should be passed
to each remote procedure to be executed on the particular remote host.
CourierOpen() returns NULL if there is a problem opening an SPP connection
to the host specified.
.pp
For low-level access to ns_addr structures,
the procedure getXNSaddr() is available, taking a string in the form
``network#a1.a2.a3.a4.a5.a6#socket'' (where all numbers are hex) or
``networkhigh-networklow#d1-d2-d3-d4#socket'' (where all numbers are
3-digit decimal numbers)
and returning a pointer to the
corresponding ns_addr structure. This result may then be passed as the
argument to CourierOpen().
More normally, the user will have a string in the form of an NS address,
e.g. ``jqj:computer\ science:cornell-univ''. This string can be
coerced into a Clearinghouse ObjectName, then used in a Clearinghouse-based
lookup to find the corresponding address:
.sp 1
.nf
Clearinghouse2_ObjectName hobj, hdefault;
struct ns_addr * host;
char * string;
CH_NameDefault(&hdefault); /* get defaults */
hobj = CH_StringToName(string, &hdefault);
host = CH_LookupAddr(hobj, 0);
.fi
.sp 1
.pp
The SPP connection may be reused by multiple RPCs destined for the same
host, even if the procedures are part of different remote programs. However,
the SPP connection may not be reused while an RPC is outstanding; thus,
if you need to issue a Courier call during a BDT transfer, you will need
to obtain a second CourierConnection.
.pp
The client then calls the compiler-generated stub function to invoke
the remote procedure. This stub
function takes at least 2 arguments:
.ip (1)
The pointer returned from CourierOpen().
If the SPP connection does not
currently exist (i.e. has been closed by the server)
it is reopened for this call.
.ip (2)
A pointer to a user-supplied function which will be used if a Bulk Data
Transfer is required (see the section on BDT below); if this remote
procedure does not involve Bulk Data Transfer, then the function pointer
should be 0 or NULL.
.ip (3...)
One additional argument corresponding to each parameter in the Courier
language description of this procedure.
.pp
The remote procedure returns in one of 2 ways: either it returns
normally, passing back a structure corresponding to the RETURNS parameters
specified in the procedure description, or it signals an error which
may be caught using the DURING ... HANDLER mechanism described in
.i except(1) .
.pp
A Courier procedure is allowed to return multiple results, a language feature
not easily mapped into C. To provide this functionality, all UNIX
courier remote procedures actually return a structure
containing the procedure results. Thus, for a procedure named
Foo, declared
.sp 1
Foo: PROCEDURE [ ] RETURNS [str: STRING];
.sp 1
the C function Foo would return a structure of type FooResults, declared
.sp 1
.nf
typedef struct {
String str;
} FooResults;
.fi
.fi
.pp
Instead of returning a value of type determined by the RESULTS clause
of a PROCEDURE declaration, a Courier remote procedure call may return
a reject message indicating the remote system's inability to even
attempt a remote operation, or an abort message raising a remote error,
i.e. reporting the operation's failure. Reject and abort messages are
handled by a signalling mechanism or if uncaught cause termination of
the client program. For example, a client calling the remote procedure
defined by
.sp 1
.nf
NoSuchFile: ERROR = 0;
OtherError: ERROR [ errorstring: STRING ] = 1;
Example: PROCEDURE [ ] REPORTS [ NoSuchFile, OtherError ];
.fi
.sp 1
might be coded as
.sp 1
.nf
conn = CourierOpen(destaddr);
DURING Example(conn,NULL)
HANDLER switch(Exception.Code) {
case REJECT_ERROR:
fprintf(stderr,"Remote reject.\en");
exit(1);
case NoSuchFile:
fprintf(stderr,"No such file\en");
break;
case OtherError:
fprintf(stderr,"Remote error %s\en",
CourierErrArgs(OtherErrorArgs,errorstring) );
break;
case PROTOCOL_VIOLATION:
case INTERNAL_ERROR:
fprintf(stderr,"Local internal error %s\en",
Exception.Message);
break;
default:
fprintf(stderr,"Unknown error, type %d\en",
Exception.Code);
}
END_HANDLER
.fi
.sp 1
The error value, Exception.code, will be one of (1) ``REJECT_ERROR'',
which indicates a REJECT message from the remote server, (2) a program-defined
ERROR value (offset by ERROR_OFFSET), (3) or ``INTERNAL_ERROR''
or ``PROTOCOL_VIOLATION''
indicating
a serious internal error in the Unix courier implementation; in the third
case, a string is available as Exception.Message.
Both errors and rejections may have arguments, which can be accessed
within a handler as a struct pointed to by Exception.Message. For
programmer convenience a macro, CourierErrArgs, is defined, taking
as arguments the typedef defining the current error's arguments
and the name of the argument to be accessed; this macro may be used
only within an error handler.
For rejection messages, the type should be ``rejectionDetails,''
as defined on page 25 of the Courier spec.
.pp
When done with a particular remote connection, the client should call
CourierClose() with argument the pointer returned from CourierOpen()
to free the socket and cleanly close the connection.
.pp
The client program should be loaded with
.i "Example1_client.o" ,
.i "Example1_support.o" ,
and -lcourier (the XNS Courier library)
to produce an executable program.
.sh 2 "Writing a Courier Server"
.pp
The Courier protocol specifies a standard for communicating
parameters and results which has been adhered to in this
implementation.
It also specifies an initial connection protocol
and a format for messages.
.pp
There is a single Courier Daemon per UNIX machine whose function
is to listen on a well-known XNS port for Courier interface activation
requests.
A request contains the number of the Courier program
whose server is to be activated, and its version number. These two
numbers are used as a key in the file
.i /etc/Courierservices
to identify
the executable file associated with the particular courier program.
.i /etc/Courierservices
consists of a sequence of lines of the form
.sp 1
program-name program-number version courier-description-file server-binary-file
.sp 1
The daemon
either spawns the executable file
or replies with a reject message. Note that each incoming remote procedure
call may be serviced by a separate UNIX process.
This implies that connection-oriented services (services which consist of a
sequence of related procedure calls) must be implemented by maintaining
the state of connections in a file.
.pp
The executable file containing the server for a particular remote
program consists of a main program generated by the courier compiler
which interprets CALL messages from the remote client and calls
one or more user-written functions to implement the
courier procedures.
.pp
Given a courier specification for the remote program Example containing
remote procedure Example,
the server functions (including the C function Example and any support
routines needed)
should be loaded with
.i "Example1_server.o" ,
.i "Example1_support.o" ,
and -lcourier
to produce the server process that will be invoked whenever
an activation request arrives.
.pp
A server function receives an argument list similar to that passed by
a client to a remote procedure. The first two arguments in the
parameter list should be ignored; each succeeding argument corresponds
to one parameter in the courier declaration.
.pp
To return from a server function you must return a structure containing
the results of the procedure. If this structure contains pointers (e.g.
Strings) you should insure that the data pointed to is allocated
staticly or on the heap rather than on the stack.
You must not call exit(3) from within the server function; doing so will
cause the client (remote caller) to hang indefinitely waiting for a
reply.
.pp
To abort a server function, returning an error code, use the
``raise(code, msg)''
library function, with arguments the error code and either NULL (if the
error takes no arguments) or a pointer to a structure containing the
arguments to the error. Raise causes a longjump out of the function
directly to the handler, and thence to the remote procedure caller.
For example, to return the OtherError message defined above one might code
.sp 1
.nf
OtherErrorArg randomerr;
. . .
randomerr.errorstring = sys_errlist[errno]);
raise(OtherError,(char*) &randomerr);
.fi
.sp 1
.pp
When a server function returns to its main program caller the main()
sends the appropriate RETURN or ABORT message to the remote client,
and does an exit(0). The server then holds the connection for up to 90
seconds waiting for another Courier call to arrive on the same SPP
stream.
.sh 2 "Dynamic Allocation"
.pp
One additional
.i caveat
is necessary when using Courier remote procedure calls from C: C does not
have garbage collection, so you should free any dynamically allocated storage
when you are done with it. In general, top level Courier objects are
always allocated from the stack or statically; however, strings and sequences
within an object are generally allocated from the heap using malloc().
.pp
A client program which calls the remote procedure Foo defined above,
returning a STRING,
actually has returned to it a C struct containing a pointer to an array
of malloced characters. When done with this string, the program may free
it by calling clear_FooResults() with argument the address of the
result returned by the call to Foo. Thus:
.sp 1
.nf
FooResults result;
. . .
result = Foo(conn,NULL);
. . .
printf("result was %s\n",result.str);
clear_FooResults(&result);
.fi
.sp 1
.sh 1 "Using Bulk Data Transfer"
.pp
.sh 2 "Overview"
.pp
When a Courier program needs to transfer an arbitrary amount of
information as an argument or result of a Courier procedure, the
procedure is usually defined to have an argument of type ``BulkData.Sink''
or ``BulkData.Source'' (and a ``DEPENDS UPON BulkData''
is included in the program).
The argument is a ``source'' if it is information transferred from caller
to server (as though a procedure argument), a ``sink'' if it is
information transferred from server to caller (as though a procedure
result). In this
implementation, a Courier procedure may have at most one such argument,
which must have the value null or immediate.
In a Courier call, the bulk data is transmitted in a special way,
multiplexed into the same data path as control messages
between the arguments and the results.
.pp
The BDT user should include in the
.i ".cr"
file a ``DEPENDS UPON BulkData (0) VERSION 1'', then reference these
arguments as BulkData.Source and BulkData.Sink in PROCEDURE
declarations.
The declaration of a Courier PROCEDURE can then indicate a bulk
data transfer by including in its formal argument list a variable
of type BulkData.Source or BulkData.Sink
as appropriate.
The corresponding parameter to the C procedure will be of type
BulkData1_Descriptor.
.sh 2 "Coding a Client"
.pp
To use Bulk Data in a client program, the Courier definition of the
procedure must include one BulkData.Source or BulkData.Sink parameter.
As the actual argument to the call, the C client passes a constant,
either BulkData1_immediateSource, BulkData1_immediateSink, BulkData1_nullSource,
or BulkData1_nullSink as appropriate. The client
also specifies a pointer to a user-supplied function as the second
argument to the remote procedure.
Courier sets up the transaction, then calls the supplied function with
one argument, the pointer returned by CourierOpen() describing the
SPP socket on which to write (if a source argument) or read
(if a sink) the bulk data.
.pp
To complete the transaction normally, the
function should send packets of SPP data terminated by
an end-of-message (if writing) or read up to but not beyond an
end-of-message (if reading), and should return normally to its caller.
To do so, it should call the procedures BDTread(), BDTwrite(), or
BDTclosewrite()
as appropriate. BDTread() and BDTwrite() take arguments analogous to read()
and write() except that instead of a file descriptor they accept the SPP
descriptor returned by CourierOpen(); their arguments are thus
(1) the pointer to the SPP data structure,
(2) a pointer to an array of characters (the IO buffer),
and (3) a count;
they return the number of characters actually read or written.
.pp
The UNIX program can finish a write transfer by calling BDTclosewrite() or
BDTabort(), each with the SPP descriptor as argument.
BDTclosewrite() produces an SPP end-of-message, while BDTabort() instructs
Courier to discard any buffered data and
send a Bulk Data Abort to abort the transaction. A read transfer may also be
prematurely ended by calling BDTabort().
.sh 2 "Coding a Server"
.pp
Writing a server that uses BDT
is similar to writing the BDT function in a caller.
The server is passed a BulkData.Source or BulkData.Sink (the two are
indistinguishable at run time).
The server routine should check to make sure that the source or sink
is of type null or immediate (active and passive descriptors are not
supported in this implementation) by means of code such as:
.sp 1
.nf
Foo(bdtconnection,ignoredarg,..., s, ...)
CourierConnection *bdtconnection;
BulkData1_Sink s;
. . .
switch (s.designator) {
case active:
case passive:
/* can't raise BulkData1_InvalidDescriptor, so */
raise(someerror);
case null:
/* handle null transfer */
break;
case immediate:
/* handle normal, i.e. immediate, transfer */
break;
}
.fi
.sp 1
Note that the BDT error InvalidDescriptor cannot be used unless the
procedure declaration explicitly notes that this is a valid REPORTS error
type. Normally, each courier program defines its own error to be reported
on BDT problems.
.pp
Use the first argument to the server procedure as the handle on the
BDT connection.
As with a client BDTabort() may
be used to send abort messages.
.sh 2 "Sending Bulk Data"
.pp
Sending bulk data, either as client or server, is quite
straightforward. Use the supplied procedure BDTwrite(), whose
semantics are similar to write(). BDTwrite() will return -1
if an error occurs or an abort from the listener is received; in this
case, the sender should immediately cease transmitting BDT data, and
should instead call BDTabort().
Typical code to send data on ``bdtconnection'',
in this case read from a buffered file open
as ``source,'' might appear as:
.sp 1
.nf
CourierConnection *bdtconnection;
FILE *source;
int count;
char buffer[SPPMAXDATA];
...
while ( (count = fread(buffer,1,SPPMAXDATA,source)) > 0 &&
BDTwrite(bdtconnection,buffer,count) >= 0 )
;
if (count <= 0) /* succsfull transfer */
BDTclosewrite(bdtconnection);
else
BDTabort(bdtconnection);
.fi
.sp 1
.pp
Each BDTwrite() transmits one packet after checking for an abort message
from the receiver.
A sender which gets an abort from a remote receiver must immediately
stop transferring data and instead must echo an abort via BDTabort()
to acknowledge the end of the transfer.
.pp
Also, for efficiency's
sake it is desirable to write packets as near as possible to the
nominal maximum length of an SPP packet; this suggests a buffer length of
534 bytes. For programmer convenience, the file
.i courier.h
defines the symbol SPPMAXDATA as 534.
.sh 2 "Receiving Bulk Data"
.pp
To make receiving bulk data simple, the routine BDTread() performs checks for
various conditions on receipt of each packet. BDTread() will return the
count of the number of bytes actually read in each packet (skipping empty
packets), or 0 to indicate end of data. If an error or BDT abort message
occurs, BDTread() will return -1; if this occurs, the receiver should
immediately stop reading BDT data.
.pp
Typical code for receiving bulk data on the socket described by
``bdtconnection'' and
depositing it in the file opened for buffered ouput as ``destfile''
might be:
.sp 1
.nf
CourierConnection *bdtconnection; /* BDT source descriptor */
FILE *destfile; /* output file */
char sppdata[SPPMAXDATA];
...
count = BDTread(bdtconnection, sppdata, SPPMAXDATA);
while (count > 0) { /* actually read data */
if (fwrite(sppdata, 1, count, destfile) == 0) {
/* error while writing */
BDTabort(bdtconnection);
break;
}
count = BDTread(bdtconnection, sppdata, SPPMAXDATA);
}
if (count == 0) {
/* successful */
...
.fi
.sp 1
.sh 2 "StreamOf declarations"
.pp
Frequently, data to be sent on a Bulk Data connection will be described
by a StreamOfSomething declaration in the courier specification. For
example, in Clearinghouse several routines are documented as returning
a StreamOfObjectName; unfortunately, a StreamOf declaration is recursive,
and so is not immediately translatable into automatic packing and unpacking
routines which need to know in advance how much space to allocate for the
result. As a kludge, we translate such types as if the recursive
part of the declaration were a null record.
Consider:
.sp 1
.nf
StreamOfObjectName: TYPE = CHOICE OF {
nextSegment (0) => RECORD [
segment: SEQUENCE OF ObjectName,
restOfStream: StreamOfObjectName ],
lastSegment (1) => SEQUENCE OF ObjectName};
.fi
.sp 1
.lp
In the above declaration, the ``restOfStream is effectively ignored.
Given this declaration, the following routine may be passed to a
remote procedure as the Bulk Data actor.
.sp 1
.nf
#include "Clearinghouse_support.c" /* get internalize_* routines */
#define MAXPACKS 5
GetData(conn)
CourierConnection *conn;
{
int count, i;
Unspecified buffer[MAXWORDS*MAXPACKS], *bp, *bufend;
StreamOfObjectName obnames;
bufend = buffer;
bp = buffer+MAXWORDS*(MAXPACKS-1); /* end of available space */
while (count = BDTread(conn, (char*)bufend,
MAXWORDS*sizeof(Unspecified))
) {
bufend += count/sizeof(Unspecified);
if (bufend > bp) {
fprintf(stderr,"BDT read too big to fit\en");
BDTabort(conn);
/* should clear out stuff here if we knew how much */
}
}
bp = buffer;
while (bp < bufend) {
bp += internalize_StreamOfObjectName(&obnames,bp);
if (0 == (int) obnames.designator)
for (i = 0; i < obnames.nextSegment_case.segment.length; i++)
ProcessObjectName(
obnames.nextSegment_case.segment.sequence[i]);
else {
for (i = 0; i < obnames.lastSegment_case.length; i++)
ProcessObjectName(
obnames.lastSegment_case.sequence[i]);
return;
}
}
}
.fi
.sp 1
.lp
Note that this code is very awkward, and that it requires that the whole
bulk data transfer be stored in memory before it is unpacked. Stay
tuned; we intend to modify the compiler to make the handling of such
streams much easier, at the cost of incompatibility with the existing
scheme, of course!
.sh 2 "Encapsulated Protocols"
.pp
Some courier programs use what might be termed ``encapsulated protocols''
as a method of type punning to escape from the restrictions of the Courier
language. For example, in Filing
.sp 1
.nf
Attribute: RECORD [
type: AttributeType, value: SEQUENCE OF UNSPECIFIED ];
checksum: AttributeType = 0;
Checksum: TYPE = CARDINAL;
createdBy: AttributeType = 1;
CreatedBy: TYPE = User;
.fi
.sp 1
Depending on the value of the type subfield, the data in the value field
is intended to be interpreted as either a CARDINAL or a User name.
.pp
Such encapsulation is in general bad design unless a very compelling
need for it exists. It is also awkward to support in a C program. The
best way to handle such types is to write functions to code and decode
the encapsulated value using the low level packing and unpacking routines
provided by the Courier compiler. For example:
.sp 1
.nf
Filing4_User
AttrToUser(attr)
Filing4_Attribute *attr;
{
Unspecified buf[2049], *bp; /* space for biggest attribute */
Cardinal len;
Filing4_User retval;
/* useful fact: Item: TYPE = SEQUENCE OF UNSPECIFIED; */
externalize_Clearinghouse2_Item(&(attr->value), buf);
bp = buf;
bp += internalize_Cardinal(&len, bp);
bp += internalize_Filing4_User(&retval, bp);
return(retval);
}
UserToAttr(id, attr)
Filing4_User id;
Filing4_Attribute *attr;
{
Unspecified buf[2049], *bp;
Cardinal len;
/* don't know length yet, so leave space for it */
bp = buf + sizeof_Cardinal(len);
len = externalize_Filing4_User(&id, bp);
(void) externalize_Cardinal(&len, buf);
internalize_Clearinghouse2_Item(&(attr->value), buf);
return;
}
.fi
.sp 1
Since the SEQUENCE OF UNSPECIFIED may have undergone arbitrary
transformations
during deserialization, translating it to a User record consists of first
reserializing it into an array of char, then deserializing it using the
low-level routine appropriate to the encapsulated type. Translating to
an encapsulated type is an almost precise inverse.
.sh 1 "Example I: Passwd.cr"
.pp
This section contains a Courier program which implements remote lookup in
.i "/etc/passwd"
(the UNIX database of user names, passwords, home directories, and so
on).
It does not utilize Bulk Data Transfer, but does illustrate most other
features of this courier implementation.
The applications programmer would first write
.i PasswordLookup.cr ,
the description of the courier interface for the service, then might
write
.i PasswordLookup.c ,
containing the routines needed to implement a server for this courier
program, or might write
.i lookup.c ,
a typical client of this service.
.bp
.sh 2 "The specification (PasswordLookup.cr)"
.sp 1
.nf
PasswordLookup : PROGRAM 754 VERSION 1 =
BEGIN
-- This is a translation of the passwd structure in <pwd.h>
Passwd : TYPE = RECORD [
pw_name, pw_passwd : STRING,
pw_uid, pw_gid, pw_quota : LONG CARDINAL,
pw_comment, pw_gecos, pw_dir, pw_shell : STRING
];
-- Remote Errors
NoSuchUser : ERROR = 0;
OtherError : ERROR [ errorstring: STRING ] = 1;
-- Remote entry points.
LookupUid : PROCEDURE [ uid : CARDINAL ] RETURNS [ passwd : Passwd ]
REPORTS [ NoSuchUser ]
= 0;
LookupUser : PROCEDURE [ user : STRING ]
RETURNS [ passwd : Passwd, forward : STRING ]
REPORTS [ NoSuchUser, OtherError ]
= 1;
END.
.fi
.sp 2
.sh 2 "PasswordLookup_defs.h"
.sp 1
.nf
/*
* Declarations for Courier program PasswordLookup.
*/
#include <courier.h>
#include <except.h>
typedef struct {
String pw_name;
String pw_passwd;
LongCardinal pw_uid;
LongCardinal pw_gid;
LongCardinal pw_quota;
String pw_comment;
String pw_gecos;
String pw_dir;
String pw_shell;
} Passwd;
#define NoSuchUser 0
#define OtherError 1
typedef struct {
String errorstring;
} OtherErrorArg;
typedef struct {
Passwd passwd;
} LookupUidResult;
typedef struct {
Passwd passwd;
String forward;
} LookupUserResult;
extern LookupUidResult LookupUid();
extern LookupUserResult LookupUser();
.fi
.sp 2
.sh 2 "Makefile"
.sp 1
.nf
CFLAGS = -O
USEROBJS = lookup.o PasswordLookup_client.o
SRVROBJS = PasswordLookup.o PasswordLookup_server.o
LIBS = -lcr
DESTDIR = /usr/lib/courier
all: lookup PasswordLookup
lookup: $(USEROBJS)
cc -o lookup $(USEROBJS) $(LIBS)
PasswordLookup: $(SRVROBJS)
cc -o PasswordLookup $(SRVROBJS) $(LIBS)
$(USEROBJS) $(SRVROBJS): PasswordLookup_defs.h
PasswordLookup_defs.h \e
PasswordLookup_server.c \e
PasswordLookup_client.c: PasswordLookup.cr
courier PasswordLookup.cr
install: all
install -s PasswordLookup $(DESTDIR)
clean:
-rm -f *.o PasswordLookup_*.c PasswordLookup_defs.h
.fi
.bp
.sh 2 "The server procedures (PasswordLookup.c)"
.sp 1
.nf
#include <stdio.h>
#include "PasswordLookup_defs.h"
extern Passwd *getpwnam(), *getpwuid();
LookupUidResult
LookupUid(CourierConnection,CourierBDTProc,uid)
CourierConnection *CourierConnection, CourierBDTProc;
Cardinal uid;
{
Passwd *pw;
pw = getpwuid(uid);
if (pw == NULL)
raise(NoSuchUser,NULL);
else {
return (*(LookupUidResult*) &pw);
}
}
LookupUserResult
LookupUser(CourierConnection,CourierBDTProc,user)
CourierConnection *CourierConnection, CourierBDTProc;
String user;
{
LookupUserResult result;
Passwd *pw;
FILE *fwdfd;
static char forward[100];
pw = getpwnam(user);
if (pw == NULL)
raise (NoSuchUser,NULL);
else {
sprintf(forward,"%s/.forward",pw->pw_dir);
if ((fwdfd = fopen(forward,"r")) == NULL) {
forward[0] = '\e0';
else {
fgets(forward,100,fwdfd);
fclose(fwdfd);
if (strlen(forward) < 2) (
static OtherErrorArg randomerr = {
"invalid forwarding file"};
raise(OtherError,&randomerr));
}
result.password = *pw;
result.forward = forward;
return (result);
}
}
.fi
.bp
.sh 2 "The user program (lookup.c)"
.sp 1
.nf
/*
* Sample program to access remote password lookup.
* Usage: lookup machine username
*/
#include <stdio.h>
#include "PasswordLookup_defs.h"
main(argc, argv)
int argc; char **argv;
{
LookupUserResult result;
Passwd passwd;
CourierConnection *connection;
if (argc < 3 || (destaddr = getXNSaddr(argv[1])) == NULL)) {
fprintf(stderr,"Usage: %s machine file ...\en",argv[0]);
exit(1);
}
if ((connection = CourierOpen(destaddr)) == NULL) {
fprintf(stderr,"Can't open connection to %s\en",argv[1]);
exit(1);
}
DURING
result = LookupUser(connection,NULL,argv[2]);
HANDLER
switch(Exception.Code) {
case Courier_reject:
fprintf("Connection rejected, code = %d\en",
CourierErrArgs(rejectionDetails,designator) );
exit(1);
case NoSuchUser:
printf("User %s unknown on %s.\en", argv[2], argv[1]);
exit(0);
case OtherError:
fprintf(stderr,"Remote error %s\en",
CourierErrArgs(OtherErrorArg,errorstring) );
exit(1);
}
END_HANDLER;
displaypwd(& result.passwd);
displayfwd(result.forward);
CourierClose(connection);
}
displaypwd(p)
Passwd *p;
{
printf("%s:%s:%d:%d:%s:%s:%s\en",
p->pw_name, p->pw_passwd, p->pw_uid, p->pw_gid,
p->pw_gecos, p->pw_dir, p->pw_shell);
}
displayfwd(s)
String s;
{
if (*s) printf("Mail forwarding to %s\en",s);
else printf("Mail is not forwarded\en");
}
.fi
.bp
.sh 1 "Example II: PrintFile"
.pp
This example is a very simple application of Bulk Data Transfer.
.sh 2 "PrintFile.cr"
.sp 1
.nf
PrintFile: PROGRAM 756 VERSION 1 =
BEGIN
DEPENDS UPON BulkData (0) VERSION 1;
-- Remote errors.
CantPrint: ERROR = 0;
-- Remote entry points.
RPrint: PROCEDURE [ s: BulkData.Source ]
REPORTS [ CantPrint ];
END.
.fi
.sp 1
.sh 2 "A typical client (remoteprint.c)"
.lp
.sp 1
.nf
/*
* Sample proram to print a file remotely using trivial remote print
* protocol.
* Usage: remoteprint filename
*
*/
#include <stdio.h>
#include <sys/types.h>
#include <netns/ns.h> /* for XNS addresses */
#include "PrintFile_defs.h"
static FILE * source; /* communicate from main to SendSource */
main(argc, argv)
int argc;
char *argv[];
{
CourierConnection *connection;
struct ns_addr *destaddr;
if (argc < 3 || (destaddr = getXNSaddr(argv[1])) == NULL)) {
fprintf(stderr,"Usage: %s machine file ...\en",argv[0]);
exit(1);
}
if ((connection = CourierOpen(destaddr)) == NULL) {
fprintf(stderr,"Can't open connection to %s\en",argv[1]);
exit(1);
}
argv++;
while (argc-- > 2) {
argv++;
if (strcmp(argv[0],"-") == 0) source = stdin;
else source = fopen(argv[0],"r");
if (source == NULL)
fprintf(stderr,"Can't open %s\en",argv[0]);
else DURING
RPrint(connection,SendSource,immediateSource);
HANDLER
fprintf(stderr,"Call to RPrint failed.\en");
END_HANDLER;
fclose(source);
}
CourierClose(connection);
}
SendSource(bdtconnection)
CourierConnection *bdtconnection;
{
int count;
char buffer[SPPMAXDATA];
while ( (count = fread(buffer,1,SPPMAXDATA,source)) > 0 &&
BDTwrite(bdtconnection,buffer,count) >= 0 )
;
if (count <= 0)
BDTclosewrite(bdtconnection); /* last packet with EOM set */
else
BDTabort(bdtconnection);
}
.fi
.sp 2
.sh 2 "Server (PrintFile.c)"
.sp 1
.nf
#include <stdio.h>
#include <sys/types.h>
#include <netxns/ns.h>
#include "PrintFile_defs.h"
RPrintResult
Rprint(source,CourierBDTProc,s)
CourierConnection *source, CourierBDTProc;
BulkData1_Source s;
{
FILE *printpipe;
char sppdata[SPPMAXDATA];
switch (s.designator)
case active:
case passive:
raise(CantPrint);
/*NOTREACHED*/
case null:
system("print /dev/null"); /* print a null file */
return;
case immediate:
if ((printpipe = popen("print","w")) == NULL) {
raise(CantPrint);
/*NOTREACHED*/
}
count = BDTread(source, sppdata, SPPMAXDATA);
while (count > 0) { /* actually read data */
if (fwrite(sppdata, 1, count, printpipe) == 0) {
BDTabort(source);
break;
}
count = BDTread(source, sppdata, SPPMAXDATA);
}
if (pclose(printpipe) == 0 && count == 0)
return;
else raise(CantPrint);
}
.fi
.sh 1 "One Final Example"
.pp
Finally, we present a slightly
more useful example, a program to print an Interpress
file on a Services-8 printer. It depends on the standard Xerox Printing
specification, program 4 version 3. For an even better example, look
at the printing client, xnsprint, provided with the XNS Courier distribution
as
.i "./examples/print/xnsprint.c" .
.sp 2
.nf
#include <stdio.h>
#include <sys/types.h>
#include <netns/ns.h>
#include "Printing_defs.h"
#include <except.h>
static FILE *ipfile = NULL;
SendSource(bdtconnection)
CourierConnection *bdtconnection;
{
int count;
char buffer[SPPMAXDATA];
while ( (count = fread(buffer,1,SPPMAXDATA,ipfile)) > 0 &&
BDTwrite(bdtconnection,buffer,count) >= 0 )
;
if (count <= 0)
BDTclosewrite(bdtconnection); /* last packet with EOM set */
else
BDTabort(bdtconnection);
}
main(argc, argv)
int argc;
char *argv[];
{
PrintResults result;
struct ns_addr *destaddr;
CourierConnection *conn;
extern struct ns_addr *getXNSaddr();
PrintAttributes attributes;
PrintOptions options;
/* use Cornell print server, CornellS1 (slander) */
destaddr = getXNSaddr("2-273#2-852-159-207");
attributes.length = 0;
options.length = 0;
if (argc != 2 || ((ipfile = fopen(argv[1],"r")) == NULL)) {
fprintf(stderr,"Usage: %s file\en",argv[0]);
exit(1);
}
if ((conn = CourierOpen(destaddr)) == NULL) {
fprintf(stderr,"Can't open connection to %s\en",xnshost);
exit(1);
}
DURING
result = Print(conn, SendSource, BulkData1_immediateSource,
attributes, options);
HANDLER {
switch (Exception.Code) {
case Busy:
fprintf(stderr,"Busy\en");
break;
case ConnectionError:
fprintf(stderr,"Connection error, %d\en",
CourierErrArgs(ConnectionErrorArgs,problem));
break;
case InsufficientSpoolSpace:
case SpoolingQueueFull:
fprintf(stderr,"Insufficient spool space\en");
break;
case SpoolingDisabled:
fprintf(stderr,"Spooling disabled\en");
break;
case MasterTooLarge:
case TooManyClients:
case ServiceUnavailable:
case SystemError:
case InvalidPrintParameters:
case MediumUnavailable:
case TransferError:
fprintf(stderr,"Some Printing error, number %d\en",
Exception.code-ERROR_OFFSET);
break;
case Undefined:
fprintf(stderr,"Undefined error, number %d\en",
CourierErrArgs(UndefinedArgs,problem));
break;
case REJECT_ERROR:
fprintf(stderr,"REJECT: type = %d\en",
CourierErrArgs(rejectionDetails, designator));
break;
default:
fprintf(stderr,"Some random error, code %d\en",
Exception.Code);
break;
}
exit(1);
} END_HANDLER;
CourierClose(conn);
printf("Done. Request ID %x %x %x %x %x\en",
result.printRequestID[0], result.printRequestID[1],
result.printRequestID[2], result.printRequestID[3],
result.printRequestID[4]);
}
.fi
.bp
.sh 1 "Final Notes"
.pp
The issues of authentication and protection are
difficult.
They are only touched upon in this implementation.
Currently, each Courier program must perform any authentication
(presumably using the Authentication protocol)
if this is desired. A few routines exist to allow cleints and servers
to perform simple Authentication; no support for strong Authentication
has yet been written.
.pp
This implementation is fairly inefficient, especially in
the implementation of servers. Courier calls require substantial
extra copying of courier arguments and results. More significantly,
the requirement that each call spawn a unique process is very expensive
in UNIX, and should be reconsidered.
A sequence of RPCs on the same SPP stream that specifies the same program
and version number uses the same process, but in all other cases a new
process must be spawned for each individual RPC.
.pp
This implementation defines a number of reserved identifiers.
.b ">>>should list them here<<<"
.sh 1 "Appendix"
.pp
This appendix contains the grammar for the Courier language.
It is similar to the YACC specification used
by the Courier compiler.
.sp
.ps -2p
.vs -2p
.nf
.TS
l l l l l.
%token identifier number string
ARRAY BEGIN BOOLEAN CARDINAL
CHOICE DEPENDS END ERROR
FALSE INTEGER LONG OF
PROCEDURE PROGRAM RECORD REPORTS
RETURNS SEQUENCE STRING TRUE
TYPE UNSPECIFIED UPON VERSION
.TE
%%
Program :
identifier ':' PROGRAM number VERSION number '='
BEGIN DependencyList DeclarationList END '.'
|
identifier ':' PROGRAM '='
BEGIN DependencyList DeclarationList END '.'
;
DependencyList :
/* empty */
| DEPENDS UPON ReferencedProgramList ';'
;
ReferencedProgramList :
ReferencedProgram
| ReferencedProgramList ',' ReferencedProgram
;
ReferencedProgram :
identifier '(' number ')' VERSION number
;
DeclarationList :
/* empty */
| DeclarationList Declaration
;
Declaration :
identifier ':' TYPE '=' Type ';'
| identifier ':' Type '=' Constant ';'
;
Type :
PredefinedType
| ConstructedType
| ReferencedType
;
PredefinedType :
BOOLEAN
| CARDINAL
| LONG CARDINAL
| INTEGER
| LONG INTEGER
| STRING
| UNSPECIFIED
| LONG UNSPECIFIED
;
ConstructedType :
'{' CorrespondenceList '}'
| ARRAY NumericValue OF Type
| SEQUENCE MaximumNumber OF Type
| RECORD '[' FieldList ']'
| RECORD '[' ']'
| CHOICE DesignatorType OF '{' CandidateList '}'
| PROCEDURE ArgumentList ResultList ErrorList
| ERROR ArgumentList
;
ReferencedType :
identifier
| identifier '.' identifier
;
CorrespondenceList :
Correspondence
| CorrespondenceList ',' Correspondence
;
Correspondence :
identifier '(' NumericValue ')'
;
MaximumNumber :
NumericValue
| /* empty */
;
NumericValue :
number
| ReferencedConstant
;
DesignatorType :
/* empty */
| ReferencedType
;
CandidateList :
Candidate
| CandidateList ',' Candidate
;
Candidate :
DesignatorList '=''>' Type
;
DesignatorList :
Designator
| DesignatorList ',' Designator
;
Designator :
identifier
| Correspondence
;
ArgumentList :
/* empty */
| '[' FieldList ']'
;
ResultList :
/* empty */
| RETURNS '[' FieldList ']'
;
ErrorList :
/* empty */
| REPORTS '[' NameList ']'
;
FieldList :
Field
| FieldList ',' Field
;
Field :
NameList ':' Type
;
Constant :
PredefinedConstant
| ConstructedConstant
| ReferencedConstant
;
PredefinedConstant :
TRUE
| FALSE
| number
| '-' number
| '"' string '"'
;
ConstructedConstant :
identifier
| '[' ElementList ']'
| '[' ComponentList ']'
| '['']'
| identifier Constant
| number
;
ReferencedConstant :
identifier
| identifier '.' identifier
;
ElementList :
Constant
| ElementList ',' Constant
;
ComponentList :
Component
| ComponentList ',' Component
;
Component :
NameList ':' Constant
;
NameList :
identifier
| NameList ',' identifier
;
.fi
.vs
.ps