M6809 Run Time Support
As operating system and langauge support on the M6809 is not so complete
as on 32 bit processors, a little more work has to be done by the
user. The code which must be put in the client and server programs
is discussed below. The run&hyphen.time system on the M6809 was written
for the FLEX operating system running on the G64 system. Hence the
supported transport media are for the G64 system. However, apart from
the configuration manager, which uses the file system to read in the
configuration file (see below), the system should work under other
operating systems. The stubs produced by the RPC compiler (with the
/xM6809 option) are for the Omegasoft Pascal compiler, which is available
for both the FLEX and OS9 operating systems.
Before the RPC system can be used, the procedure RPC_Init must be
called. Apart from initialising the RPC system, RPC_Init will read
in the configuration file from disk ( 2.CM.DAT, or if not found, 0.CM.DAT,
otherwise no configuration file is used). The configuration file contains
a list of equivalences for RPC addresses and address fields, that
is intended as a substitute for the VMS logical name system. It is
free&hyphen.format: name followed by equivalence, separated by one
or more spaces. Comments are preceded by an exclamation mark (!).
If an address or the equivalence of an address (translation is repeated
until there is no equivalence available) is of the form ASK"prompt"[default]
(eg. ASK"Node"[VXDEOP] ), then the user is prompted for the equivalence.
If RETURN is pressed, then the default is used (specifying a default
is optional). This mechanism is limited by the 40 character maximium
size of the address.
Example :
! Example of a configuration file: CM.DAT
! Name Equivalence
! ==== ===========
vxdeop AA000400DD58
vxcrna AA0004002F58
filer_client_name *FILER@IEEE.CATS
! The following two names cause the user to be prompted for the remote
! node name, while supplying the rest of the RPC address.
filer_server_name 0@FILER@NODE.IEEE.CATS
node ASK"Node"[VXDEOP]
Client program
For each package that is to be accessed, an integer (16 bit) variable
h_xxx (where xxx is the package name) must be declared in the MAIN
program as ENTRY. This is the handle. Before the package can be used,
RPC_Open (status, h_xxx, name)
must be called. Status is of type RPC_status, h_xxx is the handle,
and name is of type RPC_name and must be equated to a 40 character
long string or character array (padded on the right with spaces) which
is the server address. The server address and the fields within it
are translated (iteratively) as described above. Before exiting the
program a call to
RPC_Close(status, handle);
must be made. This is particularly important if the connection is
to ethernet, since even if the program exits, the ethernet card will
keep the connection open. In any program modules that need to call
RPC run&hyphen.time routines (such as RPC_Init or RPC_Open), it is
necessary to include RPC_const, RPC_types, and RPC_proc in the constant,
type, and procedure declaration parts of the program respectively.
These files are accessable, either as input (via *INCLUDE) to the
INCLUDE preprocessor on the VAX under these logical names (ie. RPC_const,
etc.), or as Pacsal include files on the G64. In the latter case (often
the more convenient) they have FLEX filenames RPCCONST.INC, RPCTYPES.INC,
and RPCPROC.INC respectivly. In addition, unlike on other systems,
it is necessary to include the file rpc$var (or, on the G64: RPCVAR.INC
) in the variable declaration section of the main program. This will
declare as ENTRY the global variables required by the RPC run&hyphen.time
system (this is necessary because of a bug in the Omegasoft Pascal
compiler that fails to allocate space on the stack for global variables
in modules that are not also declared in the main program). You must
compile and assemble the client stub and include it as one of the
"Additional files to load" when you link. The RPC library (RPCLIB.RO)
must be included as one of the "Additional library files" .
Example using package name FILER:
PROGRAM FILER (input, output); { Example client program on M6809 }
CONST
{$iRPCconst.inc Include RPC constant definitions}
TYPE
VAR
{$iRPCvar.INC Include RPC global variables}
h_filer: integer entry; { Handle onto server }
status: RPC_status;
address: RPC_name; { Server address }
{$iRPCproc.INC Include RPC procedure declarations}
BEGIN
RPC_Init; { Initialise RPC system }
{ Open a connection to the server. We use an address that we hope will be
translated by the configuration manager. See the example configuration file
above for a possible translation for filer_client_name. }
address:= 'filer_client_name ';
RPC_Open (status, h_filer, address); { open connection to server }
RPC_Report_Error (status);
{Instead of inserting the main program in here, we put in a call to a
procedure MAIN (defined in this file). This allows us to separate the
calls to the RPC run-time system from the rest of the program.
{
main;
RPC_Close (status, h_filer); { close connection to server }
RPC_Report_Error (status);
END.
Server program
The procedure attach_xxx is not defined on the M6809. Thus you must
call RPC_Attach_Stub (status, integer(addr(r_xxx)), service,
prog_no) where r_xxx (with xxx being the package name) is declared
INTEGER PCR and service is of type RPC_name and contains the space&hyphen.padded
package name, and prog_no is an integer (16&hyphen.bit). As for the
client program, the server main program must include the file RPCVAR.INC
in the VAR section. Any modules that use RPC run&hyphen.time routines
(eg. RPC_Loop_Server) must also include RPCCONST.INC, RPCTYPES.INC,
and RPCPROC.INC. You must compile and assemble your server procedures
and the server stub, both of which must be included as "Additional
files to load" when you link. The RPC library (RPCLIB.RO) must be
included as one of the "Additional library files". Example using package
name FILER :
PROGRAM MAIN (input, output); { Example server program on M6809 }
CONST
{$iRPCconst.inc Include RPC constant definitions}
TYPE
{$iRPCtypes.inc Include RPC type declarations}
VAR
{$iRPCvar.inc Include RPC global variables}
r_filer: integer pcr; { Server stub address }
status: RPC_status;
package: RPC_name; { package name }
address: RPC_name; { Address of client }
prog_no: integer; { Returned package number }
{$iRPCproc.inc Include RPC procedure declarations}
BEGIN
RPC_Init; { Initialise RPC system }
package:= 'filer ';
RPC_Attach_Stub (status, integer(addr(r_filer)), package, prog_no);
RPC_Report_Error (status);
address:= 'filer_server_name ';
RPC_Loop_Server (status, address); { Service RPC requests }
RPC_Report_Error (status);
END.
Example: VAX-G64 over ethernet, ISO TP4 protocol
The following example shows the commands needed to build a RPC application.
Suppose we have a program called MYPROG.FOR written in FORTRAN and
running on a VAX under VMS. This needs to call procedures in a module
called FILER.TXT written in Omegasoft Pascal and running on the G64
running the FLEX operating system. The interface between the two is
described in RPCL in the file FILER.RPC. First of all we compile the
main program using the VAX/FORTRAN compiler, generating the file MYPROG.OBJ:
$ FORTRAN MYPROG
We then generate the stub code for each system using the RPC Compiler:
$ RPC FILER.RPC /CVAXVMS /SM6809
Now the RPCC will produce (if no errors are found) the files:
CLIFILER.OBJ The client stub for VAX/VMS
SERFILER.PAS The server stub: Omegasoft Pascal
We can then link together the VAX image:
$ LINK MYPROG, CLIFILER, rpc_lib/opt
We now have an executable file, MYPROG.EXE, which, when run, will
call the remote version of FILER. To create the executable file on
the G64, the file SERFILER.PAS must then be downloaded to the G64.
Note that the default filetype for source files under FLEX is .TXT
so when the file is downloaded, the output filespec should be specified
as SERFILER.TXT (also filename must not be more than 8 characters
long). The server stub must then be compiled and assembled:
+++PASCAL O
+++RA SERFILER.RO O
The server routines (that we wrote) in FILER.TXT must also be compiled
and assembled:
+++PASCAL O
+++RA FILER.RO O
Finally these must both be linked in with a main program (say, MAIN.TXT
) that will simply initialise the RPC system and call a routine like
RPC_Loop_Server (which simply services remote procedure calls forever).
An example main server program is given above. The main program can
be compiled and linked with the chain file produced by the LC command:
+++LC "MAIN" F
Linkage Creator Version 2.11
Copyright 1982 by Omegasoft
Auto setup ? Y Let LC decide where to put the stack
System stack size : 400 (in hex) Better to overestimate!
Starting load location : 0 The start of the program in hex
Library drive number : 0 Drive on which RL.RO can be found
Additional files to load : SERFILER Sever stub
Additional files to load : FILER Server routines
Additional library files : RPCLIB G64 RPC library
Load options : Options for the LL command line
Map options : Use F for a full map listing
Additional command : FLEX command to follow Link step.
The command CHAIN MAIN will execute the chain file and produce the
executable file 2.MAIN.BIN, which may be executed by the command 2.MAIN.BIN
. Remember that the file CM.DAT should be present on either disk 2
or 0, so that the definitions for filer_server_name and filer_client_name
(used in the client and server main programs respectively) are present.
RS232 serial line
An asynchronous V24 For readers outside Europe, CCITT recomendation
V24 is the European equivalent of the RS232&hyphen.C standard. (RS232&hyphen.C)
line may be used for connecting two devices. The G64 system has two
types of RS232 chip, the SCN2661 (the older type - used on the "asynchrone"
board) and the SCN2681 (supplied with the new paged-RAM CPU card)
which provides two asynchronous channels. The format of is similar
for the two chips. The is V24. The gives the four&hyphen.digit hexadecimal
address of the memory&hyphen.mapped RS232 controller preceded by a
"$". For the SCN2681, this is followed by "_A" or "_B" depending which
of the two channels of the DUART is to be used. The may have a suffix
giving the baud rate. This defaults to 9600 baud. Examples :
$E020_B.4800.V24 Second terminal line on CPU board
run at 4800 baud.
$E000.V24 First chip on the Dual Asynchrone board.
The implimentation of V24 communications for other systems allow both
7- and 8-bit communications. Only 8-bit communications is supported
on the G64, and consequently those systems that the G64 communicates
with via RS232 should also be configured to use 8-bit.
OSI Transport Service over ethernet
For Ethernet/Cheapernet communication on the G64, the cheapernet interface
card (produced by CERN/DD) is required on the G64 crate. ISO class
4 Transport Protocol ("TP4") is used. If communicating with the VAX,
the VOTS package is required on the VAX. (The software uses a CATS
CATS is a standard calling sequence for a transport service. Implementations
existing include those running over IEEE 802.3 (Ethernet/Cheapernet)
on the VAX/VMS and G64; and DECNET, Mailbox, and X.25 protocols on
the VAX, and over the CERN Host Interface. library to access the communications
service). The is CATS. The has a suffix to indicate which medium
CATS is to use. Currently only IEEE is supported on the G64 (IEEE,
DECNET, X25, and MBX are supported on the VAX). For the client,
is of the form @ .IEEE where the (transport suffix) identifies
the process that will run the server - it should be the same as the
tsuf specified by the server; and gives the physical address of the
machine running the server. The may optionally be preceded by a "#",
which causes the client to make a new transport connection for each
RPC call rather than to leave it open after the RPC_Open and only
close it when RPC_close is called. The "short&hyphen.connect" client
is useful when either the client or server can only have limited number
of connections open. For the server, is of the form * @IEEE
where the identifies the current process to the network system. On
the G64 - not a multi&hyphen.tasking system - only one may be used
at a time. Examples : The following examples give two possible addresses
for the client and the corresponding address for the server.
0@MYSERVER@AA000400DD58.IEEE.CATS Normal client.
0@#MYSERVER@AA-00-04-00-DD-58 Short-connect client.
*MYSERVER@ieee.cats Server.
On the G64, .IEEE and .CATS are default and may be omitted.
Debugging tools
If the RPCLIB.RO library was compiled with tracing messages included,
then rpc_trace_flag is translated using the configuration file by
RPC_Init. If it translates to Y, then tracing messages are displayed
on each call. If ASK"Enable Tracing?"[Y] is included in the configuration
file, then the user will be prompted at run&hyphen.time. Tracing
may be turned on or off from within the program by setting rpc_trace_flag
(a global variable defined in rpc$var) to false. The tracing output
goes to the output stream errlog (a global text file also defined
in rpc$var) which is setup by RPC_Init to be routed to the terminal
output stream. If the RPC run&hyphen.time system has been generated
with tracing disabled, then no tracing output can be obtained.
Further comments
- Since the heap is used by the RPC run&hyphen.time system, it is important
that Omegasoft Pascal's mark and release routines do not come on either
side of a call to the RPC run&hyphen.time system. ie. mark(i); ...
RPC_open(); ... release(i); is a bad move .
- Currently there is no support for asynchronous calls on the M6809.
Consequently RPC_Start_Server, RPC_Queue_Server, and RPC_Service are
not defined. RPC_Accept with a timeout of zero is a useful mechanism
for polling for an RPC request while carrying out other tasks.
- In order to save memory space, versions of the M6809 RPC library can
be created without support for all the transport media, or for debugging
messages.