EDOC097

EUROGAM DATA ACQUISITION SYSTEM

Eurogam Tape Server

Edition 2.0 Aug 1995

Nuclear Physics Support Group Central Laboratory of the Research Councils Daresbury Laboratory

Introduction

This document describes the Eurogam Tape Server (EGTS) protocol specification used by the Eurogam data acquisition system.

It is an extension of a previous document (EDOC020) which describes the Network Tape System (NTS); a general purpose tape access method. This document describes only the changes and extensions required to NTS for the EGTS environment and hence the document EDOC020 should be read in combination with this document.

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

Edition 1.0 Oct 1991 - first entry in Eurogam document server

Edition 1.1 May 1992 - updated following implementation

Edition 1.2 July 1992 - add data rate information to state reply.

Edition 2.0 January 1995 - enhanced associate command (procedure 28/29)

Operation

Use

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.

Program Specification

RPC Information The EGTS service uses only the Null authentication EGTS is supported on the UDP/IP transport only EGTS is RPC Program 28000205 This is Version 4 of the protocol EGTS uses UDP port number 10205

Procedures defined by NTS but NOT used by EGTS procedure 1. Allocate Device - use EGTS procedure 23

Procedure 24. Claim EGTS

There are no procedure specific parameters.

Requests access to the EG Tape Server resource.

RESPONSE - success

success=0 capability

The response returns a 8 byte (64 bit) capability which is an opaque field generated by the server and used by the client as an access token in subsequent procedure requests to the EGTS. The EGTS will currently be in the halted state.

RESPONSE - failure procedure status

Procedure status is a 4 byte field which is non zero and indicates the cause of the failure.

Procedure status= 4  EGTS already claimed

Procedure 25. Free EGTS

REQUEST

capability Releases the EG Tape Server resource.

The current state of the EGTS must be halted otherwise the request will fail.

RESPONSE procedure status

Procedure status is a 4 byte field which indicates the result of the request.

Procedure status= 0  success
8  capability is invalid
13  EGTS is in wrong state

Procedure 26. Set EGTS State

REQUEST

capability state state = 1 requests that the EG tape Server change to the halted state. state = 2 requests that the EG Tape Server change to the going state. state = 3 requests that the EG tape Server change to the test state.

The transition from halted to going will fail if any EG data stream is associated with a tape stream which is not in the dev open state. While in the going state the close file procedure is not permitted on any tape stream which is associated with a EG data stream. In the test state all data streams are enabled and will receive data. Data flow is controlled and checked normally but the data is discarded without being written to any device. The transition from halted to test does not require the EG data streams to have any current association and is always permitted as long as the current state is halted RESPONSE

procedure status

Procedure status is a 4 byte field which indicates the result of the request.

Procedure status= 0  success
7  a stream is in wrong state
8  capability is invalid

Procedure 27. Inquire EGTS State

REQUEST

capability

RESPONSE - success

success = 0 state

state = 1 indicates that the EG Tape Server is currently in the halted state, state = 2 indicates that it is currently in the going state and state = 3 indicates that it is currently in the test state.

RESPONSE - failure procedure status

Procedure status is a 4 byte field which is non zero and indicates the cause of the failure.

Procedure status= 8  capability is invalid

Procedure 28. Associate EG Stream

REQUEST

EG stream

capability

mode = 2 valid = true list length

list of client identifiers

:

valid=false Connects a Eurogam data stream to one or more lists of tape devices (data duplication). Each list itself is a list of one or more tape devices (data striping). Mode = 2 indicates the duplication+striping option implemented in version 4 (and later) of the program protocol.

Data received for the Eurogam data stream identified by EG stream are associated with all tape streams identified by the following lists of client identifiers. Each list of client identifiers receives a copy of the data for this EG data stream (data duplication). The data is then written in a ”round robin” manner to each of the tape devices implied by the client identifiers in the list (data striping). A null request may be used to cancel any existing association. The current state of the EGTS must be halted otherwise the request will fail.

RESPONSE

procedure status

Procedure status is a 4 byte field which indicates the result of the request.

Procedure status= 0  accepted
2  unknown client identifier for this client
8  capability is invalid
13  EGTS is in wrong state

Procedure 29. Inquire EG Stream Association

REQUEST

EG stream capability

Requests a description of the tape devices to which the EG stream is associated.

RESPONSE - success success = 0 mode = 2 valid = true list length

list of client identifiers

:

valid = false A variable number of variable length lists of client identifiers are returned. Only mode = 2 is returned by version 4 of the program protocol.

Each list of client identifiers receives a copy of the data for this EG data stream (data duplication). The data is then written in a ”round robin” manner to each of the tape devices implied by the client identifiers in the list (data striping).

If there is no current stream association for this data stream then a null list of lists is returned.

RESPONSE - failure procedure status

Procedure status is a 4 byte field which is non zero and indicates the cause of the failure.

Procedure status= 8  capability is invalid

Procedure 30. Inquire EGTS Stream State

REQUEST

EG stream capability

RESPONSE - success

success = 0 state block count byte count data rate

state = 1 indicates that the EG Tape Server is currently in the halted state, state = 2 indicates that it is currently in the going state and state = 3 indicates that it is currently in the test state. The number of data blocks received for this EG stream is returned in block count and the number of data bytes in byte count. Data rate contains the data received in bytes per second averaged over the last 10 second period for this EG stream.

RESPONSE - failure procedure status

Procedure status is a 4 byte field which is non zero and indicates the cause of the failure.

Procedure status= 8  capability is invalid

Procedure 23. Allocate Device

REQUEST

client identifier

capability

device name length

device name Allocates the specified device for exclusive use of the client to the supplied client identifier.

Stream identifier is a 4 byte opaque field supplied by the client to identify this device. It must be different from any other client identifier currently in use by this client for previously allocated devices. Device name specifies the server resource to be allocated. It may either be the name of an actual resource or a generic name given to a group of identical resources. The resources available are server dependant but a list may be obtained by use of the Inquire Available Devices procedure.

RESPONSE - success

success = 0 device name length

device name

The response returns the actual device name allocated. This is useful when the request supplies a generic name requesting any one of a group of identical devices. The current value of stream status for this stream changes to dev alloc. The current value of procedure status for this stream changes to success (=0).

RESPONSE - failure procedure status

Procedure status is a 4 byte field which is non zero and indicates the cause of the failure.

Procedure status= 1  client identifier already in use for this client
3  no free resources
6  requested resource unavailable