                  <<< DISK$SYSTEM:[NOTES$LIBRARY]RPC.NOTE;1 >>>
                           -< Remote Procedure Call >-
================================================================================
Note 1.0                          Introduction                        11 replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              13 lines   1-OCT-1987 16:08
--------------------------------------------------------------------------------
    This conference is a storing place for titbits of knowledge about
    the Remote Procedure Call system developed in DD/OC, or for that
    matter on other systems.
    
    Suitable material is, for example
    
    	- User problems, Bug reports, solutions
    	- Update information
    	- Pointers to more documentation
    
    The conference will be writable, so users should feel free to
    make comments or queries, if they may be enlightening for a wider
    audience.
================================================================================
Note 1.1                          Introduction                           1 of 11
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               9 lines   1-OCT-1987 17:48
                             -< Online etiquette >-
--------------------------------------------------------------------------------
    For information on "online etiquette", see the sample conference,
    which has hints about how to use NOTES.
    
    Please, if you write a note, sign it with you name and institute
    unless you have set up a suitable personal name in you NOTES profile
    (so that it appears at the top of the NOTE).
    
    Tim Berners-Lee CERN/DD
    VXCERN::TIMBL
================================================================================
Note 1.2                          Introduction                           2 of 11
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               6 lines  25-OCT-1989 21:00
                          -< Is there anybody there? >-
--------------------------------------------------------------------------------
    It would be interesting to know whether anyone is actually following
    this conference.  If you are, please reply to this note. If you find
    you can't reply for some reason, then mail me. Thanks!
    
    Tim BL
    
================================================================================
Note 1.3                          Introduction                           3 of 11
VXCERN::BRUCE "Bruce Wessels"                         7 lines  26-OCT-1989 09:20
                      -< Well here is oneperson who does >-
--------------------------------------------------------------------------------


	Yup I follow it! Normally read it when my Vaxstation has crashed
and is rebooting and after i have read the Unix news

		Bruce Wessels

================================================================================
Note 1.4                          Introduction                           4 of 11
VXCRNB::WA80                                          3 lines  26-OCT-1989 10:10
                   -< Well, here is anther person who does >-
--------------------------------------------------------------------------------
    Yes, I follow it too!
    	Burkhard Kolb
    
================================================================================
Note 1.5                          Introduction                           5 of 11
VXCERN::DIVIA "Roberto Divia` CERN-DD/OC"             0 lines  26-OCT-1989 11:04
                                   -< I do >-
--------------------------------------------------------------------------------
================================================================================
Note 1.6                          Introduction                           6 of 11
VXL3EC::BOBCLARE "Bob Clare"                           1 line   3-NOV-1989 15:41
                                 -< i do too >-
--------------------------------------------------------------------------------
    
================================================================================
Note 1.7                          Introduction                           7 of 11
43478::BERMAN "wild wild hair..."                     2 lines   7-NOV-1989 23:04
                          -< hands across the water >-
--------------------------------------------------------------------------------
    me too, me too, me too!!!
    
================================================================================
Note 1.8                          Introduction                           8 of 11
FNAL::BCBROWN "Bruce C. Brown MS316 X4404 FNAL"        1 line  14-NOV-1989 01:18
                      -< One more time, with feeling.... >-
--------------------------------------------------------------------------------
    I try to keep up.....
================================================================================
Note 1.9                          Introduction                           9 of 11
VXCERN::PETERB                                        2 lines   4-JAN-1990 16:39
                                  -< Me too >-
--------------------------------------------------------------------------------
    I'm listening too
    
================================================================================
Note 1.10                         Introduction                          10 of 11
VXCRNB::CAMACHO "Angel Camacho-Rozas. FAEnet/Spain"   2 lines   5-JAN-1990 17:23
                                -< Me three... >-
--------------------------------------------------------------------------------
    Me too, of course !
    
================================================================================
Note 1.11                         Introduction                          11 of 11
VXCERN::MUELLERW                                      0 lines  12-JAN-1990 12:47
                                  -< Me too >-
--------------------------------------------------------------------------------

================================================================================
Note 2.0                   Updates to the RPC software                17 replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               2 lines   1-OCT-1987 16:16
--------------------------------------------------------------------------------
    This topic and its replies are about updates to the RPC software.
    (If you have comments, please reply to a different topic.)
================================================================================
Note 2.1                   Updates to the RPC software                   1 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              34 lines   1-OCT-1987 16:18
================================================================================
Note 2.2                   Updates to the RPC software                   2 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               8 lines   1-OCT-1987 16:21
                             -< Version 2.1 plans >-
--------------------------------------------------------------------------------
    Version 2.1 is currently being put together. It is not guarranteed
    stable, but is accessible by calling @[rpc.v2_1]setup.
    
    The v2.1 runtime system includes a protocol for error recovery when running
    over raw ethernet.
    
    The compiler will include extra options, including
    the generation of stubs in C rather than Pascal.
================================================================================
Note 2.3                   Updates to the RPC software                   3 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              12 lines   1-OCT-1987 17:37
                               -< RSM68K system >-
--------------------------------------------------------------------------------
    The RMS68K version of the RPC run-time system has been made romable
    (by Dirk Gosman).  A package is available which includes the full
    RPC system to run over ethernet, including the BOOT task (for use
    with the TARGET program, among others), and the option of remote
    terminal.
    
    Mail me if you would like details, with an example 'makefile'
    (MMS description) for an RMS system.
    
    Tim Berners-Lee
    VXCERN::TIMBL
                                                       
================================================================================
Note 2.4                   Updates to the RPC software                   4 of 17
VXCERN::RPC                                         130 lines  15-JAN-1988 10:48
================================================================================
Note 2.5                   Updates to the RPC software                   5 of 17
VXCERN::RPC                                           8 lines  18-JAN-1988 11:50
                    -< User Guide Coordinates: Correction >-
