Protocol for Communication

Methods provide three different kinds of data stream. You can view all of these from browsers:

HTML for browser display. See this example (and view at the "source").
Flat listings browser display. See this example.
Protocol for application programs. See this example.

The rest of this document concentrates on the last case.

Example

We illustrate the communication protocol with a simple example: for a data object which looks like

list "test(station<=5&press<100,station,lat,lon,press,o2)"
#  wunsch stations 3-10 
#  p<1000 
======================= 
station,    lat,    lon
........................ 
      3,  38.28, -73.53
======================= 
  press,     o2
------------------------ 
  5.000,  5.970
 25.000,  6.990
 49.000,  6.060
 99.000,  5.340
======================= 
station,    lat,    lon
........................ 
      4,  38.19, -73.52
======================= 
  press,     o2
------------------------ 
  5.000,  5.840
 25.000,  7.090
 49.000,  6.020
 99.000,  5.340
======================= 
station,    lat,    lon
........................ 
      5,  38.16, -73.26
======================= 
  press,     o2
------------------------ 
  5.000,  5.770
 25.000,  6.660
 49.000,  5.510
 99.000,  5.100
=======================

The dictionary entry is assumed to be

test=def(/usr/users/jgofs/data/t0)

The communications look like:

list -> method (def)
argv = [/usr/users/jgofs/data/t0,station<=5&press<100,station,lat,lon,press,o2
def -> list
&c***********************
 wunsch stations 3-10
 p<1000
&v0======================

&v1======================
station lat     lon
&v2======================
press   o2
&r=======================
&c***********************
 wunsch stations 3-5
 p<1000
&d0----------------------

&d1----------------------
3       38.28   -73.53
&d2----------------------
5.000   5.970
25.000  6.990
49.000  6.060
99.000  5.340
&d1----------------------
4       38.19   -73.52
&d2----------------------
5.000   5.840
25.000  7.090
49.000  6.020
99.000  5.340
&d1----------------------
5       38.16   -73.26
&d2----------------------
5.000   5.770
25.000  6.660
49.000  5.510
99.000  5.100
&e**** End of object ****

Thus the application begins by sending the parameters to the method and then reading the blocks of data. The blocks are indicated by commands with an & in the first position. There are four types of protocol blocks: comments, variable names, data, and end.

Protocol blocks

Comments

The &c introduces the plain text comments section. Comments consist of lines of no more than 80 characters.

Variables

This section gives the names, dimensions, and attributes of variables at each hierarchical level. The outermost level, 0, is defined first and then we work our way inward. The signal is &vn with n=0...9 the level indicator. Each variable definition has:

The name (avoid embedded blanks --- use _ )
Attribute list appended to the variable name surrounded by []. The attribute list is a comma-separated set of strings, usually (except for units) of the form attribute=value. The variables section is closed by a record marker, &r.

Variable fields are tab-separated.

Data

The data is likewise presented in a hierarchical fashion. The &dn intoduce the data from the n'th level. Note that the innermost level can drop the &dn. The data from the outermost levelis sent, followed by the next level, up to the innermost level. The innermost level repeats until the next level up changes or the data ends. Data fields are tab-separated.

End

This indicates the end of the data object. The indicator is &e.

Errors

Errors are indicated by the method returning &x [descriptive string] and exiting.