       
                                        Ref:    DXS/CSTS/L1
                                        Date:   06-Dec-91
                                        Author: Paul Sanders
                                
                                
               CD-ROM Data Exchange Standard (DXS)
                  Client-Server Transfer Syntax
                           Version 1.0
                                
       
            Paul Sanders
            SilverPlatter Information Ltd.
            10 Barley Mow Passage
            Chiswick
            London W4 4PH
            England
       
            Tel: +44 (0) 81-995 8242
            Fax: +44 (0) 81-995 5159
       
            This document is available in Microsoft Word 5.5
            format from the above address.


































                                   1

                        Table of Contents
       
       .Begin Table C.

1.     Introduction                                        3
  1.1    Change History                                    3

2.     Overview                                            3

3.     Ground Rules                                        4

4.     Requests                                            5

5.     Responses                                           7

6.     Common Request and Response Types                   9
  6.1    'Error/Warning' Request                           9
  6.2    'Cancel request' Request                         11
  6.3    'Echo' Request/Response                          11
  6.4    'Set language' Request                           11
  6.5    'Display message' Request                        12

7.     Well-Known Identifiers                             12
       .End Table C.

































                                   2



1.     Introduction

       This document describes a general purpose protocol for
       communicating between a client and a server on a
       previously established reliable transport service
       connection.
       
       A working knowledge of the following related documents is
       assumed:
          - 'CD-ROM Data Exchange Standard Specification'
            (DXS/SPEC)
          - 'CD-ROM Data Exchange Standard Platform Dependent
            Implementation Details' (DXS/PLAT)
          - 'CD-ROM Data Exchange Standard Database Server Access
            Protocol' (DXS/DSAP)


1.1    Change History

       This is the first live version of this document.


2.     Overview

       The intention of this document is to describe a mechanism
       which provides some useful common elements and which can
       be readily extended to support the specific requirements
       of a particular type of server.
       
       The protocol described here is message orientated, with a
       distinction made between requests and responses.  By and
       large, a request is sent by the client to instigate some
       action at the server, and a subsequent response returns
       the results of that action.  The existence of an
       underlying transport service offering reliable, connection
       oriented delivery is assumed.
       
       Requests are categorised by request type; associated with
       each request type are:
          - a list of data items, identified by keywords, that
            the client can send to the server (in order to fully
            define the request)
          - a list of data items, again identified by keywords,
            that the server can return to the client (if so
            requested)
       
       The protocol offers the following benefits:
          - The protocol is readily implementable now, over any
            transport service offering reliable, connection
            oriented data delivery.





                                   3

          - The protocol is readily portable to utilise the OSI
            transport layer, but is not dependent on it, nor any
            of the higher layers in the OSI protocol stack.
          - For each request, the client sends to the server only
            those data items that it needs to.  This gives
            flexibility (because new data items can be defined
            for existing requests whilst remaining compatible
            with existing clients and servers) and reduces
            network traffic; it also keeps the number of request
            types down.
          - For each request, the client informs the server which
            data items to return in the response; again, this
            gives flexibility and reduces network traffic.
          - The response format allows the server to pack its
            responses into the minimum packet size.
          - A mechanism for adding vendor-unique extensions is
            included.
          - The protocol is small, focussed, and reasonably easy
            to implement.
          - A degree of human readability makes client-server
            implementations using this protocol easier to debug.
       
       We felt that none of the existing OSI protocols could
       deliver this combination of features.
       
       Interoperability is possible between any client and server
       using the same transport service.  It is possible for a
       server to support multiple transport protocols, or even to
       build gateways at the transport protocol level (e.g.
       between TCP and Novell's SPX, which would allow a Netware-
       based client to transparently access a TCP-based server).
       
       Note that this protocol can be implemented equally well on
       either a message or byte-stream oriented transport
       service.


3.     Ground Rules

       The following basic data types are defined:
            BYTE      a 1 byte (8 bit) unsigned value
            WORD      a 2 byte (16 bit) unsigned value
            DWORD     a 4 byte (32 bit) unsigned value
       
       All multi-byte integers are sent most significant byte
       first (Motorola 'big-endian' byte ordering), except where
       otherwise stated.  8 bit bytes are assumed.
       
       Bit 0 is defined as the least significant bit.
       
       In the interest of reasonable buffer sizes, a message has
       a maximum length of 1024 bytes (including the header).





                                   4