--------------------------------------------------------------------------------
    The DOCPRINT command to get a copy of the User Manual (if you are at
    CERN) was incorrectly given in the V2.1 release notes, as the category
    name has been changed from "USER" to "USER_GUIDES". The command should
    be 
		DOCPRINT RPC USER_GUIDES RPCUSER (XSCRIPT

    Apologies for the error.    
    Tim Berners-Lee
================================================================================
Note 2.6                   Updates to the RPC software                   6 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              17 lines  18-MAY-1988 16:17
                     -< Package numbers become invisible >-
--------------------------------------------------------------------------------
    The RPC system has just got smarter, so that if you have more
    than one package provided by a server, the client doesn't have
    to know the individual package numbers.  You can simply omit the
    package number from the address, and the RPC system will check
    at initialisation time with the remote node, asking it what package
    number to use.
                                                    
    This should make the addressing simpler all round.
    
    Incidentally, this will happen to get round a problem with the simple
    ethernet protoicol that the first call of a session could be executed
    twice. The first message sent will always be the look-up call, which
    will not mind being repeated.
    
    These improvements will go into the next general release, Prereleases
    for VMS, MoniCa and RMS68k are avilable to those interested. The
    system will be back-compatible with previous versions.
================================================================================
Note 2.7                   Updates to the RPC software                   7 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"             153 lines  22-AUG-1988 11:47
_______________________________________________________________________________

			More Information
			================

	The details of how to use the RPC system are in the RPC User 
	Manual.	At CERN, if you have an account on the CERNVM machine,
	you can get a copy with the the command (under VM/CMS) 

		DOCPRINT RPC USER_GUIDES RPCUSER (SGML

	The text is available on DECNET in flat form as 

		CERNVM::CMS:[ONLINE.210]RPCUSER.HELPMANU

	or in SGML form as 
 
		CERNVM::CMS:[ONLINE.210]RPCUSER.SGML 
 
	On-line help:
 
		VMS help files are included in this release. (HELP RPC)
 
	VAX/NOTES Conference:
 
		For up to date release information, bug reports and user
		feedback, see the VAX/NOTES conference VXCERN::RPC.
		If you haven't used NOTES before, give the commands

			$ NOTES
			> CREATE ENTRY VXCRNA::RPC
			> OPEN RPC
			> SET SEEN
			> DIR *.*

		On future occasions, just say

			$ NOTES RPC

	Electronic Mail:
 
		Please send any suggestions, comments or problems by mail to 
 		VXCERN::TIMBL (or put them into the NOTES conference 
		if they may be of general interest)
 
	Internals:

		An Implementation Guide is available to those 
		interested in porting the system to new environments. Mail 
		VXCERN::TIMBL if you would like a copy.
================================================================================
Note 2.8                   Updates to the RPC software                   8 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              19 lines  30-AUG-1988 16:31
                    -< DECNET addresses now have a default >-
--------------------------------------------------------------------------------
    A recent enhancement makes communications between many tasks easier
    with DECNET and VMS.  Firstly, you can give a server address of
    the form
    
    			*.DECNET
    
    omitting the decnet object name:  in this case, the object name
    will default to the name of the process.  Secondly, if you call
    RPC_CALLER_ADDRESS from within a server routine, the address returned
    will be of the form
    
    		NODE::"0=ppppp".DECNET
    
    where ppppp is the process name of the calling process. (This was
    true in V2.2).  Therefore, if each process calls RPC_ASYNC_SERVER
    and passes the string "*.DECNET", then any process they call will
    be able to call them back later at the address returned by
    RPC_CALLER_ADDRESS.  The parameters to RPC_CALLER_ADDRESS are in
    the v2.2 manual.
================================================================================
Note 2.9                   Updates to the RPC software                   9 of 17
VXCERN::RPC                                          32 lines  20-OCT-1988 14:46
                   -< RPC error into user status parameter >-
--------------------------------------------------------------------------------
    Normally, if a remote procedure call fails because of some
    communication or RPC address error, the programs stops, or a user
    error handler is called and execution is resumed.
    
    There has been a request for an alternative action for remote
    procedures which take a status parameter. The run-time library now
    has code to allow safe calls which will not terminate on error, but
    will just return an error status as one of the parameters. In the case
    that the call succeeds, the parameter returned is the one given by the
    server as usual. There is no compiler support for this yet, but those
    of you who are modifying your own stubs will be able to use it. The
    change is made to the client stub, so that where it read 
    
    	rpc_call(h_xxxx, rpc_p_buf, ttttt);
    	with rpc_p_buf^ do begin
    		...
    
    it reads instead
    
    	my_status := rpc_call_status(h_xxxx, rpc_p_buf, ttttt);
    	if odd(my_status) then with rpc_p_buf^ do begin
    		...
    
    The "my_status" here is the name of one of the parameters to the
    procedure.  The new run-time function rpc_call_status will not unwind
    the stack or call any user error handler, print any message, or halt.
    This facility is available with the current "development" version of
    the run-time system, and will be put into the next general release.
    Compiler support for this will have to wait. 
    
    Tim BL         
    
================================================================================
Note 2.10                  Updates to the RPC software                  10 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              18 lines   4-NOV-1988 11:25
                             -< Compiler goodies >-
--------------------------------------------------------------------------------

In response to many requests ... the RPC compiler will soon allow

	o	Record (structure) types.
	o	Nested composite types, eg arrays of records of...
	o	Pointers to named types (some restrictions).
	o	Special, user-defined data types.

If anyone wants a prerelease now, please mail me - otherwise, this will come
out with release 2.3 maybe around Christmas time. Also in that release,
for users of Valet systems (and PILS on the VAX),

	o	Generation of stubs for PILS
and
	o	Generation of stubs for TurboPascal on the Mac
	o	Runtime support for TurboPascal on the Mac with RS232 link

Tim BL
================================================================================
Note 2.12                  Updates to the RPC software                  12 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              21 lines   3-APR-1989 11:21
                       -< One-way messages: PRAGMA CAST >-
--------------------------------------------------------------------------------
                        
    You can now specifify that a remote call which only passes data in one
    direction (IN) should not use any reply message at all. This is
    specified by the new PRAGMA CAST(proc_name) in the RPC definition
    file. (The syntax is the same as for PRAGMA CONCURRENT).
    
    The advantages of this are
    
    	o	Efficient use of stream-oriented protocols such as DECNET,
    		for example in graphics applications;
    
        o	Possibility to broadcast and multicast calls over datagram
    		services;

        o	A CAST does no blocking read (and so can, for example,
    		be called from AST level when the medium does not support
    		blocking reads at AST level).
    
                         
    The development version of the compiler and run time support support
    this feature - contact me if you want to use it.
================================================================================
Note 2.13                  Updates to the RPC software                  13 of 17
VXCERN::RPC                                           9 lines  13-APR-1989 12:58
                        -< PILS server stubs enhanced >-
--------------------------------------------------------------------------------
    A bug has been fixed in the PILS codegenerator, which showed up
    when the compiler was used with the /SPILS and /VERSION=0 options.
    
    The PILS server now also contain a procedure DETACH_<package> which
    is just like ATTACH_<package> but does the reverse.
    
    Thanks to Lionel Sacks for pointing out the bug and suggesting the
    new procedure. These changes are are now in the development version,
    and will be in the next release.
================================================================================
Note 2.14                  Updates to the RPC software                  14 of 17
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              16 lines   8-MAY-1989 12:58
                       -< Close_xxx() and Detach_xxx() >-
--------------------------------------------------------------------------------
    In response to popular request, the initialisation routines in the
    stubs have been complemented by de-initialisation routines. This
    is for use in environments (such as OS9) in which the operating
    system cannot clean up completely for an exiting image in the way
    it can under VMS, for instance. The routines generated are now
    
				Initialize	De-initialize
    
   	 Client:	    	open_xxx	close_xxx

	 Server:    		attach_xxx	detach_xxx

    
    where xxx is the package name. In these environments, if you call
    an initialisation routine, you should call the deinitialisation
    routine before exiting.
_______________________________________________________________________________

			More Information
			================

	The details of how to use the RPC system are in the RPC User 
	Manual.	Anne Perrelle CERN/DD can supply copies (about 108 pages)
	(Perrelle@cernvm.cern, PERRELLE AT CERNVM on bitnet,
	or MINT::"perrelle@cernvm.bitnet" over DECNET).

	On-line help:
 
		VMS help files are included in this release. (HELP RPC)
 
	VAX/NOTES Conference:
 
		For up to date release information, bug reports and user
		feedback, see the VAX/NOTES conference VXCERN::RPC.
		If you haven't used NOTES before, give the commands

			$ NOTES
			> CREATE ENTRY VXCERN::RPC
			> OPEN RPC
			> SET SEEN
			> DIR *.*
			> HELP

		On future occasions, just say

			$ NOTES RPC

	Electronic Mail:
 
		Please send any suggestions, comments or problems by mail to 
 		VXCERN::RPC (or put them into the NOTES conference 
		if they may be of general interest).
		(RPC@vxcern.decnet.cern.ch, RPC%VXCERN AT CERNVAX on bitnet)
 
	Internals:

		An Implementation Guide is available to those 
		interested in porting the system to new environments. Mail 
		if you would like a copy.


CERN/DD Online group
_______________________________________________________________________________ 

			More Information
			================

	The details of how to use the RPC system are in the RPC User 
	Manual.	Anne Perrelle CERN/CN can supply copies (about 108 pages)
	(Perrelle@cernvm.cern, PERRELLE AT CERNVM on bitnet,
	or MINT::"perrelle@cernvm.bitnet" over DECNET).

	On-line help:
 
		VMS help files are included in this release. (HELP RPC)
 
	VAX/NOTES Conference:
 
		For up to date release information, bug reports and user
		feedback, see the VAX/NOTES conference VXCERN::RPC.
		If you haven't used NOTES before, give the commands

			$ NOTES
			> CREATE ENTRY VXCERN::RPC
			> OPEN RPC
			> SET SEEN
			> DIR *.*
			> HELP

		On future occasions, just say

			$ NOTES RPC

	Electronic Mail:
 
		Please send any suggestions, comments or problems by mail to 
 		VXCERN::RPC (or put them into the NOTES conference 
		if they may be of general interest).
		(RPC@vxcern.decnet.cern.ch, RPC%VXCERN AT CERNVAX on bitnet)
 
	Internals:

		An Implementation Guide is available to those 
		interested in porting the system to new environments. Mail 
		if you would like a copy.

================================================================================
Note 3.0                        Run-Time problems                     19 replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               7 lines   1-OCT-1987 16:47
--------------------------------------------------------------------------------

    This topic is a list of problems found while running RPC systems.
    Some of these are problems with the underlying communications
    systems; some are with the RPC system itself.
    
    Solutions are mentioned where they are known.
    
================================================================================
Note 3.4                        Run-Time problems                        4 of 19
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              28 lines   2-OCT-1987 13:57
                   -< Ethernet: Timeouts >8sec NEVER expire >-
--------------------------------------------------------------------------------
From:	VXCRNA::BOOTH        "Chris Booth - also CNB@CERNVM"  1-OCT-1987 17:51
To:	TIMBL,BOOTH       
Subj:	TIMLIB


I have discovered a feature of the library [ RPCLIB V2.1 of 29-Sep-87]!
It does have the retry facility, but I discovered that if
the option /TIMEOUT=1000 is used, one never gets a timeout, even with no
server running.  It appears, from looking with trace on, that the time
interval is increased to a maximum of 8 s and then stays there.  (I see
this from the "backoff time" message.)  If I set a timeout of, say, 700
everything works as I would expect.
I must agree that, with retries, specifying a limit greater than 8 s gives
a very long time and is therefore unnecessary.  However, I don't think
you document anwhere that timeouts greater than 800 are equivalent to
infinity, so wonder if this is an intended feature!
                               Chris

    This was a bug in the library, which has been in all along - it's
    just that noone ever tried it with more than 8seconds before.
    For VAX/VMS, it's fixed in V2.1 now (1-Oct-87).  If your client
    is in a microprocessor, you'll have wait till you rebuild the roms
    of course.
    
    Tim BL
    

    
================================================================================
Note 3.6                        Run-Time problems                        6 of 19
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               9 lines  20-OCT-1987 16:49
                          -< M68k: Unknown RPC error >-
--------------------------------------------------------------------------------
    Version 2.0 of the M68020 software had a bug in the error message
    reporting routine, such that a valid RPC error (such as a timeout)
    would be reported as
    
    %RPC Error:  RPC error unknown to rpc_report_error!
    
    This was due to a bug which was introduced at some time, and removed
    on 20 Oct 87, for version 2.1
    
================================================================================
Note 3.7                        Run-Time problems                        7 of 19
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              10 lines  13-NOV-1987 14:25
                         -< *.ETHERNET problems, V2.0 >-
--------------------------------------------------------------------------------
    Under V2.0, when using *.ethernet or *_<ptype>.ethernet addresses,
    there is a problem when a server is dealing with many clients in
    rapid sucession: in some cases, the replies get sent to the
    wrong people!
    
    This fault is not apparent if you use *.ethernet, but only in fact
    user one partner at a time.
    
    The bug will be fixed (I hope!) in V2.1 in all versions. (The VMS
    library for V2.1 is already fixed).
================================================================================
Note 3.12                       Run-Time problems                       12 of 19
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              13 lines  10-JUN-1988 13:41
                  -< "No privilege" exit from decnet server >-
--------------------------------------------------------------------------------
    The following bug has been corrected today (10 Jun 88) in version
    2.2 of the RPC software for VMS.
    
    Symptom:	A multi-client server running over decnet exits with
    		"No privilege for attempted operation" status after running
    		happily for some time.
    		Only occurs when client breaks a connection to the server
    		immediately after using it.
    
    Repeatable: With difficulty: it requires a timing coincidence.
    
    Solution:	Use run-time library postdating 10-Jun-88 (ie V2.2 or later).
                
================================================================================
Note 3.16                       Run-Time problems                       16 of 19
VXCERN::RPC                                          11 lines  23-JAN-1989 09:08
                          -< VXCRNB ethernet problem >-
--------------------------------------------------------------------------------
    I'm sure I've recorded this somewhere before, but maybe the note
    got lost in a backup. On VXCRNB, there have been two ethernet adapters,
    one (ET:) connected to the ethernet, and one (XE:) conneceted to
    a terminating resistor! Unfortunately, the RPC system finds the
    unibus adapter (XE) first, and so attempts to use ethernet from VXCRNB
    time out, with no other error message.
    
    Solution:		$ DEFINE RPC_ETHERNET_DEVICE _ETA0:
                        
    The RPC system will use this device name (if defined) before trying
    anything else.
================================================================================
Note 3.17                       Run-Time problems                       17 of 19
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               5 lines  22-MAR-1989 17:29
          -< "Array index out of bounds" with VMS string descriptors >-
--------------------------------------------------------------------------------
    If you are using VAX/VMS and producing stubs in Pascal or FORTRAN
    which use FORTRAN-compatible string descriptors, you may get a
    Pascal array bounds violation error under some circumstances. This
    bug has been fixed in the development version, and so the cure
    is to get a release later than 2.3.
================================================================================
Note 4.0                      Compile-time problems                   10 replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               5 lines   1-OCT-1987 17:20
--------------------------------------------------------------------------------
    This is a list of problems occuring while compiling RPC stub modules,
    and linking the results together to form a client and/or server
    program.
    
    Add a problem if you have one, along with any helpful comments.
================================================================================
Note 4.1                      Compile-time problems                      1 of 10
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              28 lines   1-OCT-1987 17:28
                          -< Pascal compiler errors >-
--------------------------------------------------------------------------------

    Code produced by the RPC compiler is initially in Pascal (or
    alternatively in C), and is then compiled into object code.
    The pascal compiler can sometimes produce error messages, even though
    the RPC compiler stage ran without error.
    
    The most common problem in this case is that one of the identifiers
    used in the  RPC definition file clashes with one used by the rpc
    system itself.  You should avoid using, in you RPC defintion file
    (normally the .RPC file), any of the following:
    
    1.	Identifiers starting with:
    		rpc_
    		m_
    		call_
    		reject_
    		return_
    		abort_
    
    2.	The identifiers:
        	b,
    		header,
    		procedure_number
    		program_number,
    	      	version_number,
    		which,
    		why
    
================================================================================
Note 4.2                      Compile-time problems                      2 of 10
VXCERN::RPC                                           4 lines  14-OCT-1987 15:41
                 -< /NOAUTOINIT, /CONCURRENT options ignored >-
--------------------------------------------------------------------------------
    Under VMS, using RPC version 2.0, the /NOAUTOINIT and /CONCURRENT
    options did not work for the $ RPC command.  They did work for the
    $ RPCC command.  This has been fixed in version 2.1.
    
================================================================================
Note 4.3                      Compile-time problems                      3 of 10
VXCERN::RPC                                          12 lines  20-APR-1988 16:34
                -< Strings in C server stubs: rpc_b undefined >-
--------------------------------------------------------------------------------

    When compiling server stubs in C which involved passing strings,
    the rpcc compiler would produce bad code. This has been fixed now,
    and so will be cured in future releases. (A new fixed version of
    v2.1 is planned soon).
    
    Symptom:
    	'rpc-b' is undefined when compiling the C stub
    Cure:
    	Use a more recent version of the compiler, or edit the C code of
    	the stub to define rpc_b in the same way as rpc_a is defined
    	near the error.
================================================================================
Note 4.4                      Compile-time problems                      4 of 10
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               4 lines  27-MAY-1988 10:30
                  -< Unexpected End Of File: Spurious error >-
--------------------------------------------------------------------------------
    If the compiler finds a blank line after the final END <package>;
    of a package definition, it will give a spurious "Unexpected EOF"
    error. This is a known bug, to be fixed in time. For the mean time,
    remove the blank line.
================================================================================
Note 4.5                      Compile-time problems                      5 of 10
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               3 lines   3-APR-1989 11:33
                         -< Semicolons in FORTRAN ?! >-
--------------------------------------------------------------------------------
    The RPC compiler, v2.3, when producing stubs in FORTRAN with the
    CONCURRENT option or pragma would produce the occasional line with
    semicolons on the end. This is fixed in future versions.
================================================================================
Note 4.6                      Compile-time problems                      6 of 10
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               4 lines  25-OCT-1989 21:02
                     -< Compiler loops on long qualifier >-
--------------------------------------------------------------------------------
    There was a problem with the RPC compiler's command line parser which
    caused it to loop indefinitely if a qualifier keyword of more than 12
    characters was accidentally given. This has been fixed in v2.4.
    
================================================================================
Note 4.7                      Compile-time problems                      7 of 10
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               8 lines  10-NOV-1989 10:12
              -< Compiler loops on PRAGMA on undefined procedure >-
--------------------------------------------------------------------------------
    Roberto Bagnara discovered that if you give a PRAGMA CONCURRENT or
    PRAGMA CAST for a procedure before it is declared, the v2.4 RPC
    compiler loops.
    
    It is in fact required that the procedure/function should have been
    declared before the pragma -- but still the compiler shouldn't loop of
    course. An undefined procedure name is now handled properly (with an
    error message) in versions later than 2.4.
================================================================================
Note 4.8                      Compile-time problems                      8 of 10
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              16 lines  29-NOV-1989 18:36
                          -< DO.. END DO not FORTRAN >-
--------------------------------------------------------------------------------
    When generating stubs in FORTRAN (with the /SFORTRAN or /CFORTRAN
    qualifiers), if an array or sequence data type was used, the compiler
    would generate DO .. END DO loops.  This is fine for VAX/FORTRAN, but
    is not OK for minimal FORTRAN77 compilers.
    
    This has been fixed (chaged to DO <label>, ... <label> CONTINUE) in
    versions of the compiler postdating this note. (ie. 2.4.0).
    
    
    
    
    
    
    
    
 
================================================================================
Note 4.9                      Compile-time problems                      9 of 10
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               5 lines  29-NOV-1989 18:38
                            -< "TYPE" not pascal! >-
--------------------------------------------------------------------------------
    The compiler would generate a spurious word "TYPE" when making an
    external definition (.ext) file in C.  This has been fixed in versions
    of RPCC postdating this note. (i.e. after 2.4.0)
    
    
================================================================================
Note 5.0                        RPC documentation                      7 replies
                                                      0 lines   1-OCT-1987 17:55
--------------------------------------------------------------------------------
================================================================================
Note 5.1                        RPC documentation                         1 of 7
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              10 lines   8-OCT-1987 11:17
                          -< Paper at RT conference >-
--------------------------------------------------------------------------------
    I submitted a short paper, "Experience with Remote Procedure Call in
    Data Acquisition and Control" to the Real-Time conference in San
    Fransico last May.
    
    The paper describes the technical choices which were made,
    advantages found, special facilities requires and simplifying
    assumptions which we could make.  It acknowldges the work of Antonio
    Pastore, Tim Adye, Dirk Gosman, Ignacio Martinez and Bob Jones on
    the project.  I have (and can run off) spare copies, or they are
    available as a DD note.
================================================================================
Note 5.2                        RPC documentation                         2 of 7
VXCERN::RPC                                            1 line  28-OCT-1987 16:12
                           -< Directory not found? >-
--------------------------------------------------------------------------------
    See topic 7 if you can't find the directory. For disk$dd use diskl$d1
================================================================================
Note 5.3                        RPC documentation                         3 of 7
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              13 lines   2-JUN-1988 12:12
                        -< Documents on CERNDOC scheme >-
--------------------------------------------------------------------------------
    The RPC documentation is now officially stored on the "CERNDOC"
    scheme on the CERNVM node (an IBM VM/CMS system). The files are
    still available via DECNET if one knows the filenames. The user
    manual is currently under
    
    	CERNVM::CMS:[ONLINE.210]RPCUSER.SGML
    
    in SGML mark-up format, and in 
    
    	CERNVM::CMS:[ONLINE.210]RPCUSER.HELPUSER
    
    as a flat ASCII file. Of course, if you can log on to CERNVM and
    use CERNDOC, then you can find the documents yourself.
================================================================================
Note 5.4                        RPC documentation                         4 of 7
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               4 lines  13-JUN-1988 15:46
                            -< Introduction to RPC >-
--------------------------------------------------------------------------------
    I now have an introductory paper describing Remote Prpocedure Call.  As
    it's in Microsoft Word format with embedded graphics, it's probably
    best to mail me if you would like a copy on paper. It's about 6
    pages, and is very general, for those not familiar with RPC at all. 
================================================================================
Note 5.5                        RPC documentation                         5 of 7
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               6 lines  22-AUG-1988 11:42
                 -< Introduction to RPC - CERNDOC coordinates >-
--------------------------------------------------------------------------------
    The introduction to RPC is now in CERNDOC:
    
    	DOCFIND RPC USER_GUIDES RPCINTRO
    
    For the DOCFIND program under VMS, see the USER_SUPPORTED_SW
    conference. To print it, you'll need to log in on VM still.
================================================================================
Note 5.6                        RPC documentation                         6 of 7
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              81 lines  20-OCT-1988 15:37
                         -< Getting documents by mail >-
--------------------------------------------------------------------------------
    You can get at CERNDOC documents, if you are not on the CERNVM node or
    an HEP DECNET node, by mailing to   CERNVM::CERNDOC (CERNDOC AT CERNVM
    on bitnet, or CERNDOC@CERNVM.cern), with the DOCFIND command as the
    message. What you get will be a flat unformatted version without any
    pictures. 
    
    If you send the message "HELP DOCFIND" you get the
    text appended to this note.
    
    [If you are on a VMS VAX on HEPnet you can run the VMS version of
    DOCFIND to interrogate the database, and pick the documents up over
    DECNET - see the USER_SUPPORTED_SW conference on this node]
    ________________________________________________________________________
    
    

DOCFIND via MAIL

This command  is used to  return to the  user via MAIL  a copy of  any document
which  has been  registered  in  CERNDOC. If  the  document  being accessed  is
confidential only a copy of the header will be returned to the user.

If the DOCFIND  command is sent to  CERNDOC@CERNVM via MAIL, the  syntax of the
command is one of the following:

+--------+-------------------------------------------------+
|DOCFIND | project  (category  (filename))                 |
+--------+-------------------------------------------------+

or

+--------+-------------------------------------------------+
|DOCFIND | keyword1  keyword2  keyword3.....               |
+--------+-------------------------------------------------+

where

project   is the name of the project where the document has been stored

category  is the name of category within the given project where the
document has been stored.

filename  is the name of the document which is to be found

keywordn  is a list of words related to this document


DOCFIND will interpret the command line in the following way:

1)     If no  argument is  given or  none  of the  arguments match  any of  the
     projects registered in CERNDOC or the  arguments do not match the keywords
     related to  a registered  document DOCFIND  will return  the names  of the
     projects registered in CERNDOC.

2)    If an argument is the name of  a registered project but none of the other
     arguments match  any of the categories  registered in that project  or the
     arguments do  not match the keywords  related to a document  registered in
     that project DOCFIND will return the names of the categories registered in
     the project.

