Silicon Graphics, Inc.
OpenVault
Client and Language Version Negotiation
Language Definition

$Id: HELLO.html,v 1.5 1997/07/15 19:14:41 jbt Exp $

Overview and High Level Goals

OpenVault needs the ability to upgrade parts of itself without requiring that all parts be upgraded at the same time. Since each of the interfaces used by OpenVault is in fact a language, we have defined those languages to have names and explicit version numbers for each version of each language.

This document describes how clients in the OpenVault system negotiate with the MLM Core to determine which of the OpenVault languages they would like to use, and which version of that language.

An overview of that negotiation is that when a client connects to the MLM Core, it announces which language it intends to use, and which versions of that language it understands. The MLM Core then picks one of those versions and tells the client that they will be using that version during the current session.

Decisions, Assumptions, and Limitations

Once the language version negotiation is completed, the parties are free to use whatever format or structure of communication will fit into the TCP socket. In effect, after the semicolon that terminates the "welcome" response, the socket could even carry pure binary if that were the definition of the language version that both sides agreed to use.

Interfaces

There are only two messages in the client to MLM connection, one in each direction: a hello message goes from the client to the MLM Core, while a welcome or unwelcome message returns from the MLM Core.

Both messages are sent as simple ASCII text in a normal TCP socket (albeit with a bit more complexity if message integrity coding is enabled, see Interprocess Communication and Authentication for more information). Unlike the ALI, ADI, CAPI, or AAPI languages this interchange has no additional structure, there are no phases (eg: no command, ack, or data phases).

Open Issues

None known at this time.

Functional Specification

Command Descriptions

hello The hello command is designed to implement a language and language version negotiation scheme. An external client will use the hello command to announce itself to the MLM Core. It will include in that command the name of the language it would like to speak, a list of the different version numbers of that language that it supports, a name for itself as an application, and a name for itself as a particular instance of an application.

LCPs and DCPs will use the OpenVault name of the device that they control as their application name.

welcome The welcome command is designed to tell the client which version of the given language the MLM Core has decided to use when talking to that client. After the external client has announced itself to the MLM Core via an appropriately filled in hello command, the MLM Core will respond with a welcome command. That command will specify which of the language versions named in the hello command the MLM Core will be using during this session.
unwelcome The unwelcome command is designed to tell the client that none of the combinations of language and language version it provided are supported by this MLM Core. After the external client has announced itself to the MLM Core via a hello command, the MLM Core may respond with an unwelcome command if the language name is unknown or none of the language versions supported by the client are supported by the MLM Core. There is both a machine-understandable error token and a set of text strings to display for the user.

Element Descriptions

language A language name is the name of the language that the client would like to use when talking to the MLM Core. It can (currently) be one of the following: "ALI", "ADI", "CAPI", or "AAPI".
versions A version number is a string identifying a particular revision of the named language. A hello command can specify multiple versions, meaning that the client is prepared to speak any of the named versions with the MLM Core. Examples of version numbers include: "1", "1.0", and "2.1".
client A client name is a text string that tells the MLM Core the application's name; an example might be "NetWorker".

LCPs and DCPs will use the OpenVault name of the device that they control as their client name. An LCP example might be "robbie" while a DCP example might be "firstDLT" and a PROXY example might be "fileserver1".

instance An instance clause is a text string that tells the MLM Core the name of the particular ocurrence of the application. For example, if the application name were "NetWorker", the instance name might be the name of the host it is running on or the name of the department being backed up.

Another example might be a system with two possible connections to a high-speed tape drive that would like to run a separate DCP for each of those connections. Each DCP would have a client of the drive name, but each would have a different instance name so that the core could tell them apart.

error token This is part of an unwelcome response from the MLM Core. An error token is one of a set of predefined text strings corresponding to the error that occurred. For example: "EBADLANGUAGE" or "EBADVERSION".
error text string This is part of an unwelcome response from the MLM Core. An error text string is a free format text string that expresses the same error shown in the error token in a human-readable format. For example: "The language name is not recognized".

Language Syntax Specification

Syntactic conventions are that single quotes may be used in place of double quotes in all contexts.

HELLO Command Syntax

This syntax is used by the external client when initiating a connection to the MLM Core. The WELCOME syntax is detailed later and is used when the MLM Cores is responding to the external client.

helloStmt: "hello" <helloArgs>+ ";"
helloArgs: <helloLangSpec> | <helloVersionSpec> | <helloClientSpec> | <helloInstanceSpec>
helloLangSpec: "language" "[" <SHORTSTRING(languageName)> "]"
helloVersionSpec: "versions" "[" <SHORTSTRING(versionNumber)>+ "]"
helloClientSpec: "client" "[" <SHORTSTRING(clientNameOrDeviceName)> "]"
helloInstanceSpec: "instance" "[" <SHORTSTRING(instanceName)> "]"

HELLO Command Examples

hello language["CAPI"] versions["1.0" "2.0"] client["networker"] instance["physics"];
A client is announcing itself as capable of talking either version 1.0 or 2.0 of the CAPI language, the client application's name is "networker", and this is instance "physics" of that application.

hello language["ALI"] versions["2.0"] client["robbie"] instance["one"];
A client is announcing itself as capable of talking only version 2.0 of the ALI language (which make that client an LCP), the client's name is "robbie" (which means that is controls a robot named "robbie"), and this is instance "one" of that application.

WELCOME and UNWELCOME Command Syntax

This syntax is used by the MLM Core when it is responding to an external client.

response: <welcomeStmt> | <unWelcomeStmt>
welcomeStmt: "welcome" "version" "[" <SHORTSTRING(versionNumber)> "]" ";"
unWelcomeStmt: "unwelcome" <unWelcomeArgs>+ ";"
unWelcomeArgs: "error" "[" <SHORTSTRING(errorToken)> "]" |
"text" "[" <STRING(text of message)> "]"

WELCOME and UNWELCOME Command Examples

welcome version["2.0"];
The MLM Core has agreed to talk version 2.0 of the specified language.

unwelcome error["EBADLANG"];
The MLM Core did not recognize the language name and is refusing to talk to the client. The socket will be closed immediately after the unwelcome message.

unwelcome error["EBADVERSION"] text["Unsupported language version"];
The MLM Core does not support any of the versions of the language named in the hello and is refusing to talk to the client. The socket will be closed immediately after the unwelcome message.

Possible Error Returns

If the MLM Core does not recognize the language name, or it does not support any of the specified the versions of that language, an unwelcome response is issued and the MLM Core will summarily close the socket.