McIDAS Programmer's Manual
Version 2003

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

Building your ADDE server

Whether you're creating primary or secondary ADDE servers, they must perform these seven steps:

Initialize the McIDAS-X file system to recognize MCPATH and file redirection.
Read the ADDE client request.
Read the server mapping table.
Interpret the client request.
Retrieve the requested data from disk.
Send the data to the client.
End the transaction.

Steps 1, 2, 3 and 7 are the same for all data types; steps 4, 5 and 6 are different among the data types. All seven steps are described in this section, along with the function calls required to perform them.

This section is organized into these parts:

McIDAS library functions
Initializing the McIDAS-X file system (step 1)
Reading the ADDE client request (step 2)
Reading the server mapping table (step 3)
Interpreting the client request (step 4)
Retrieving the requested data from disk (step 5)
Sending the data to the client (step 6)
Ending the transaction (step 7)

McIDAS library functions

The McIDAS-X library functions that you will use when creating an ADDE server are listed alphabetically in the table below.

C function	Fortran function	Description
	initblok	initializes the McIDAS-X environment for the server
M0isrtdataset	m0isrtdataset	determines if the dataset requested was flagged as a real-time dataset
M0IsTraceSet	m0istraceset	given a client request, activates tracing if TRACE=nonzero value
M0swbyt4	swbyt4	conditionally flips 4-byte data buffers
	swbyt2	conditionally flips 2-byte data buffers
M0sxdatasetinfo	m0sxdatasetinfo	extracts the server mapping table information
M0sxdone	m0sxdone	ends the ADDE transaction
M0sxGetClientRequest	m0sxgetclientrequest	reads the request header and request string sent from the client
M0sxread	m0sxread	reads data sent from the client to the server
	m0sxresolv	appends information from the server mapping table to the client request
M0sxsend	m0sxsend	sends data from the server to the client
M0sxSetTraceOff	m0sxsettraceoff	turns tracing off
M0sxSetTraceOn	m0sxsettraceon	turns tracing on
M0sxtrce	m0sxtrce	writes tracing information to a trace file
M0InitLocalServer		initializes the environment for secondary servers
Mctrace	mctrace	writes tracing information to a trace file

Initializing the McIDAS-X file system

Your server must be able to access McIDAS-X disk files, since most servers are built using disk file utilities. Use the initblok function to initialize the McIDAS-X disk file system so the server can recognize MCPATH and the redirection table, as shown below. Note that the parameter passed into initblok must be a 2-byte integer.

In Fortran:

integer*2 init_stat
:
ok = initblok (init_stat)

In C:

short     init_stat;
:
ok = initblok_ (&init_stat);

For more information about disk files, see the section titled McIDAS disk files in Chapter 5, Accessing Data. For more information about file redirection and MCPATH, see the section titled McIDAS user applications in Chapter 2, Learning the Basics.

Reading the ADDE client request

Each ADDE client request received by the server contains a 160-byte request header, which contains system-level information built for the server.

The table below shows the input components included in the request header. The third column contains the starting word locations if the server is written in Fortran; the fourth column contains the variable names for the C structure, servacct, if the server is written in C.

Request header components	Length, in bytes	Word number in Fortran	servacct structure names in C
server IP address	4	1	server_address
server port	4	2	server_port
client IP address	4	3	client_address
user initials	4 (ASCII)	4	user
project number	4	5	project
password	12 (ASCII)	6 - 8	password
service name	4 (ASCII)	9	transaction
input data length	4	10	input_length in excess of 160 bytes
request string	120 (ASCII)	11 - 40	text

The last 120 characters of the request header is a buffer that may hold the client request string. The request string contains the group and descriptor names, and any selection conditions the server may need to fulfill the client request. If the request string is too long to fit in this buffer, the request string variable will contain a value of zero in bytes 4-7; bytes 0-3 will contain the actual length of the request string, which the server then must read from stdin.

The process for reading the ADDE client request is performed with one of two functions, depending on whether the server reading the request is a primary or secondary server.

Words 41 to 64 are for sending a return packet. The section Ending the transaction in this chapter provides more information.

