McIDAS Programmer's Manual
Version 2003

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]


Getting started

Before writing an ADDE server, you should understand some basic concepts about servers in McIDAS-X. This section describes the following:

Client and server communication

The ADDE design is stream-oriented, so both the client and server can work simultaneously. An ADDE server reads a data request sent from the client via stdin (standard input) and sends data back to the client using stdout (standard output) through a pipe.

Although the size of the data sent from the server may be many megabytes, intermediate data storage on the server or client is not needed. Since the pipe is a finite size, the server will wait to write if the pipe is full. The client will wait for up to two minutes if the pipe is empty. If no activity takes place on the pipe after two minutes, the process stops. This is important for requests that take a long time to fulfill due to extensive searching. An environment variable, ADDETIMEOUT, can be set on the server to change this timeout length.

Rules for transmitting data

The rules below apply to all data transmissions between the server and client.

Primary servers

Primary servers, along with the client APIs, define the client selection syntax and the transmission format between the server and the client. The selection syntax and transmission format are different for the various data types in McIDAS-X. The table below lists the current primary servers provided in McIDAS-X.

Client APIs Client request type Data type Server name Description Secondary server suffix

mcadel

ADEL

image

adelserv

deletes images from a dataset

 

mcadir
mcadrd

ADIR

image

adirserv

retrieves image header information

ADIR

mcaget
mcalin
mcapfx
mcanav
mcacal
mcacrd

AGET

image

agetserv

retrieves the image header, navigation, calibration and data; data is returned line by line

AGET

mcaput
mcaout
mcacou

APUT

image

aputserv

writes an image object to a dataset

 

mcaput

ATOK

image

atokserv

checks file permissions for writing image objects

 

mcgdir
mcgfdrd
mcgdrd

GDIR

grid

gdirserv

retrieves grid header information

GDIR

mcgget
mcgridf
mcgridc

GGET

grid

ggetserv

retrieves the grid header and entire grid

GGET

mcgput
mcgoutf
mcgoutc

GPUT

grid

gputserv

writes a grid object to a dataset

 

mcgput

GTOK

grid

gtokserv

checks file permissions for writing grid objects

 

m0pthdr
m0ptrdhdr
m0pthdrd

MDFH

point

mdfhserv

retrieves point file header information

 

ptcopy command

MDHD

point

mdhdserv

retrieves point header information

 

m0ptget
m0ptrd

MDKS

point

mdksserv

retrieves the point header and data

KS

m0navget
M0ReadNavBlock

NAVG

nav

navgserv

retrieves satellite navigation

 

M0obtxget
M0obtxread

OBTG

text

obtgserv

retrieves observational weather text

OBTG

M0textget
M0txtread

TXTG

text

txtgserv

retrieves an ASCII text file

 

M0wtxget
M0wtxread

WTXG

text

wtxgserv

retrieves textual weather information

WTXG

The ADDE communications module, mcserv, starts the primary servers based on the server's IP address, which tells mcserv if the request will be fulfilled locally or remotely. If the request is handled locally, mcserv finds the ADDE request type and runs the appropriate server process. The server process reads the body of the client request, acquires the data requested and sends the data back to the client.

If the request is handled remotely, mcserv opens a connection to the remote server and acts as a TCP-to-pipe bridge, sending out the request. On the server machine, inetd receives the connection and creates a child process running the same mcserv module with slightly different command arguments. Like local requests, this version reads the beginning of the client request, determines which server process is needed and runs it. The server processes the request and sends the data requested back to the client.

Secondary servers

In ADDE, the client requesting data doesn't care about the file format of the stored data. It only cares that the data is delivered in a well-known, predefined format. For example, if you have gridded data stored in a flat ASCII file, the McIDAS-X GRDDISP command can contour that data as long as the server delivers the gridded data to the client in the appropriate format. To accomplish this, you need a secondary server.

The secondary server's job is to:

Sample data request

The example below shows the steps that a primary and secondary server will use to fulfill a data request. You should assume that the server administrator inserted the two commands below into the server mapping table:

DSSERVE ADD ETA/00 GRID 101 110 TYPE=GRID "00Z ETA Model Run
DSSERVE ADD LOCAL/MODEL FLAT TYPE=GRID "Local Model Grids

The first entry created the grid dataset ETA/00, which is stored in the standard McIDAS-X grid format in grid file numbers 101 to 110. The second entry created the grid dataset LOCAL/MODEL. The grids for this dataset aren't stored in the McIDAS-X grid format, but in a format called FLAT. If a user enters a GRDDISP command to display a grid from each of these datasets, the steps taken by the server to fulfill these requests are different.

Using a primary server

If the user enters the GRDDISP command below, the steps that follow are performed once the appropriate machine is identified.

Type:  GRDDISP ETA/00

  1. mcserv starts the primary server ggetserv.
  2. ggetserv reads the server mapping table entry for the dataset ETA/00.
  3. Because the grids from ETA/00 are in the standard McIDAS-X format, ggetserv processes the data request and sends the data to the client.

Using a secondary server

If the user enters the command below, the steps that follow are performed.

Type:  GRDDISP LOCAL/MODEL

  1. mcserv starts the primary server ggetserv.
  2. ggetserv reads the server mapping table entry for the dataset LOCAL/MODEL.
  3. Because the grids are stored in a non-standard McIDAS-X format called FLAT, ggetserv starts the secondary server flatgget.
  4. flatgget processes the data request and sends the data to the client.

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]