3)    If an  argument is the name of  a registered project and an  other is the
     name of a category registered in that project, but the third or subsequent
     arguments do not match the name of  a document registered in that category
     or match  the keywords related to  a document registered in  that category
     DOCFIND will return the names of the documents registered in the category.

4)    If  the arguments  match the project,  category and  document names  of a
     document registered in CERNDOC or the keywords of a document registered in
     CERNDOC a copy of the document will be mailed back to the user, however if
     the document was confidential a copy of the header will be returned.


USAGE NOTES:

1)   With a keyword  search no specific order for the  keywords is required and
     the keywords can include the project  name and/or the category name and/or
     the document name and/or any of the user specified keywords.

2)   A copy  of the document or header  will be returned if  the keywords given
     uniquely identify  a document  otherwise a  list of  the names  of matched
     documents will be returned.
================================================================================
Note 5.7                        RPC documentation                         7 of 7
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              12 lines  20-FEB-1989 11:24
                    -< New RPC User and Internals Manuals >-
--------------------------------------------------------------------------------
    The new RPC User Manual (DOCFIND RPC USER_GUIDES RPCUSER) is now
    available. It includes information on using the new compiler features,
    and the OS9 and Mac implementations.
    
    The "RPC Internals" manual (formerly "RPC Implementation
    Guide") has been substantially fattened in response to spceific
    requests.  It is a collection of whys and hows and wherefores of
    the RPC system. (DOCFIND RPC USER_GUIDES RPCUSER).
    
    If you can't use DOCFIND, try asking Anne Perrelle (CERN/DD)
    (PERRELLE@CERNVM.BITNET) who keeps copies.
                          

================================================================================
Note 6.0                      Digital's RPC product                    3 replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               8 lines   8-OCT-1987 10:59
--------------------------------------------------------------------------------
    We have been approved as a field test site for DEC's own RPC system,
    VAX/RPC v1.0, for nine months from the end of October 87.  All I
    have at the moment (8-Oct) is an outline description, but it seems
    to work on just the same principles as our own system, and runs
    over DECnet, or within a machine using global sections.
    
    I anyone is interested in trying this code, or getting a copy of
    the documentaion (under non-disclosure), could they mail me please.
================================================================================
Note 6.1                      Digital's RPC product                       1 of 3
VXCERN::RPC                                           2 lines  12-OCT-1987 15:40
                           -< Field test postponed >-
--------------------------------------------------------------------------------
    The field test has now been postponed by Digital until January 1988,
    pending architecture discussions within Digital.
================================================================================
Note 6.2                      Digital's RPC product                       2 of 3
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              13 lines  30-SEP-1988 17:27
                      -< VAX/RPC suspended indefinitely >-
--------------------------------------------------------------------------------
    Digital has now suspended the VAX/RPC product indefinitely (that
    is, cancelled it). This is nominally because it was "inconsistent
    with Digital's overall goals to potentially support industry standards
    and the Open System Foundation (OSF)". So officially they are waiting
    for standards to gel. This cancellation was not totally unexpected.
    Can we now hope that in a little while, Apollos and Vaxes will be
    talking to each other using compatible RPC systems? It's not so
    unlikely.  Meanwhile, Apollo NCS looks like the best bet for a standard
    with which our RPC system should converge...
                             
    I have a short test report about the small amount of testing I did
    with VAX/RPC though I guess it had better be for CERN/DD distribution
    only, as the test was subject to nondisclosure.
================================================================================
Note 6.3                      Digital's RPC product                       3 of 3
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              11 lines  22-MAR-1989 17:17
                                -< DEC go NCS >-
--------------------------------------------------------------------------------
    A press release jointly by Apollo (H-R Dervy, +41 1 835 77 77)
    and DEC (Elizabeth Vogler, +41 1 816 93 32) dated 14 March 89
    talks of the two companies joining forces to work on NCS, with
    DEC contributing their WAN know-how, and both companies integrating
    the results into their network products.
    
    This has got to be good news, and rather what I had hoped for.
    They talk about the "new specifications of the extended RPC"
    which will be "widely distributed".  I wonder how much change
    there will be...
                                                  

================================================================================
Note 7.0                      Disk change on VXCERN                   No replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              16 lines  12-OCT-1987 14:32
--------------------------------------------------------------------------------
    On 12 October, the RPC software was moved on the VXCERN cluster. This
    means that where, in a logon file (or anywhere else) you had 

	$ @disk$dd:[rpc]rpc.com

    or anything similar, that it must be CHANGED to 

	$ @disk$d1:....

    Documentation and help files residing on disk$dd:[rpc...] and
    disk$dd:[timbl...] have also moved to disk$d1:, so where documents
    carry instructions for printing them on VXCERN, these instructions
    should be modified. 

    All refernces to DISK$DD: in this NOTEs conference before 12-Oct-87
    should be considered as refering to DISK$D1: 

================================================================================
Note 9.0               Support for CATS on VMS from Delphi             3 replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              23 lines  28-OCT-1987 14:21
--------------------------------------------------------------------------------
Delphi, and Ignacio Martinez, have volunteered to support a CATS
under VAX/VMS. The message below explains the principle; I would
expect filenames etc to follow.
________________________________________________________________

From:	Frank_Harris <HARRIS@UK.AC.OX.PH.V1> 28-OCT-1987 09:47
To:	HARRIS,EAN%PRIAM.CERN::JMG,JANET%CERN.VXCRNA::MARTINEZ
Subj:	CATS on VAX
                                
Dear Mike,                      

I write to confirm what we agree at our meeting at CERN last week.
Ignacio Martinez will support CATS over DECNET/VOTS/X25 in VAX/VMS.
We are happy to make this software available to the HEP community,
with error reporting going to MARTINEZ on VXCRNA. We will make
the sources available also so people can feel less nervous about the
support problem!
We hope that Tim Berners-Lee can integrate Ignacios software into his
supported RPC software. Under separate cover I will send details of
the directories etc.
                                                              
Frank Harris   28 Oct 1987
                                                                
================================================================================
Note 9.1               Support for CATS on VMS from Delphi                1 of 3
43015::HEINICKE "Peter Heinicke FNAL/DAQ"             3 lines  17-MAY-1988 23:51
                                   -< CATS? >-
--------------------------------------------------------------------------------
    What is CATS? (Please supply a brief description)
    -phh
    
================================================================================
Note 10.0                         RPC Utilities                        2 replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               2 lines  28-OCT-1987 15:20
--------------------------------------------------------------------------------
    This topic covers announcements and queries about utilities which
    use RPC.
================================================================================
Note 10.1                         RPC Utilities                           1 of 2
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              66 lines  28-OCT-1987 15:23
                        -< TARGET added features Jun87 >-
--------------------------------------------------------------------------------
Updated version of TARGET program			  TBL 5 June 87

There was (5 June 87) a new version of TARGET.EXE, the interactive program
for controlling and interacting with target M68000 based systems. It is in
VXCRNA::DISK$D1:[RPC.V2_0]TARGET.EXE. Details of its new features follow.

(General help can be obtained, if you have setup the rpc software, using
HELP TARGET). 

1. TARGET supports many interactive sessions in different
   windows on a VT220. The new commands

	SET SERVER	starts a server to handle a new client process
	WINDOW		allows selection, sizing and deletion of windows

	Any window is available for output, but only one for input.
	The WINDOW command allows the following keys to be used:

	<Next page>	Move cursor between windows
	<Prev page>

	<Up>		Move window dividers to change the window size
	<Down>

	<Select>	Exit the WINDOW command, with the chosen window
			selected for input.

	<Remove>	Removes a window from the screen


	Once inside an M68k interaction window, you can get back to the
	window command (and hence back out of the window!) by pressing
	control/C then W.
	
2. Target can be run from a command file, with the same syntax, but
   with abreviated keywords instead of single keystrokes for menu
   selection.  A "*" is used instead of RETURN to select a default option.

	Example command file:

		$ TARGET 026086000567
			file load myprog.abs
			go *
			display registers
			quit
		$ TARGET 026086000123
			set task name TSK1
			set task stopped
			file load myprog3.abs
			set reg prog 300000
			set task running		
			quit

3.	TARGET may be set up as a foreign command to take command line
	parameters, syntax as for a command file.  In this case,
	set_target must first be used to define the target ethernet address.
	If command line parameters are given, they are executed then control
	returned to DCL.

		$ TAR :== $RPC$UTIL:TARGET.EXE	! Note initial dolloar sign
		$ set_target 026086000123
		$ tar fi lo myprog.abs go *


Please send reports of any bugs (or suggestions for more improvement)
to TIMBL@VXCRNA. Thanks.
================================================================================
Note 10.2                         RPC Utilities                           2 of 2
VXCERN::RPC                                          12 lines   2-DEC-1988 14:44
                             -< TARGET for VMS V5 >-
--------------------------------------------------------------------------------
    I have made a new version of the "TARGET" utility, for two reasons.
    Firstly, the old one did not work under V5, due to a bug. Secondly,
    the remote terminal aspect is all being coordinated by Bruce Wessels
    now and will be part of a separate product. The new version of TARGET
    does not therefore support the "SET HOST" command.
    
    The latest version is available as vxcern::disk$d1:[rpc.util]target.exe
    for those who need a copy for a VMS V5 machine. It will be distributed
    will the Valet support software in due course.
    
    Tim BL
    

================================================================================
Note 11.0                     RPC Example Programs                       1 reply
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               2 lines   4-FEB-1988 15:41
--------------------------------------------------------------------------------
    This topic is for information on example programs and applications
    using RPC
================================================================================
Note 11.1                     RPC Example Programs                        1 of 1
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"             123 lines   4-FEB-1988 15:42
                                -< Battleships >-
--------------------------------------------------------------------------------
================================================================================
Note 12.0                          RPC for OS9                         3 replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"             346 lines  14-APR-1988 15:17
--------------------------------------------------------------------------------
       The first release of RPC software for OS9 is now available.
    The release notes are appended to this note. You can get a copy
    by creating a suitable directory and unwrapping the save set:
    
    $ BACKUP VXCRNA::DISK$D1:[RPC.DISTRIBUTION_KIT]RPC_OS9010.A/SAV-
    	[]*.*
                           
    ________________________________________________________________________

    This release is the first release of the RPC system for OS9.  It is
    basically tested, and has been used for a number of applications, but
    is in its early stages. 

See the RPC manual (a version postdating this release) for details of how
to make and link RPC programs to run on OS9.

This release contains the following files:

	rpcrts.c	The run-time system kernel
	ts.c		The transport service used by the rpcrts
	ether.c		Interface to T. Charity's ethernet driver.

	rpcheader.h	Incldue file used when compiling the C stubs under OS9
			(Identical to the file in the RPC_VMS product)

	RPC_OS9.release_notes
			These notes.

The following note by Johannes Raab (CERN/EP, OPAL) describes the use of RPC
under OS9 in OPAL.

If your have problems, or require more information, then mail VXCERN::TIMBL
or use the VXCERN::RPC conference under VAX/NOTES.
______________________________________________________________________________


	              REMOTE PROCEDURE CALLS (RPC)

In this note I address neither the pro's and con's nor the meaning and logic of
RPCs. I simply want to provide a crude recipe for using them. In depth
documentation exists from DD/OC: the most useful is "RPC USER MANUAL" by Tim
Berners-Lee, and some nitty-gritty info can be found in "RPC SYSTEM:
IMPLEMENTATION GUIDE" also by TBL. Indeed, the first few pages of the RPC USER
MANUAL are prerequisite reading to the remainder of this note. 

To the programmer an RPC is just a function/subroutine call--to be executed on
a remote machine--plus a little extra work. However, the user of the final
product will never know where the data goes to, or comes from, i.e. from
VME/OS9, VAX/VMS, Apollo, Apple, ... . The fundamental idea is clean and easy
communication between our vaxes and our local system crates. 

The following gives a method for obtaining two simple types of RPC's: the first
example is a CLIENT program on VAX/VMS with the SERVER on VME/OS9, and the
second has the roles reversed. The client is the one making the call while the
server executes it. Note, that a client (server) may have several different
servers (clients) at a time. The sky (=40) is the limit. 

At the time of writing (11.3.88) the RPC game is played in OPAL on three
systems: VXCERN, UXOPCJ (could be any other VAX or mu-VAX), and VME/OS9. VXCERN
and now VXOPON (16.3.88) has all the machinery to make RPC stubs but VXCERN
should not be used to make calls to OS9. Most of the VXCERN executable images
will run on the other vaxes, unless the programs contain very system specific
calls. 

LANGUAGE MIXING

A word of caution: C is the preferred language for OPAL RPC's because all the
underlying OS9 programs use C. It is no problem to run Fortran code on the VAX
side, but the use of RTF on OS9 has not been tested yet. Care must be used in
using stubs in C with programs in FORTRAN mainly because of the different
treatments of character and string variables in C and Fortran. 

In any case, you must specify the client and server environments when you 
use the RPC compiler (see the RPC MANUAL for details).

The /GENERICC and /BYVALUE options should
be used for C-compatible stubs in C on either VMS or OS9.
The /SVAXVMS and /CVAXVMS options should be used for FORTRAN compatible
stubs under VMS.
  
There is no restriction on mixing langauges on different machines: FORTRAN
programs under VMS may call C programs under OS9, for example, as all the
communication is performed using langauge-independent formats. 

                              ________

 
RECIPES:
--------

general tools:
 
       -- LOGIN on VXCERN
       -- execute DISK$D1:[RPC]RPC  to get access to logical names, etc
       -- C users must define the logical names for the standard libraries


**************************************************************
*  EXAMPLE 1:   server on VAX/VMS written partly in Fortran  *
*               client on VME/OS9 written in C               * 
**************************************************************

 SERVER  program: ( vxcrna::disk$opal1:[raab.rpc.vax_com]os9_dcl.for)
  --------------------------------------------------------------------
                                        
              INTEGER FUNCTION OS9_DCL(COMMAND)
      C       execute a VAX command from OS9
              CHARACTER *(*) COMMAND
              OS9_DCL = LIB$SPAWN(  COMMAND       ,        !command
           +                                      ,        !input file
           +                                      ,        !output file   
           +                     )                         !many other parameters
      C       keep a record of action and status
              OPEN(35,FILE='OS9_DCL.OUT',FORM='FORMATTED',
           +       STATUS='UNKNOWN',ACCESS='APPEND')
              WRITE(35,10) COMMAND, OS9_DCL
        10    FORMAT(//,2X,'Command was: ',A,/,2X,'Status returned: ',I10,/)
              CLOSE(35)
              RETURN
              END
        


      -- CHECK that program compiles !!


  RPC data/variable definition file:(vxcrna....[ ...vax_com]dcl.rpc)
  ------------------------------------------------------------------

  PACKAGE OS9_SERVICE IS
     TYPE IN_STRING IS STRING(133);
     FUNCTION OS9_DCL( COMMAND : IN  IN_STRING)  RETURN RPC_LONG;
  END OS9_SERVICE;


  SERVERLOOP routine (VXCRNA::.[..]serverloop.c)
  ------------------

      #include <rpcheader.h>
      #include <stdio.h>
          extern attach_os9_dcl();    /* comes from server stub */
    
      main()
      {
         /* the name between " " must be EXACTLY 40 char long, and should be 
            identical to the package name in the .RPC declaration file */
         rpc_name service = "OS9_SERVICE                             ";
         rpc_status status;
       
         attach_os9_dcl(); 
       
         rpc_loop_server(&status,service);
         rpc_report_error(&status);      
       }
  

  COMMAND file to RPC, compile, and link the SERVER files:
  --------------------------------------------------------

      $! PRODUCE STUBS (SERDCL.OBJ AND CLIDCL.RPC)
      $ rpc dcl.rpc /svaxvms /cgenericc /noautoinit /byvalue
      $! LINK THE SERVER ROUTINES ASSUMING THEY HAVE BEEN COMPILED 
      $ link/debug os9_dcl.obj, serdcl.obj, serverloop.obj, rpc$lib/lib
               


  PORT/COPY the CLIENT stub to OS9:
  ----------------------------------------------------

       --edit to make OS9 compatible
              this encompasses 2 changes:
                   1) the replacement of all " " in the INCLUDE statement
                      by < > (if there are any)
                      (or specify the complete path)
                   2) the addition of a '*' in front of the variable 'service'
                      at the declaration line in the stubs


  CLIENT  program:( has been edited for illustration, 
                    complete code in   /m17/rpc/dcl/dcl.c)
  --------------------------------------------------------


      #include <strings.h>
      #include <types.h>
      #include <rpcheader.h>
    
         extern void open_os9_service();
         extern void rpc_init();
         extern rpc_long os9_dcl();   /* see DCL.EXT file produced by RPCing */
      
      main (argc,argv)
      int argc;
      char *argv[];
      {
         int i, j, istat;
         char command[133], temp[133];
         static char *first_call = {" "};
         static char *next_call = {"command_is"};
    
         rpc_init();
         open_os9_service();
         istat = os9_dcl(first_call);               /*send a nothing first */
         istat = os9_dcl(next_call);                /*send the command     */
         if (istat == 1) 
             printf(" On this end (muVAX and OS9) all is fine\n");
         else {
               printf(" SORRY, there has been a problem! Please, see\n");
               printf("        an expert and report ISTAT = %d\n",istat);
               }
    
        }
    



 
     --compile and link on OS9 with the following commands (for C code
               it is useful to set the environment variables CDEFS and CLIB
               to /m14/defs and /m14/lib respectively.

               1) cc -ros -v=/m17/rpc filename
                  (the -v=... is not necessary if you use full pathnames 
                        for RPC-include files)
               2) cc -x client.r clientstub.r /m17/rpc/*.r -f=fileout
             

  DEFINE ethernet address on the VAX and VME:
  ------------------------------------------------------------------------
       on the VAX the logical variable will by default be the PACKAGE name
          as defined in the .RPC declaration file. Make sure that this name
          agrees with the one in the SERVERLOOP program. Protocol is a 
          number between 5680 and 56FF hex (reserved for OPAL RPC).
          for this example:
          DEFINE OS9_SERVICE *_5680.ETHERNET

       on VME you set the environment variable for the client. By default the 
          varaible name is the PACKAGE name. On OS9 you MUST use UPPERCASE
          letters.
          in this example talking with UXOPCJ:
          SETENV  OS9_SERVICE 0@AA_00_04_00_15_58_5680.ETHERNET


 
  NOW
      START the SERVER on the VAX
      RUN the CLIENT on OS9
  
  
***************************************************
*  EXAMPLE 2:   client on VAX/VMS written in C    *
*               server on VME/OS9 written in C    * 
***************************************************

   -- the general procedure is as above
         1) write the server, client, and variable declaration files
         2) RPC the declaration file with correct options
         3) link the client modules on the VAX (for this application)
         4) fix the INCLUDES, and add the * in the server stub
         5) port the server routines, compile, and link with RPC files
         6) define the logical/environment variables(=addresses)
         7) run the application


   CLIENT program (vxcrna::disk$opal1:[raab.rpc._2]test_2.c
   --------------------------------------------------------

     #include <stdio.h>
     #include <rpcheader.h>
     	extern void open_test_2();
        extern rpc_long testfun_2();
     
     main()
     {
        int a,b;
     
        open_test_2();		/* connect us to the server */
     
        a = 1;
        b = 9;
        printf("\n A = %d   B = %d", a, b);
        printf("\n A + B =  %d", testfun_2(a,b));
     }


   RPC variable declaration file (vxcrna...[]test_2.c)
   --------------------------------------------------
  
      PACKAGE TEST_2 IS
              FUNCTION TESTFUN_2 (
                       P1 : IN RPC_LONG; P2 : IN RPC_LONG)  RETURN RPC_LONG;
      END TEST_2;
          

  SERVER routines (/m17/rpc/server/*.c)
  ------------------------------------

     #include <rpcheader.h>
     #include <stdio.h>
     #include <types.h>
     
         extern void attach_test_2();
         extern void rpc_init();
     
     main()
     {
        static rpc_name *service = "RPC_CLIENT_NAME                        ";
        rpc_status status;
       
        rpc_init();
        attach_test_2(); 
        
        rpc_loop_server(&status,service);
        rpc_report_error(&status);      
     }
     
     
     testfun_2(p1,p2)
     int     p1,p2;
     {
        return(p1 + p2);
     }
   


  -- RPC the declaration file
  -- compile and link the  client routines
  -- port the server to OS9, compile and link there
  -- define the addresses
        OS9:  SETENV RPC_CLIENT_NAME  AA_00_04_00_15_58_5680.ETHERNET
        VAX:  DEFINE TEST_2 0@02_60_86_00_04_4E_5680.ETHERNET     

  -- start the server
  -- run the client


DIAGNOSTIC INFORMATION

To obtain tracing information on OS9, you must 
        SETENV RPC_TRACE_FLAG TRUE
     this provides useful debugging information at times.
     On the VAX you use the command TRON after you have run the initial 
     command file.  

 

================================================================================
Note 12.1                          RPC for OS9                            1 of 3
VXCERN::RPC                                           9 lines  20-APR-1988 16:13
                         -< Release 1.1 for OS9 V2.2 >-
--------------------------------------------------------------------------------
    A release (1.1) of the RPC software for version 2.2 of OS9 now exists.
    The files are named as for release 1.0 (except for the release notes)
    and can be retrieved with the command
    
    $BACKUP VXCRNA::DISK$D1:[RPC.DISTRIBUTION_KIT]RPC_OS9011.A/SAV []
    
    See the release notes file for further details. The release contains
    also a few bug fixes. (Software by Johannes Raab/OPAL. If you have
    problems, mail VXCRNA::TIMBL)
================================================================================
Note 12.2                          RPC for OS9                            2 of 3
FNAL::BCBROWN "Bruce C. Brown MS316 X4404 FNAL"       8 lines   2-JAN-1990 21:07
                            -< What about OS-9000 >-
--------------------------------------------------------------------------------
    In the Sept 1989 issue of Computer Technology Review ( a
    system-integrator industry magazine) there is an article announcing
    that Microware has announced OS-9000 (as a follow-on to OS9, I think).
    
    Questions:  
    	1.  Will the CERN RPC's transparently work in OS-9000 (by some
    		fortunate chance?)
    	2.  Is there any interest/activity in making RPC's for OS-9000?
================================================================================
Note 12.3                          RPC for OS9                            3 of 3
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               9 lines   2-JAN-1990 21:37
                    -< Yes, it should when OS9000 arrives >-
--------------------------------------------------------------------------------
    In note Note 12.2, FNAL::BCBROWN "Bruce C. Brown MS316 X4404 FNAL" asks
    whether RPC will run over OS9000. (OS9000 is a rewrite of OS9 in C,
    with a certain amount of reorganisation while Microware are about it.)
    
    RPC will probably port directly to OS9000 immediately if you want to
    run over TCP.  That is because the code uses the socket library, which
    is the same as Berkley unix, os9 etc. If you want to run over raw
    ethernet then that would be more difficult, as you would need a
    compatible ethernet driver to the os9 one by T. Charity.

================================================================================
Note 13.0                       RPC under Ultrix                       2 replies
VXCERN::RPC                                          11 lines  20-APR-1988 16:28
--------------------------------------------------------------------------------
    The RPC compiler, 'rpcc' is now installed on the priam vax. The
    syntax of the rpcc command is as described in the RPC manual.
    (It is the same as the RPCC command under VAX/VMS, but with options
    introduced by '-' instead of by '/'.)
                                                                 
    The header file 'rpcheader.h' is in the normal search path for the
    C compiler.
    
    The 'rpcc' command generates stubs in C or Pascal: The command 'RPC'
    under VMS to produce stubs in object format does not have an equivalent
    under Ultrix. 
================================================================================
Note 13.1                       RPC under Ultrix                          1 of 2
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               2 lines  15-FEB-1989 08:49
                           -< Version 2.3 installed >-
--------------------------------------------------------------------------------
    rpcc version 2.3 is now installed on the priam ultrix vax,
    and the v2.3 rpcheader.h is under /usr/include.
================================================================================
Note 13.2                       RPC under Ultrix                          2 of 2
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"               3 lines  25-OCT-1989 21:05
                         -< RPC runs on Unix over TCP >-
--------------------------------------------------------------------------------
    There is a runtime system available for Unix, communicating using TCP
    with, for example, other unix systems, VMS or OS9. Mail me if you would
    like the files.

================================================================================
Note 14.0                       RPC on the IBM-PC                     No replies
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              14 lines  18-MAY-1988 15:43
--------------------------------------------------------------------------------
    Peter Lorenz (Delphi) has ported the RPC system onto the IBM-PC, using
    TurboPascal.  This includes both the RPC compiler and the run-time
    support.  The communications medium currently supported is ISO Tranport
    Protocol (TP4) running using the BICC ethernet card. Peter has had his
    PC calling routines on the VMS VAXes and also M6809 based systems in
    G64 crates.  Partly due to the slickness of TurboPascal, it seems very
    easy to use. You just run RPC the compiler, and put a "USES CLIxxxx"
    clause into your program to refer to the client stub. 
                                      
    I have not yet put together a VMS distribution kit, but the software
    is available on a floppy. Mail me (VXCERN::TIMBL) or Peter (VXCERN::LORENZ)
    if you're interested.
    
    Tim Berners-Lee

================================================================================
Note 15.0                    Improvements wish-list                    2 replies
VXCERN::RPC                                         155 lines  23-AUG-1988 18:51
--------------------------------------------------------------------------------
    This is a list (drawn up in March 88) of improvements which have
    been asked for.  Some of them have since been done - I have added
    comments in brackets where I have noticed anachronisms.
    
    Any futher request for improvements can be added as replies to this
    topic. 
    _________________________________________________________________________
            						  TBL DD/OC March 1988
	    
		Remote Procedure Call Wish List
		-------------------------------

A list of possibile improvements and updates to the RPC system
from DD/OC, for general comment, and for allocation of priority.

1.	Porting

1.1	Under Mac, PC

-	Port to turbo-pascal.  Started by Delphi summer student
	'87 Now partly completed and tested by Peter Lorentz, and must
	be incorporated with the rest of the RPC software. 
	(Delphi, Valet-Plus bridge) [Largely done now for RS232 and Ethernet
	by R. Bagnara]

1.2	Under Unix

-	Make runtime system, to enable Valet-Plus support
	software etc to run on priam. General release of Runtime library
	for Unix and C environments.

-	Convert documentation of compiler into 'man'
	form. 

1.3	Under VAX/VMS

-	Make runtime system into a shareable library.
-	Integrate DRB handling (for CHI) with support for other transport media.
-	Make VMS/INTSALable save sets (?)

1.4	Under OS9

-	Documentation and examples into RPC User Manual [done]
-	VMS-style release of files and documentation    [files done,
    	doc in CERNDOC]
-	Add RS232 communications ability?
-	[Add TP4 communications ability now TP4 exists under OS9?]

1.5	For the CHI

-	Transport over CATS to be integerated with the general M68k
	transport service. (Allow ethernet on CHI, and use with RS232).

2 Extra Features

2.1	V24 communications improvements

-	Complete these, including reception of RS232 messages asynchronously.
	(Valet, GPM)

2.2	User Binding Routine

-	The ability to specify a user function to bind a client
	to a specific server. 	(Wisla MPC)

2.3	Server

-	connection/Disconnection routines
-	The ability to specify routines to be called when clients
	connect and disconnect.(FASTBUS on CHI)

2.4	Master server Master server on every RPC
	node to allow server package numbers to be looked up at
	run-time. (UA2, etc)

2.3	Configuration Manager

	Configuration manager handles local name database, refers to
	remote configuration managers, and handles capabilities.
	(Delphi, etc) (Use RPC_ACE product written by Delphi for
	database?) 

2.4	Compiler upgrades

	These would extend the ease of use of RPC, and
	reduce the amount of "hand crafting" of stubs. 

-	Support for records

-	Compiler support for transport media which allow infinitely long
	direct transfers - eg CFI by directly calling transport service
	from stub. (CHI applicvations - L3 for example).

-	Support for arbitrary actual bounds to subarrays, including
	expressions, for arbitrary variable length arrays.

-	Support for back-call package in same definition file.

2.3	Compatibility

	In the long term, we must try to converge with other RPC systems.
	In the medium term, producing options for compatability with these
	systems could give us interworking with more systems, eg IBM.

	Four interesting systems are

	a.	VAX/RPC

	We have a field test tape for this.
	It will be installed on VXCERN in April.   [installed]
	It is limited to VAX/VMS at the moment, but is quite powerful,
	and very similar in style to our own RPC.
	I have documentation under non-disclosure,
	and notes from a 2 day course.

	b.	Apollo NCS

	This is an ostensibly public-domain system, with VMS support officially
	to come out some time, and operation over various media.
	OPAL interested.  Exists on site I think. [latest news suggests VMS
	and MSDOS versions exist. Need feasbility study]

	c.	Sun XDR.

	Sources, I am told, are on the priam VAX.
	A fairly longstanding RPC system, probably not optimal, but
	useful as it exists in various (especially Unix like) environments.

	d.	SPS Network Compiler

	We have not succeded in getting specifications for the protocol
	or message formats for this protocol, but it would be useful
	for experiments to be able to exchange data this way with
	the accelerators, without having two RPC systems on the same machine.

3	Maintenance

-	RPC manual - update and tidy SGML conversion, add diagrams. 	[done]
-	RPC Internals guide - update for latest version.
-	Test default bind to local server if it exists (for MoniCa especially)

3.1	 Under RMS68k

These were requests from Kevin Einsweiler. (UA2)

-	Prevent duplication of first call (by doing first call to master server)
	[done]
-	System lockup bug occurred during last run from time to time.
	(AEB would stop receiving packets - they would get as far as the
	Lance buffers but not to tasks on the ethernet receive queue.
	(Was ethfltr called?))
-	Response time is unpredictable under load. (Make timeout parameters
	accesible?)

                                                              
================================================================================
Note 15.1                    Improvements wish-list                       1 of 2
VXCERN::SPANG "Karsten Spang, CERN/EP/DELPHI"         6 lines  21-SEP-1988 14:37
                         -< Mailbox medium under VMS >-
--------------------------------------------------------------------------------
	CATS has not been extended to support the mailbox medium for commu-
	between processes on the same VAX, and it seems that it will 
	never be done by DELPHI. Still it would be nice to have RPC 
	support that medium, because it does require special privileges 
	to run, and because it is efficient. So, my wish is: Make a mail-
	box medium for RPC under VMS.
================================================================================
Note 15.2                    Improvements wish-list                       2 of 2
VXCERN::RPC                                          10 lines  28-OCT-1988 14:22
                      -< Exists, undocumented as yet... >-
--------------------------------------------------------------------------------
    The CATS which RPC uses on the VAX was produced originally by Delphi
    (I. Martinez) and DOES support mailbox communication. It's just
    lacking in documentation.  Angel Camacho (who replaces I. Martinez)
    will be at CERN mid November 1988 and is going to upgrade CATS in
    general, and attach the new CATS to RPC.  Hopefully, he will leave
    the capabilities of the mailbox system documented.
    
    I had not persued this because I had found that mailbox communication
    was in fact slower than DECNET, but I agree it might be useful in
    some cases for other reasons.  Your wish is noted!

================================================================================
Note 16.0     Avoiding SYSNAM for a multi-client server under VMS?     2 replies
VXCERN::SPANG "Karsten Spang, CERN/EP/DELPHI"        15 lines   8-SEP-1988 14:01
--------------------------------------------------------------------------------
I am going to develop some software using RPC on a general VAX/VMS 
machine. The offending thing is of course that I need SYSNAM privilege
to run a which must handle multiple clients.

My system manager
1) will not give me SYSNAM privilege
2) does not want to install my programs every time I make an update
3) is willing however to define a couple of network objects that I may
   use as I want.

Now my questions are: If the network object is already known, will a 
server then be able to work? How should I define RPC_CLIENT_NAME?
Is it possible to start the server before it receives a connect request?

   Karsten Spang
================================================================================
Note 16.1     Avoiding SYSNAM for a multi-client server under VMS?        1 of 2
VXCERN::SPANG "Karsten Spang, CERN/EP/DELPHI"        12 lines   9-SEP-1988 23:13
                    -< How is the MBX medium of CATS used? >-
--------------------------------------------------------------------------------
	Another way around the problem may be the use of mailboxes as the
	medium under CATS. Unfortunately it is not described in the 
	manual how to define the logical names. From the description of
	how CATS handles ethernet connections I guessed that they should
	be:
		0@SERV@MBX.CATS		for the client, and
		*SERV@MBX.CATS		for the server,
	but this turned out not to work. The program was a simple one-
	routine test that worked fine over DECnet with automatic server
	startup. The program was run with the GRPNAM privilege and
	LNM$TEMPORARY_MAILBOX was equal to LNM$GROUP, so there should be
	no problems creating the mailbox.
================================================================================
Note 16.2     Avoiding SYSNAM for a multi-client server under VMS?        2 of 2
VXCERN::TIMBL "Tim Berners-Lee CERN/DD"              36 lines  23-SEP-1988 16:33
                        -< No loopholes that I know of >-
--------------------------------------------------------------------------------
    It is stated fairly explicitly in the DECNET manual [Guide to
    networking on VAX/VMS, AA-Y512A-TE, Sep 84, page 8-44] that
    
    "A target task can accept multiple inbound connection requests
    only if it declares itself a known network task. [...] This
    system service requires SYSNAM privilege."
    
    I therfore conclude that nothing you can specify in the NCP database
    will allow it to become a named network task without SYSNAM.  This is
    rather a pity if the task is quite innocuous but just needs to declare
    its own existence.  However, it is quite right that SYSNAM is not
    dished out to test programs, as you can break the system with it. 
    
    What you could do is test the program until it looks good either with
    single clients (one at a time) or on a machine on which you can get
    SYSNAM. Then, when you release it, you will have to ask for the program
    to be installed with SYSNAM privilege.  To use service clients one at a
    time, you can
    
    	$ DEFINE RPC_CLIENT_NAME SYS$NET.DECNET
    
    If a second client arrives, then a second server task will be started,
    which may or may not be useful. In this way you can test it almost
    completely, and without relinking redefine it as *xxxxx.DECNET when you
    get SYSNAM. 
    
    [For details of the mailbox communication underlying CATS, you will
    have to see the DELPHI documentation.  I have not seen any myself,
    and so have not used or tested it.  I hear from the grapevine that
    MBX communication tends in fact to be slower than local DECNET,
    so I have not persued it].
                 
    That's all I can suggest - unless anyone has found a neat way round
    this problem.
               
    Tim Berners-Lee

================================================================================
Note 17.0             Apollo Network Computing System (NCS)           No replies
VXCERN::TIMBL "Tim Berners-Lee CERN/CN"              16 lines   4-MAY-1990 17:12
--------------------------------------------------------------------------------
    We have a beta-test version on Apollo NCS v1.5.1, the RPC system which Apollo
    and DEC have put forward to OSF as part of their "DECorum" offering for
    distributed computing.  This has some extended features over v1.1 which
    we were previously using.
    
    Apollo are keen for projects to be set up which they can quote. So far
    there has been some interest in NCS from L3 and Opal and SPS/LEP
    controls. If anyone else would be interested, then mail me.
    
    The NCS system consists of an RPC compiler ("nidl"), and a runtime
    system which runs on Apollos, Unix and VMS machines.  We have some
    documentation which you can copy -- it is also available in paperback.
    
    We also have a channel for bug reports and help -- an electronic mail
    address for Glen Crossman, of Apollo in Germany, who has offered to
    help us.

================================================================================
Note 18.0                     Netwise Inc: RPC Tool                   No replies
VXCERN::TIMBL "Tim Berners-Lee CERN/CN"               9 lines   4-MAY-1990 17:30
--------------------------------------------------------------------------------
    Netwise Inc, of Boulder, Colorado, are a software company providing an
    RPC system they call "RPC Tool". Being independent of hardware
    manufacturer, they sell it ported to as meny environments as they can.
    It currently runs on unix, VMS, MSDOS and OS2 over a number of
    protocols.
    
    I have some sales information, and we expect a visit by one of their
    technical team on 10-May-1990. Mail me if you are interested, or have
    specific questions about it.                     

================================================================================
Note 21.0                 Porting to other unix systems               No replies
VSOC10::TIM "Tim Berners-Lee CERN/CN"                20 lines  18-DEC-1990 11:07
--------------------------------------------------------------------------------

The development tree for unix systems and OS9 is on the priam:: node
(known on the internet as "cernvax"), in /userd/tbl/rpc at the
time of writing. The runtime library code is easy to port to a new unix system.
Under /userd/tbl/rpc/rts/c there are several subdirectories for different
machines, such as /unix (actually for ultrix), /next (the NeXT computer),
and /os9 (the OS9 operating system).

System-specific things are only in these directories. This includes
the makefile and all object files. To port, copy the
whole tree, then make a new subdirectory, a copy of /unix.
Delete all object files in the new directory, and recompile. Where your
system is different from ultrix, change the unix_specific.h file.
You may want to chaneg the Makefile too.

cernvax does not currently support anonymous ftp, but can be accessed over
decnet, or ftp if you have an account. Please mail me if you take a copy
of the code. Thanks.

	Tim BL
