XEROX COURIERSERVE 2 4 1 COURIERSERVE 1 4 By: Christopher Lane (Lane@Sumex-aim.ARPA) INTRODUCTION COURIERSERVE implements a Courier Server process for Interlisp-D allowing other clients to make Courier calls into the workstation. The server supports both multiple Courier stream connections as well as Expedited (single packet) and Broadcast calls. STARTING A COURIER SERVER The Courier server can be started by evaluating: (COURIER.START.SERVER) [Function] Once the server is running, it can be invoked by a remote host client using (COURIER.OPEN HOSTNAME) for a Courier stream connection or by using COURIER.EXPEDITED.CALL or COURIER.BROADCAST.CALL for Expedited calls. The functions for making Courier client calls from Interlisp-D are documented in the Interlisp manual. DEFINING A COURIER SERVER FUNCTION Defining a Courier server program is identical to defining a Courier client program except for the extra field IMPLEMENTEDBY in each procedure in the PROCEDURES section of the Courier program definition: PROCEDURES ((LAYOUT 0 (GRAPHNODES ROOTIDS FORMAT FONT MOTHERD PERSONALD FAMILYD) RETURNS (GRAPH) REPORTS (LAYOUT.ERROR) IMPLEMENTEDBY GRAPH.REMOTELAYOUT)) The order of the RETURNS, REPORTS and IMPLEMENTEDBY fields is significant and should be maintained. The function named in the IMPLEMENTEDBY field is invoked when a Courier call to the procedure is made. This will be refered to as the "server function" . The server function is applied to the Courier stream, the Courier program, the Courier procedure followed by the arguments named in the Courier definition. The argument for GRAPH.REMOTELAYOUT would be (COURIERSTREAM PROGRAM PROCEDURE GRAPHNODES ROOTIDS FORMAT ...). Note that the COURIERSTREAM, PROGRAM and PROCEDURE arguments are not necessarily used, they are made available for implementing special kinds of servers. RETURNING VALUES FROM A COURIER PROGRAM Results or errors can be returned by a Courier server function by one of two different methods. In the usual, simple case, the function can return as its result a list starting with one of RETURN, ABORT or REJECT followed by the appropriate values. For the RETURN result, the tail of the list should be the results as defined in the Courier procedure defintion, eg. (RETURN 23 "John"). For the ABORT result, the tail of the list should contain the reason for the abnormal termination (as defined in the Courier program), followed by any error arguments, eg. (ABORT NAME.NOT.FOUND "John"). For the REJECT result, the tail of the list should contain the rejection error as defined in the Courier standard . The only rejection that should occur inside a server function should be UNSPECIFIED if the program needs to reject for any reason. The other rejection types are handled by the Courier server. Alternatively, the server function can return results directly to the Courier stream and return NIL as its result. To return results directly to the Courier stream use: (COURIER.RETURN COURIERSTREAM PROGRAM PROCEDURE RESULTLST) [Function] (COURIER.ABORT COURIERSTREAM PROGRAM ERROR RESULTLST) [Function] (COURIER.REJECT COURIERSTREAM ERROR RESULTLST) [Function] EXPEDITED AND BROADCAST COURIER CALLS The Courier server allows expedited and broadcast Courier calls. The only difference the server function would see if invoked due to an expedited call is that the Courier stream it is handed is actually a record containing an XIP packet and a socket. If the server function does not use the Courier stream directly, then this difference is invisible. If the server function actually needs a Courier stream to operate (such as a CHAT server), then it should probably include an USE.COURIER abort error in its definition. If the server function needs a Courier stream due to Bulk Data arguments, this will be trapped in the Courier server itself, which will reject appropriatly and not invoke the server function. USING BULK DATA IN A SERVER FUNCTION If a server function takes a Bulk Data argument (either BULK.DATA.SINK or BULK.DATA.SOURCE), it is handed an open Bulk Data Stream as that argument when called. If the server function returns a result by returning one of the RETURN or ABORT forms as its result, the Bulk Data Stream will be closed automatically. If the server function returns results directly to the Courier Stream using COURIER.RETURN or COURIER.ABORT, then the server function must first close the Bulk Data Stream using: (CLOSE.BULK.DATA STREAM ABORTFLG) [Function] The CLOSEF function currently does not work on the Bulk Data Stream argument and using it will hang the Courier connection. Only the Immediate Bulk Data transfer type is handled. NULL, ACTIVE or PASSIVE Bulk Data transfer types will cause a Courier rejection of type UNSPECIFIED. Both of these limitations are hopefully temporary. SIMPLE SERVER FUNCTION DEFINITION The following is a Courier definition for a simple evaluation server, the two functions EVAL.REMOTE and APPLY.REMOTE are the only functions that would have to be defined to make the server run. ((1105 0) TYPES ((SEXPR STRING) (FN STRING) (ARGS (SEQUENCE SEXPR)) (ERRORN (RECORD (ERROR.NUMBER CARDINAL) (ERROR.MESSAGE SEXPR)))) PROCEDURES ((EVAL 0 (SEXPR) RETURNS (SEXPR) REPORTS (REMOTE.EVAL.ERROR REMOTE.READ.ERROR) IMPLEMENTEDBY EVAL.REMOTE) (APPLY 1 (FN ARGS) RETURNS (SEXPR) REPORTS (REMOTE.APPLY.ERROR REMOTE.READ.ERROR) IMPLEMENTEDBY APPLY.REMOTE)) ERRORS ((REMOTE.EVAL.ERROR 0 (ERRORN)) (REMOTE.APPLY.ERROR 1 (ERRORN)) (REMOTE.READ.ERROR 2 (ERRORN)))) RELATED FILES The files COURIERDEFS.DCOM, COURIEREVALSERVE.DCOM, REMOTEGRAPHER.DCOM, REMOTEPSW.DCOM and COURIERIMAGESTREAM.DCOM define Courier servers and/or Courier type definitions. (LIST ((PAGE NIL (FOLIOINFO (ARABIC) STARTINGPAGE# 1) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM) FORMATINFO (ARABIC)) (174 36 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))))) ((((1 (8( (8D PAGEHEADING RUNNINGHEAD TERMINAL D6(TEXTFONT 5 (CLASSIC 12) (TIMESROMAN 10) (CLASSIC 10)) MODERN MODERNTERMINAL  HELVETICA MODERN MODERN MODERN MODERNMODERN LOGO     HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN   HRULE.GETFNMODERN   HRULE.GETFNMODERN  ,  2 ?" G!g'8)  %    &am$  N!  00 !#" z