Using a primary server

To read the client request from a primary server, call M0sxGetClientRequest or m0sxgetclientrequest, as shown in the code fragments below.

In Fortran:

include 'fileparm.inc'
character*(MAXPATHLENGTH) request
integer                   request_block(64)
:
:
ok = m0sxgetclientrequest(request_block, request)

In C:

#include "mcidas.h"
:
servacct request_block;
char     *request;
int       ok;

ok = M0sxGetClientRequest (&request_block, &request);

Upon successful completion, request_block contains the request header information sent to the server, and request contains the request string, including the group and descriptor names and selection conditions specified.

Using a secondary server

To read the client request from a secondary server, call the function M0InitLocalServer, as shown in the code fragment below.

const char Server[] = {"TESTSERV"};
servacct   request_block;
char      *request;
:
:
ok = M0InitLocalServer (Server, &request_block, &request);

If the dataset requested by the client is stored in a non-standard McIDAS-X format on the server, the primary server starts the secondary server with a call to m0subserv. m0subserv builds an argument list for the secondary server and starts it with a call to execlp. The argument list contains both information from the client request block and the actual client request string. The M0InitLocalServer function extracts values from the secondary server's argument list and puts them in the client request block.

Reading the server mapping table

Once the server successfully receives the client's request, it must extract information from the server mapping table, which is a database that provides the server with information needed to fulfill a user request. The server mapping table is manipulated by the DSSERVE command and contains information about the location and format of the data on the server machine. This information is accessed by the server based on the group and descriptor names included in the client request.

The function M0sxdatasetinfo or m0sxdatasetinfo extracts information that the server needs from the server mapping table, including:

ADDE group and descriptor names
Stored data type and its format
Minimum and maximum file numbers in the dataset
Any additional information needed to fulfill the request
Dataset comment section
Flag indicating if the dataset is a real-time dataset

The code fragment below demonstrates the use of M0sxdatasetinfo. It assumes that the server administrator entered the following DSSERVE command, which created the ADDE dataset GMS/IR:

Type: DSSERVE ADD GMS /IR AUST 3 8 TYPE=IMAGE INFO=east_ir.cfg "GMS Infrared Imagery

char *request;
char *group;
char *dataset;
char *type;
char *format;
char *info;
char *comment;
int   min_range;
int   max_range;
int   real_time;

...
...
...

ok = M0sxdatasetinfo (request, &group, &dataset, &type, &format,
                 &info, &comment, &min_range, &max_range, &real_time);

Upon successful completion, the output variables will contain the following values:

Variable	Value
group	GMS
dataset	IR
type	IMAGE
format	AUST
info	east_ir.cfg
comment	GMS Infrared Imagery
min_range	3
max_range	8
real_time	0 (default)

Interpreting the client request

After the server reads the client request and extracts the dataset information from the server mapping table, it parses the client request so the data can be located and the request fulfilled.

Since client requests are similar in form to a McIDAS-X command, it is easiest to use the McIDAS-X command line parsing routines to extract information from the request. To use common command line data retrievers, such as Mccmdstr and Mccmdint, you must initialize the command line subsystem. You only need to do this for primary servers. The M0InitLocalServer function automatically performs these steps for secondary servers.

The code fragments below demonstrate how to initialize the command line subsystem in both Fortran and C.

In Fortran:

    character*256    request
    integer          len_req
    :

c---    request already contains the request string to be parsed

    call m0cmdput (m0cmdparse (request, len_req))

In C:

char *request;
int   len_req;
int   stat;
:

/* request already contains the request string to be parsed */

stat = M0cmdput (M0cmdparse (request, &len_req)) ;

Once the request string is parsed by the command line subsystem, it is your job, as the server developer, to find the data matching the request. The section titled Request syntax and data transmission formats later in this chapter explains the request syntax for each of the McIDAS-X data types.

Retrieving the requested data from disk

The method of retrieving data matching the client request will vary from file format to file format.

When determining the location of data files, you should be aware that the server mapping table may not have enough entries available for an individual dataset to fully explain the filing format. If this happens, use a configuration file and store the name of that file in the INFO field of the server mapping table. Then the server can get additional file location information there.