4.     Requests

       A client issues a request to a server in a message with
       the following format:
            WORD      value 0xABCD (helps identify start of msg)
            WORD      request length
            WORD      protocol type
            WORD      request type (bit 15 = 0)
            DWORD     request ID
            WORD      flags
                         - bit  0 = 1 if request incomplete
                         - bit 15 = 1 if message incomplete
            BYTE      request data [] (variable length)
       
       Request length is the total length of the request, in
       bytes.  The length of the request data is obtained by
       subtracting the number of bytes in the fixed-size request
       header (14).
       
       Protocol type allows each type of server to have its own
       set of request types.  Currently defined protocol types
       are listed below; additional protocol types will have to
       be centrally administered.
       
       Request type specifies the request being made.  Request
       types common to all protocols are defined below.  All
       other request type values are specific to each protocol
       type.  The most significant bit of the request type is
       always zero.
       
       Request ID is an optional ID, generated by the client,
       which the client can use to identify the response to the
       request, when it arrives.
       
       Flags are used as follows:
          - If a request is marked as 'request incomplete', the
            next message from the client must carry the same
            request ID and contain the next portion of the
            request data.  This is not a general facility - it is
            only used for those request types that explicitly
            allow it, since fragmented requests complicate life
            for the communicating parties.
          - The 'message incomplete' flag is used where the
            underlying transport service is unable to deliver a
            1024 byte message in a single packet.  If this is
            set, the subsequent packet(s) will contain the
            remainder of the message.
       
       Request data is of the form:
            keyword='value';keyword='value1','value2'; >info-list
       
       Where:
          - keywords must start with a letter and contain A-Z, 0-
            9 and underscore only



                                   5

          - keywords can appear in any order
          - vendor-unique keywords start with the vendor prefix,
            including the '$' symbol (e.g. SP$SPECIAL)
          - values containing any of the following characters
            must be placed in single quotes:
                 ; (semi-colon)
                 , (comma)
                 = (equals sign)
                 . (period)
                   (space)
            for a literal single quote, use two quotes in
            succession, as in the fourth example below
          - spaces outside quotes are ignored
          - when a request specifies a 'comma-delimited list',
            each separate value in the list should be enclosed in
            single quotes (if necessary), as in the third example
            below
       
       Examples:
            NAME=Mole; INITIAL=A; AGE='14 3/4'
            NAME='Pevsner,B'; INJURIES='HANDS;KNEES'
            COUNTRIES=RUSSIA, 'U.K.', 'U.S.A'
            SQUOTE=''An Apple a day keeps Adobe away''
            DQUOTE="IBM executives enjoy munching Apples"
       
       There is a list of valid keywords for each request type.
       
       To reduce network traffic, all keywords also have a two
       character abbreviated form, preceded by the vendor prefix
       if necessary.  Either form can be used.
       
       Info-list, if present, is a comma delimited list of data
       items to be returned in the response(s) to the request.
       Only the data items named will be returned.  It takes the
       form:
            >DATAITEM1,DATAITEM2...
       
       Data item names must start with a letter and contain A-Z,
       0-9 and underscore only.  Spaces around data item names
       are ignored.
       
       Examples:
            >NAME,ID,AGE,DATA
            > N_OCCS, N_DOCS
       
       There is a list of valid data items associated with each
       request type.
       
       To reduce network traffic, all item names also have a two
       character abbreviated form, preceded by the vendor prefix
       if necessary.






                                   6

