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.

All transactions from the server to the client are performed in pairs. A 4-byte value containing the total number of bytes to be sent is transmitted first, followed by the data.
All numeric values are sent in network-byte-order, or big-endian. All client APIs for ADDE expect data to be transmitted in big-endian format and perform the necessary byte swapping where appropriate. Byte swapping is only performed on integer values; character strings are not flipped.
If you transmit floating point values via ADDE, send the data as scaled integers. The platforms supported by McIDAS-X are not guaranteed to use the same bit representation for floating point values.

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:

Interpret the client request
Read the data from disk in its native format
Convert the data to the format the client expects
Send the data to the client

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 GFS/00 GRID 101 110 TYPE=GRID "00Z GFS Model Run
DSSERVE ADD LOCAL/MODEL FLAT TYPE=GRID "Local Model Grids

The first entry created the grid dataset GFS/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 GFS/00

mcserv starts the primary server ggetserv.
ggetserv reads the server mapping table entry for the dataset GFS/00.
Because the grids from GFS/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

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

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