Support for RPC on the M6809

## 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.