5.     Responses

       A server issues a response to a request from a client in a
       message with the following format:
            WORD      value 0xABCD (to identify start of message)
            WORD      length of response data
            WORD      protocol type
            WORD      response type (bit 15 = 1)
            DWORD     request ID
            WORD      flags
                         - bit 0 = 1 if response incomplete,
                           record complete
                         - bit 1 = 1 if response incomplete,
                           record incomplete, info-list item
                           complete
                         - bit 2 = 1 if response incomplete,
                           record incomplete, info-list item
                           incomplete
                         - bit 3 = 1 if request complete
                         - bit 4 = 1 if more records available
                         - bit 15 = 1 if message incomplete
                           (divided into more than one packet by
                           the transport service)
            WORD      number of records in response
            BYTE      response data [] (variable length)
       
       Response length is the total length of the response, in
       bytes.  The length of the response data is obtained by
       subtracting the number of bytes in the fixed-size response
       header (16).
       
       Protocol type is the same as in the corresponding request.
       
       Response type is the same as the corresponding request,
       with the most significant bit set.
       
       Request ID is the ID of the corresponding request.
       
       Number of records in response - data sufficient to fill
       one complete set of items in the request's info-list
       constitutes one record.
       
       Flags are used as follows:
       
       'Response incomplete, record complete' is returned where
       the response consists of more than one record, and there
       are more records than will fit in a single 1024 byte
       message.  This is permitted for all requests types where
       the response can return more than one record.
       
       'Response incomplete, record incomplete, info-list item
       complete' is returned where the one record in the response
       is too long to fit in a single 1024 byte message.  The
       next message will contain the remaining info-list item(s)



                                   7

       in the record.  This is not a general facility - it is
       only used for those request types that explicitly allow
       it, since it complicates life for the communicating
       parties.
       
       'Response incomplete, record incomplete, info-list item
       incomplete' is returned where one info-list item in the
       response is too long to fit in a single message.  The next
       message will contain the remainder of the current info-
       list item, and any remaining info-list items in the
       record.  This is not a general facility - it is only used
       for those request types that explicitly allow it, since it
       complicates life for the communicating parties.
       
       'Response complete' is returned in the last (or only)
       response.  At this point, the server 'forgets' the request
       ID.  'More records available' will be set if there are
       more records available matching the original request.  The
       client must issue another request to obtain these.
       
       The 'message incomplete' flag is used where the underlying
       transport service is unable to deliver a 1024 byte message
       in a single packet.  If this is set, the following
       packet(s) will contain the remainder of the message.
       
       Response data contains zero or more records, each record
       containing the items specified in the request's info-list
       in the sequence that they appear in the request.
       
       Each record is both preceded and followed by the record
       length (a two byte integer, MS byte first); the record
       length excludes these four bytes.
       
       Each item is preceded by a one byte tag that describes the
       format of the data.  These tags take the following values:
       
            0..239    - the integer value of the tag
            240       - 1 byte integer
            241       - 2 byte integer, MS byte first
            242       - 4 byte integer, MS byte first
            243       - C string (nul terminated)
            244       - Pascal string (length in following byte,
                        followed by that many bytes of binary
                        data)
            245       - binary data (length in following two
                        bytes, MS byte first, followed by that
                        many bytes of binary data)
            246..252  - reserved
            253       - missing value (no data bytes follow)
            254       - empty value (no data bytes follow)
            255       - reserved
            
       Except where stated, a request will always elicit a
       response.  If, for a particular request type, no response



                                   8

       is specified, the requester should expect a response with
       the 'response complete' flag set and the number of records
       set to zero.


6.     Common Request and Response Types

       Request types 0x01 - 0xFF (and response types 0x8001 -
       0x80FF) are reserved for functions common to all
       protocols.  Those currently defined are listed below.
       
       Error codes 0x01 - 0xFF are also reserved for common
       errors - see below.
       
       In the message formats below, the two character keyword
       and item name abbreviations precede the full name,
       separated by a space.


6.1    'Error/Warning' Request

       This request is sent from the server to the client when a
       request from the client generates a warning or terminates
       with an error; no response is expected from the client.
       In the case of an error, no (further) responses will be
       generated by the server; only the first (or most serious)
       error is reported.  In the case of a warning, the normal
       response(s) to the request will be returned.
       
       Protocol Type       the protocol type of the request which
                           generated the condition (or
                           NWP_COMMON, if unsolicited warning
                           message)
       Request Type        either CR_ERROR or CR_WARNING
       Request ID          the ID of the request which generated
                           the condition (or 0, if unsolicited
                           message)
       Keywords and values:
            EC ERRORCODE   numeric warning or error code
            UM USERMSG     end-user error message string
            DM DEVMSG      developer error message string
       
       Warning codes, error codes and error message strings are
       defined separately for each protocol type.
       
       The following error codes are common to all protocols:
            EC_BADPROT     invalid protocol type specified
            EC_BADREQ      invalid request type specified
            EC_BADSEQ      a continuation of an incomplete
                           request was expected but something
                           else was received
            EC_BUSY        the server is too busy to accept the
                           request - try again later




                                   9

            EC_MISSINGKW   missing required keyword(s) in a
                           request; the keyword(s) in question
                           are returned in the developer error
                           message string in the form:
                                NAME;INITIAL
            EC_NULLVALUE   missing required value(s) in a
                           request; the keywords(s) in question
                           are returned in the developer error
                           message string in the form:
                                NAME;INITIAL
            EC_BADVALUE    invalid value(s) in a request; the
                           offending keyword(s) and value(s) are
                           returned in the developer error
                           message string in the form:
                                NUMBER='123X'
            EC_CANCELLED   request cancelled by the client
            EC_IOERR       I/O error at the server
            EC_SYSERR      system error at the server
            EC_RESOURCES   shortage of resources in the server
            EC_SECURITY    access denied (e.g. not logged in)
            EC_BADKEY      non-existent key specified in a
                           request; the offending keyword(s) and
                           value(s) are returned in the developer
                           error message string in the form:
                                TAG='QWERTY'
            EC_MULTKEY     some requests accept more than one
                           keyword specifying a key; only one
                           such keyword may be supplied in the
                           request
            EC_EXPIRED     a previously opened resource has
                           become unavailable for some reason;
                           the keyword and value of the resource
                           in question is returned in the
                           developer error message - the resource
                           is generally identified by a hex-ASCII
                           handle, e.g.:
                                DBHANDLE='1379FD22'
                           the reason is in the end-user error
                           message.  This request is only sent
                           once - further attempts to use the
                           handle will return EC_BADKEY
            EC_LOGGEDOUT   the server has logged the client out
                           for some reason; the reason is in the
                           end-user error message.  This request
                           is only sent once - further attempts
                           to use the connection will return
                           EC_SECURITY.  The server may also
                           close a connection unilaterally.
       
       
       The following warning codes are common to all protocols
            WC_BADKW       a request contained one or more
                           invalid keywords which have been
                           ignored; the keyword(s) in question



                                   10

                           are returned in the developer error
                           message string in the form:
                                INITAIL;FORNAME
            WC_BADITEM     a request contained one or more
                           invalid data item names in the info-
                           list ('missing value' tags are
                           returned in the response data); the
                           item name(s) in question are returned
                           in the developer error message string
                           in the form:
                                NAME,AGE


