This document describes the Spectrum Access Server (SAS) protocol specification used to provide access to the distributed spectrum servers which form part of the NSF data acquisition system.

The protocol is used to implement the Spectrum Access procedures defined in EDOC062 together with the spectrum format defined in EDOC061.

It is intended that this protocol be available over a number of communications media and hence the relevant Communications Protocol specification document should be consulted for detail in this area.

This protocol is an application carried by the RPC protocol which is described in the Eurogam document Remote Procedure Call.

The general structure of the protocol is described in the Eurogam document RPC Application Programs.

History

Version 1.0 June 1991 - Initial version

Version 1.1 Sept 1991

Version 1.2 Aug 1992 - Allow authorisation with no password if client machine is listed in user's .rhosts.sas, /etc/hosts.sas or /etc/hosts.equiv.

Version 1.3 June 1998 (This version) - document converted to HTML format
Additions to handle both big endian and small endian processors.

Version 1.3 of the document corresponds to version 1 of the program protocol.

Throughout this document capability is an 8 byte (64 bit) opaque field generated by the server and used by the client as an access token.

Throughout this document the spectrum being accessed is identified by the string variable pathname. For on-line spectrum servers this is the name of the spectrum within the server. For off-line spectrum servers (ie disc-based spectra) this is either an absolute pathname identifying a disc file known to the spectrum server or is a pathname which is relative to the 'home' directory of the authenicated user issuing the request.

Program Specification

Basic Data Types

    typedef   enum   { FALSE = 0, TRUE = 1 } boolean;

    typedef   enum {
       OK = 0
       authentication_failure = 1
       already_in_use         = 2
       capability_invalid     = 3
       pathname_invalid       = 4
       parameter_invalid      = 5
       not_a_spectrum         = 6
       not_a_directory        = 7
       data_access_error      = 8
    } stat;

    typedef    string user<32>
    typedef    string password<32>
    typedef    string pathname<255>

    typedef    string timedate[20]

    typedef    unsigned map

    typedef    opaque capability[8]

    typedef    signed   base[8]
    typedef    unsigned range[8]
    typedef    unsigned size[8]

    typedef    unsigned  dimension
    typedef    unsigned  arraytype
    typedef    unsigned  arraylayout
    typedef    opaque    countvalue
    typedef    unsigned  stringtype
    typedef    unsigned  stringid

Actually countvalue is not opaque; the data type is determined by type.

    typedef    struct {
         arraylayout    layout;
         arraytype      type;
    } attrib;

Procedure Summary

0	null procedure	[go]
1	Authorise	[go]
2	Create Spectrum	[go]
3	Delete Spectrum	[go]
4	Look Up Spectrum	[go]
5	Read String	[go]
6	Write String	[go]
7	not used by SAS
8	Read Names	[go]
9	Read Spectrum	[go]
10	Write Spectrum	[go]
11	Change Array Options	[go]
12	UnAuthorise	[go]
13	Generate Error Report	[go]