Sending the data to the client

When the request is parsed and the appropriate data is located, it can be sent back to the client. All data transactions are done in pairs (count + data) using the function M0sxsend or m0sxsend. First, a 4-byte value containing the length of the data being sent to the client is transmitted. Then that many bytes of data are transmitted.

To ensure that data sent between the server and the client is in network-byte-order (big-endian), include calls to M0swbyt4 or swbyt4 for all integer values. This function flips 4-byte memory segments on little-endian machines; it has no effect on big-endian machines.

The first value sent from the server to the client is read internally by the client function M0cxreq or m0cxreq before any API-level reading routines are called. For example, when serving image data, this value is the total number of bytes the server will send to completely transmit the data object. Some ADDE clients expect a dummy, nonzero value in this location. If a zero is sent back, M0cxreq or m0cxreq assumes the server was unable to fulfill the request. The complete transmission format for each McIDAS-X data type is described later in this chapter in the section titled Request syntax and data transmission formats.

The code fragment below demonstrates the appropriate way to send data from the server to the client. It assumes the client wants to receive a 4-byte dummy value of one, which will be read by m0cxreq, followed by two 40-byte records. Words 2 through 4 in the record are character values; the remainder of the record contains integer values.

    integer n_bytes      ! number of bytes to send  
    integer n_bytes_nbo  ! number of bytes in network byte order
    integer dum_val
    integer buffer(10)

c---    send the value 4 to the client indicating that it is to read an 
c---    additional 4 bytes; the additional 4 bytes will contain the 
c---    value 1; this pair is read on the client in m0cxreq.

    n_bytes     = 4
    n_bytes_nbo = n_bytes
    call swbyt4(n_bytes_nbo, 1)
       call m0sxsend (4, n_bytes_nbo)

       dum_val = 1
       call swbyt4(dum_val, 1)
       call m0sxsend (n_bytes, dum_val)


c---    now we will loop 2 times, getting new data and sending it
c---    back to the client; remember that words 2 through 4 are
c---    character strings.

    do 10 I = 1 , 2

c---    get the data

    ok = datareader (buffer)   ! fictitious function

c---    send the record length back
    
        n_bytes     = 40
        n_bytes_nbo = n_bytes
        call swbyt4(n_bytes_nbo, 1)
        call m0sxsend (4, n_bytes_nbo)

c---    convert the appropriate locations in the buffer to
c---    network byte order

        call swbyt4(buffer(1), 1)
          call swbyt4(buffer(5), 6) 

c---    send the data back to the client

        call m0sxsend (n_bytes, buffer) 

10  continue

Ending the transaction

After the data is transmitted to the client, the server ends the transaction by calling M0sxdone or m0sxdone. This function sends a 96-byte trailer, which is filled on the server and sent to the client at the end of the transaction. Its contents are described in the table below.

Trailer description	Length, in bytes	Word number in Fortran	servacct structure names in C
total reply length	4	41	reply_length
cpu used	4	42	cpu
return status code	4	43	returncode
error messages	72	44 - 61	errormsg
date	4	62	date
start time	4	63	start_time
end time	4	64	end_time

Before the transaction ends, you must set the return status code and any error messages that may have voided the transaction. The only successful return code is zero, which appears in word 43 of the client request block. If you send a nonzero value to the client, also put an error string in words 44-61 so the client API will print a message telling the user why the request couldn't be fulfilled. If your site uses the ADDE accounting software, also fill word 41 with the total number of bytes transmitted to the client.

The code fragment below shows the calling sequence that a server should include for a request that can't be fulfilled.

    integer       request_block(64)
    logical       syntax_error
    :
    :

c---there is a syntax error in the client request

    if (syntax_error)then
       comm_block(43) = -1001
        call movcw (request_block(44),'Syntax error in the user
          request')
    endif

    call m0sxdone (request_block)

Using this example, the message below is printed by the function m0cxreq if the server encounters a syntax error.

COMMAND: Syntax error in the user request -1001

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