6.2    'Cancel request' Request

       This request is sent from the client to the server to
       cancel a previous issued request.  No response is issued
       by the server to the 'cancel request' request.  A 'request
       cancelled' error request is sent to the client for the
       request cancelled.
       
       Protocol Type       the protocol type of the request to
                           cancel
       Request Type        CR_CANCEL
       Request ID          the ID of the request to cancel


6.3    'Echo' Request/Response

       When a server receives this request, it returns an echo
       response.  It is used to check that a connection is still
       functioning, or to time round-trip delays.
       
       Protocol Type       any
       Request Type        CR_ECHO
       Request ID          as required
       Keywords and values:
            DATA           data to be echoed
       Info-list (1 record returned in response):
            DATA           data echoed


6.4    'Set language' Request

       This request specifies the language in which the server
       returns error messages to the client on this connection.
       Keywords and inf-list items are unaffected.
       
       Protocol Type       any
       Request Type        CR_LANGUAGE
       Request ID          as required
       Keywords and values:





                                   11

            LANGUAGE       EN = English, GE = German, FR =
                           French, IT = Italian, ES = Spanish;
                           others to be defined


6.5    'Display message' Request

       This request is sent from the server to the client to
       request the workstation to display a message to the end-
       user.  There is no response to this request.
       
       Protocol Type       any
       Request Type        CR_SHOWMSG
       Request ID          as required
       Keywords and values:
            MESSAGE        the text of the message


7.     Well-Known Identifiers

       Protocol types:
         1 - NWP_COMMON    dummy protocol
         2 - NWP_DIRSRVR   reserved (for directory server
                           protocol)
         3 - NWP_DBSRVR    database server access protocol
         0, 4..255         reserved
       
       Request types common to all protocols:
         1 - CR_ERROR      'error' request
         2 - CR_WARNING    'warning' request
         3 - CR_CANCEL     'cancel request' request
         4 - CR_ECHO       'echo' request
         5 - CR_LANGUAGE   'set language' request
         6 - CR_SHOWMSG    'display message' request
         0, 7..255         reserved
       
       Error codes common to all protocols:
         1 - EC_BADPROT    invalid protocol type specified
         2 - EC_BADREQ     invalid request type specified
         3 - EC_BADSEQ     invalid sequence of requests
         4 - EC_MISSINGKW  missing required keyword(s)
         5 - EC_NULLVALUE  missing required value(s)
         6 - EC_BADVALUE   invalid value(s) specified
         7 - EC_CANCELLED  request cancelled by the client
         8 - EC_IOERR      I/O error at the server
         9 - EC_SYSERR     system error at the server
         10- EC_RESOURCES  shortage of resources in the server
         11- EC_SECURITY   access denied
         12- EC_BADKEY     non-existent key specified
         13- EC_MULTKEY    two or more keys specified
         14- EC_EXPIRED    resource has expired
         15- EC_LOGGEDOUT  connection has been logged out
         0, 16..255        reserved
       



                                   12

       Warning codes common to all protocols:
         1 - WC_BADKW      invalid keyword(s)
         2 - WC_BADITEM    invalid data item name(s)
         0, 3..255         reserved
       
       
       
                            oooOOOooo

















































                                   13
