McIDAS Programmer's Manual
Version 2003

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


Request syntax and data transmission formats

This section is organized into the following topics:

In ADDE, the client will manipulate data regardless of the format in which it is stored on the server. For this to happen, however, you must follow a specified set of rules for processing data and delivering it to the client. This section describes the client request syntax and data transmission formats for each data type supported in McIDAS-X. The table below provides a summary of the necessary components for each request type, in alphabetical order.

Request type Data type Description Client requester Client reader Sample McIDAS-X command

ADIR

image

image header information

mcadir

mcadrd

 

AGET

image

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

mcaget

mcalin
mcapfx
mcacrd
mcacal
mcanav

 

 

GDIR

grid

grid header information

mcgdir

mcgfdrd
mcgdrd

 

GGET

grid

grid header and entire grid

mcgget

mcgridf

   

MDFH

point

point file header information

m0pthdr

m0ptrdhdr

FORM=FILE

MDHD

point

point header information

 

 

PTLIST FORM=PARAM

MDKS

point

point header and data

m0ptget

m0ptrd

PTLIST

NAVG

nav

satellite navigation

m0navget

m0snlist
m0nvblk

 

OBTG

text

observational weather text

M0obtxget

M0obtxread

 

TXTG

text

ASCII text file

M0textgt

M0txtread

 

WTXG

text

textual weather information

M0wtxget

M0wtxread

 

All secondary servers must perform the four basic tasks below to deliver the appropriate data to the client.

  1. Read the client request based on the syntax described for the data type.
  2. Verify that the client request adheres to any special rules which apply to that data type.
  3. Convert the data to the format the client expects.
  4. Transmit the data to the client in the appropriate format.

Since ADDE client requests are sent as character strings with a format similar to McIDAS-X commands, it is easiest to use the McIDAS-X command line retrieving routines to extract information from the client request. The request syntax description for each data type described in this section uses the McIDAS-X command line notation.

Additionally, remember that transactions of integer values between the client and the server are performed in network-byte-order (big-endian). Unless otherwise noted, assume that all strings sent back to the client are blank padded.

Serving image data

The ADDE server, agetserv, processes a client request and returns a complete image object to the client. An image object includes an image header and the image lines, and may also contain a line prefix for each line, calibration, navigation and comment cards. Due to the volume of data associated with image objects, the server delivers the data portion of the object to the client one line at a time. The McIDAS-X command IMGDISP accesses image objects.

Image object request syntax

The table below lists the client request syntax options for an image object. Note that keywords 1 through 9 are placed in the request block as positional parameters.

Keywords Description Remarks

' ' 1

group name

 

' ' 2

dataset name

 

' ' 3

position in the dataset

relative position in the dataset; negative means Nth most recent

' ' 4

coordinate type and position

(E)arth, (I)mage, (A)rea; (C)entered or (U)pper; no default; this field is used with the next two parameters; for example, to return an image centered at latitude 43.5 and longitude 90.0, the client request will contain EC 43.5 90.0

' ' 5

latitude or line number

latitude of the Earth (dd:mm:ss) or line number

' ' 6

longitude or element number

longitude of the Earth (dd:mm:ss) or element number

' ' 7

image resolution

default=1

' ' 8

number of lines to transmit

default=480

' ' 9

number of elements to transmit

default=640

VERSION=

transmission version number

value as of 11/96 is 1

TIME=btime etime

time of day selection range

the format is hh:mm:ss (no default)

DAY=

the day that data is valid

not a range of days; format must be yyddd or ccyyddd (no default)

UNITS=

calibration type requested

not all calibration types are valid for a data type (default=stored units)

SPAC=

number of bytes per data point

be careful when reducing data point resolution, if the data can be sent back in lower resolution (default=stored format)

CAL=

set to QTIR to return TIROS in quick calibration

 

STYPE=VISR

sets calibration to UNITS of BRIT and type of VISR

converts data type to 1-byte data

BAND=band
BAND=ALL

specific band number to send or ALL bands

 

LMAG=

line magnification factor

blow ups are done on the client to conserve transmission bandwidth (default=1); values must be integers; negative numbers mean a blowdown must be performed

EMAG=

element magnification factor

blow ups are done on the client to conserve transmission bandwidth (default=1) values must be integers; negative numbers mean a blowdown must be performed

DOC=

if YES, include the line documentation block

default=NO

AUX=

if YES, additional calibration information is sent

 


Server-specific keywords Description

ID=

NEXRAD station ID (NEXRAD server)

TIME=btime etime C

Coverage; accesses data for specified time range (realtime POES server)

WL=

wavelength (AIRS server)

WN=

wavenumber (AIRS server)

Special rules for transmitting an image object

You must adhere to the rules below when transmitting an image object. The first five are specific to the client request; the last three are specific to the transmission format sent back to the client.

Converting the image object's format

The image object contains the image header and the image lines. It may also contain line prefixes, navigation, calibration and comment cards. Each of these components is created by the server. Their formats are described in Chapter 6 of this manual in the AREAnnnn data file documentation. Below are the common modifications needed for the image header.

Word Description Reason for modification

1

ADDE dataset relative position number

always modified

6

upper-left image line number

1) if client does not specify SIZE=ALL

2) if client requests coordinate base transfer

7

upper-left image element number

1) if client does not specify SIZE=ALL

2) if client requests coordinate base transfer

9

number of lines in the image

1) if client does not specify SIZE=ALL

2) instead of sending lines containing all zeros at the bottom of the image

10

number of elements in the image; must be divisible by 4

1) if client does not specify SIZE=ALL

2) instead of sending lines containing all zeros at the bottom of the image

11

number of bytes per band

1) if SPAC≠source value

2) if client requests STYPE=VISR

12

line resolution

if LMAG≠1

13

element resolution

if EMAG≠1

14

number of spectral bands

if BAND≠ALL

15

length of line prefix

1) if BAND=ALL is not specified

2) if SIZE=ALL is not specified

3) if DOC=YES is specified

4) if STYPE=VISR

19

spectral band map

if BAND=ALL is not specified

34

byte offset to the start of the data block

always modified (256+navlength+callength)

35

byte offset to the start of the navigation block

always modified (usually 256)

36

validity code

1) if request contains DOC=NO, set to 0

2) if SIZE=ALL is not specified, set to 0

3) if DOC=YES, must be set

49

length of the prefix documentation

1) if DOC=NO is specified, set to 0

2) if SIZE=ALL is not specified, set to 0

50

length of prefix calibration

if STYPE=VISR, set to 0

51

length of prefix band length

1) if STYPE=VISR, set to 0

2) if BAND≠ ALL

52

source type; satellite-specific (ASCII)

if STYPE=VISR, set to VISR

53

calibration type; satellite-specific (ASCII)

if STYPE=VISR, set to BRIT

54

sampling/averaging flag

set to 1 if blow down is performed by sampling

57

source's original satellite type (ASCII)

if STYPE=VISR, set to original satellite type

58

units of values returned

if AUX=YES and UNIT is specified

59

scaling of values returned

1) if UNIT is specified

2) if AUX=YES, set to 1

63

byte offset to the start of the calibration block

if calibration is sent
(usually 256+navlength)

64

number of comment cards

if comment cards exist

Transmitting the image object to the client

Once the data is formatted correctly, the image object can be sent to the client. Because the transmission protocol is count+data, the server will send the following information to the client:

The sample code below shows you how to set up your server to transmit image objects.

    integer image_header(64)
    integer nav_block(1024)
    integer cal_block(1024)
    integer line(2000)
    integer prefix(100)
    integer comment(20)
    integer total_bytes
    integer nav_size
    integer cal_size
    integer pre_size
    integer n_comments
    integer n_lines
    integer n_elements
    integer data_size
    integer n_send
    integer n_send_nbo

c---    assume the image_header, nav_block, cal_block have already been loaded

    n_lines    = image_header(9)
    n_elements = image_header(10)
    data_size  = image_header(11)
    nav_size   = image_header(63) - image_header(35)
    cal_size   = image_header(34) - image_header(63)
    pre_size   = image_header(15)
    n_comments = image_header(64)

    total_bytes= (n_lines * n_elements * data_size) +
    &             (n_rows * pre_size) +
    &             (n_comments * 80)
    &             (nav_size + cal_size)

c---    send the total number of bytes in the image object

    n_send_nbo = total_bytes
    call swbyt4(n_send_nbo, 1)
    call m0sxsend(4, n_send_nbo) 

c---    send the image header; assume imageheadernbo converts the header
c---    to network-byte-order

    call imageheadernbo(image_header)
    call m0sxsend(256, image_header) 

c---    send the nav block; assume navnbo converts the nav block to
c---    network-byte order

    if (nav_size .gt. 0)then
       call navnbo(nav_block)
       call m0sxsend(nav_size, nav_block) 
    endif

c---    send the cal block; assume calnbo converts the cal block to
c---    network-byte order

    if (cal_size .gt. 0)then
       call calnbo(cal_block)
       call m0sxsend(cal_size, cal_block) 
    endif

c---    now we will send the image data lines, one line at a time;
c---    assume getoneline retrieves one line of data as packed bytes

    do 10 i = 1 , n_lines
       ok = getoneline(i, line, prefix)
       if (pre_size .gt. 0)then
          call m0sxsend(pre_size, prefix) 
       endif
       call m0sxsend(n_elements, line) 
10  continue

c---    send the comments; assume readcomment reads one comment card

    if (n_comment .gt. 0)then
       do 20 i = 1 , n_comments
          call readcomment(i, comment)
          call m0sxsend(80, comment) 
20     continue
    endif

Serving image directory data

The ADDE server, adirserv, processes a client request and returns image directories and comment cards to the client. The McIDAS-X command IMGLIST accesses image directories.

Image directory request syntax

The table below lists the client request syntax options for image directories. Note that keywords 1 through 4 are placed in the request block as positional parameters

Keywords Description Remarks

' ' 1

group name

 

' ' 2

descriptor name

 

' ' 3

beginning file position number

can be the value ALL; positive numbers represent absolute locations; negative numbers are time-relative offsets (no default)

' ' 4

ending file position number

default=beginning file number

AUX=

when YES, sends the center lat/lon, latitude resolution in km, longitude resolution in km, and valid calibration types as comment cards

default=NO

BAND=

spectral band, if the image has multiple bands

 

DAY=bday eday

day range to search

ccyyddd or yyddd format (no default)

ID=

NEXRAD station ID

NEXRAD server only

SS=ss1 ss2

satellite sensor number

no default

TIME=btime etime

time range to search

hh:mm:ss format (no default)

WL=

wavelength

AIRS server only

WN=

wavenumber

AIRS server only

Special rules for transmitting the image directory

If the server has problems fulfilling the request, use the following standard error values and messages found in ~mcidas/src/adderror.doc. The range -12000 to -12999 lists error codes specific to image directories. Use enumerated error codes and messages when applicable and create new error codes and messages for error conditions that are unique to your site.

Converting the image directory's format

The image directory sent to the client is a 65-word directory. Word 1 contains the AREA number from the server. Words 2 through 65 are the same as words 1 through 64 in the image directory described in the AREAnnnn data file documentation in Chapter 6.

Transmitting image directory objects to the client

Once the data is formatted correctly, the image directory can be transmitted. Because the transmission protocol is count+data, the server will send the following information to the client:

The information is repeated until there are no new image directories to send. The sample code on the facing page shows you how to set up your server to transmit an image directory.

    integer image_header(64)
    integer n_comments
    integer comment(20)
    integer n_send_nbo
    integer total_bytes

c---    loop through all image objects matching selection conditions
c---    assume readimagedirectory reads a 64-word image in area format

    do 10 i = 1 , n_files

       ok = readimagedirectory (i, image_header)

       n_comments = image_header(64)

c---    calculate the number of bytes to be sent for this directory

       total_bytes = 260 + (n_comments * 80)
       n_send_nbo  = total_bytes
       call swbyt4(n_send_nbo, 1)
       call m0sxsend(4, total_bytes) 

c---    send the file number

       file = i
       call swbyt4(file, 1)
       call m0sxsend(4, file) 

c---    send the image directory; assume imageheadernbo converts
c---    the header to network-byte-order

       call imageheadernbo(image_header)
       call m0sxsend(256, image_header) 

c---    send comment cards backlashes readcomment reads once 
c---    comment card

       if (n_comments .gt. 0)then
          do 20 j = 1 , n_comments
             call readcomment(i,j,comment)
             call m0sxsend(80,comment) 
20     continue 
        endif
10  continue

Serving grid data

The ADDE server, ggetserv, processes a client request and returns complete grid objects to the client. The grid object contains the grid header and the data. Unlike the image server, which can only send one image object to the client, grid requests may include as many grid objects as desired. The McIDAS-X GRDDISP command accesses grid objects.

Grid object request syntax

The table below lists the client request syntax options for grid objects. The table below lists the client request syntax options for image directories. Note that keywords 1 through 3 are placed in the request block as positional parameters

Keywords Description Remarks

' ' 1

group name

 

' ' 2

descriptor name

 

' ' 3

maximum number of bytes that can be stored in the destination grid buffer on the client

 

DAY=day1 .. dayn

list of model-run days

ccyyddd format (no default)

DERIVE=

derived parameters

 

DRANGE=bday eday dinc

range of model-run Julian days

ccyyddd format

FDAY=

model-forecast valid day

ccyyddd format

FRANGE=fhr1 .. fhrn

range of model-forecast hours

 

FTIME=

model-forecast valid time

hhmmss format

GRIB=sgrib egrib

range of grib numbers to get from a McIDAS-X grid file

 

GRID=sgrid egrid

range of grid numbers to get from a McIDAS-X grid file

 

LEV=lev1 .. levn

list of data levels to retrieve

can be a number, SFC, MSL or TRO

NUM=

number of grids to retrieve

can be a number or ALL

PARM=p1 .. pn

list of parameters to retrieve

 

PARSE=select1 .. selectn

list of grid selection conditions for multiple grid parsing

format is a subset of other selection conditions specified; each selection is isolated by single quotes

PNUM=

number of parseable grids specified in the selection

 

POS=

relative file position number in the dataset

 

PRO=

model-projection type

 

SRC=src1 .. srcn

list of model grid sources

 

TIME=time1 .. timen

model run times to retrieve

hhmmss format

TRANGE=btime etime tinc

range of model-run times

hhmmss format for time

VERSION=

grid transmission version

value is A as of 11/96

VT=vt1 .. vt2

valid hour offsets

hhmmss format

Special rules for transmitting a grid object

You must adhere to the rules below when transmitting a grid object. The first two are specific to the client request. The last three are specific to the transmission format sent back to the client.

Converting the grid object's format

The grid object contains a grid header and gridded data. The grid header format is described in Chapter 6 of this manual in the GRIDnnnn data file documentation.

Transmitting grid objects to the client

As the server sends data to the client, TCP may timeout during periods of no data transmission. To avoid timeouts, the server can send a heartbeat value (11223344) periodically to the client to keep the connection active. The heartbeat values are sent at the beginning of the transmission only. Once all the data is found and formatted, the grid object can be sent to the client.

The server sends the client the following information:

The grid header, grid object, and 4-byte value containing zero are repeated until all the grid objects are sent.

The sample code below shows you how to set up your server to transmit a grid object.

    include 'gridparm.inc'
    integer grid_header(64)
    integer grid(MAXGRIDPT)
    integer total_bytes
    integer grid_size

c---    read the grid; assume readgrid reads a grid header's grid
c---    into McIDAS format

    ok = readgrid(grid_header, grid)
    grid_size = grid_header(1)

c---    send the total number of bytes

    total_bytes = 256 + (grid_size * 4) + 8
    temp_int    = total_bytes
    call swbyt4(temp_int, 1)
    call m0sxsend(4, temp_int)
    call M0sxsend (4 temp_int)

c---    send the number of grids

    temp_int = 1
    call swbyt4(temp_int, 1)
    call m0sxsend(4, temp_int)

c---    send the grid header; assume gridheadernbo switches integer
c---    values in the header to network byte order

    call gridheadernbo(grid_header)
    call m0sxsend(256, grid_header)

c---    send the data

    call swbyt4(grid_data,grid_size)
    call m0sxsend(grid_size*4, grid)

c---send 0 separate

    temp = 0
    call swbyt4(temp_int, 1)
    call M0sxsend (4,temp_int)

Serving grid directories

The ADDE server, gdirserv, processes a client request and returns grid directories to the client. The grid directory contains information about the contents of the grid. The McIDAS-X command GRDLIST is one that accesses grid directories.

Grid directory request syntax

The table below lists the client request syntax options for grid directories. Keywords 1 and 2 are placed in the request block as positional parameters.

Keywords Description Remarks

' ' 1

group name

 

' ' 2

descriptor name

 

DAY=day1 .. dayn

list of model-run days

ccyyddd format

DERIVE=

derived parameters

 

DRANGE=bday eday dinc

range of model-run Julian days

ccyyddd format

FDAY=

model forecast valid day

ccyyddd format

FRANGE=fhr1 .. fhrn

range of model-forecast hours

 

FTIME=

model-forecast valid time

hhmmss format

GRIB=sgrib egrib

range of grib numbers to get from a McIDAS-X grid file

 

GRID=sgrid egrid

range of grid numbers to get from a McIDAS-X grid file

 

LEV=lev1 .. levn

list of data levels to retrieve

can be a number, SFC, MSL or TRO

NUM=

number of grids to retrieve

can be a number or ALL

OUT=

output format

default=ALL

PARM=p1 .. pn

list of parameters to retrieve

 

PARSE=select1 .. selectn

list of grid selection conditions for multiple grid parsing

format will be a subset of other selection conditions specified; each selection is isolated by single quotes

PNUM=

number of parseable grids specified in the selection

 

POS=

relative file position number in the dataset

 

PRO=

model-projection type to retrieve

 

SRC=src1 .. srcn

list of model grid sources

 

TIME=time1 .. timen

list of model-run times to retrieve

hhmmss format

TRANGE=btime etime tinc

range of model-run times

hhmmss format for time

VERSION=

ADDE grid transmission version

value is 1 as of 11/96

VT=vt1 .. vt2

list of valid hour offsets

hhmmss format

Special rules for transmitting the grid directory

If PAR=STREAML, WINDB or WINDV, you must send the u- and v- component wind.

If DERIVE=TTIN, VOR, DVG, SPD, DIR, ABV, DSH, DST, TD, KINX, COR, BETA or ADV, you must calculate the appropriate grid before sending the results back to the client.

Converting the grid directory's format

The grid directory's format is defined in Chapter 6 of this manual in the GRIDnnnn data file documentation.

Transmitting the grid directory to the client

As the server sends data to the client, TCP may timeout during periods of no data transmission. To avoid timeouts, the server can send a heartbeat value (11223344) to the client periodically to maintain an active connection. The heartbeat values are sent at the beginning of the transmission only. Once all the data is found and formatted, the grid directory can be sent to the client.

The server sends the client the following information. Except the first item, all the items listed below are repeated for each grid file. Within each grid file, the grid file header and the two 4-byte values are repeated for each grid in the grid file.

A 4-byte value of 2, indicating no more grid files, is sent to end the transaction.

If the server has problems fulfilling the request, use the standard error values/messages found in ~mcidas/src/adderror.doc. The range -22001 to -22999 lists error codes specific to grid directories. Use enumerated error codes and messages when applicable and create new error codes and messages for error conditions that are unique to your site.

The sample code below shows you how to set up your server to transmit a grid directory.

 
    integer grid_header(64)
    integer grid_file_header(64)

c---    send total byte count

    temp_int = (260* n_grids) + (n_files * 260)
    call m0sxsend(4, temp_int)

c---    loop through the grid file headers

    do 10 file = 1 , n_files

c---        read the grid file header; assume readfileheader reads
c---        a grid file header in McIDAS grid file format

        call readfileheader(file, grid_file_header, n_grids)

c---        send the value 0 indicating that a grid file was found

        temp_int = 0
        call m0sxsend (4, temp_int)

c---    send the grid file header; assume gridfileheadernbo
c---    switches integer words to network byte order

    nbytes = 256
    call gridfileheadernbo(grid_file_header)
    call m0sxsend(nbytes, grid_file_header)

    do 20 i = 1 , n_grids

c---        read the grid header; assume readgridheader reads a 
c---        grid in McIDAS grid format

        call readgridheader(file,i,grid_header)

c---        send the value 0 indicating that a grid file was found

        temp_int = 0
        call m0sxsend (4, temp_int)

c---        send the grid header; assume gridheadernbo switches
c---        integer words to network byte order

        nbytes = 256
        call gridheadernbo (grid_header)
        call m0sxsend(nbytes, grid_header)
20  continue

c---    no more data from this grid file

    temp_int = 1
    call swbyt4(temp_int, 1)
    call m0sxsend (4, temp_int)
10  continue

c---    no more data

    temp_int = 2
    call swbyt4(temp_int, 1)
    call m0sxsend (4, temp_int)

Serving point data

The ADDE server, mdksserv, processes a request and returns point data to the client. In addition to the data values, the server also sends information about the units, scaling factor, and name of each parameter returned to the client. The McIDAS-X command PTLIST accesses point data.

Point data request syntax

The table below lists the client request syntax options for point data. The table below lists the client request syntax options for image directories. Note that keywords 1 through 2 are placed in the request block as positional parameters

Keywords Descriptions Remarks

' ' 1

group name

 

' ' 2

descriptor name

 

MAX=

maximum number of matches to find given the selection conditions

 

POS=

file position number in a dataset

 

SELECT=

data selection clause

see comments below

TRACE=

trace file activation

set to 1 to activate tracing

VERSION=

transmission version number

value is 1 as of 11/96

Special rules for transmitting point data

The client can request point data either by specifying no specific parameter names, which sends all the parameters to the client, or by specifying only the parameter names of interest. Because the user may ask for an unlimited number of individual parameters, the parameter list is sent after the client request string. Thus, a server must make additional calls to M0sxread to get the list of 4-byte, blank-padded parameter names. You can also call the McExtractPointRequest function to extract the client request and put it in the C structure PTREQUEST.

The SELECT clause contains the entire data selection clause format. You can use as many selection clauses as needed for each request. The selection clause format is described in the section titled Reading point objects: Defining selection conditions in Chapter 5, Accessing Data.

Transmitting point data to the client

When the point data is formatted correctly, it can be sent to the client. The server sends the following information:

The last two pieces of information are repeated until there is no more data to be transmitted. Then the 4-byte value containing the number of bytes of data to be sent will be zero.

If the server has problems fulfilling the request, use the standard error values and messages found in ~mcidas/src/adderror.doc. The range -31000 to -31999 lists error codes specific to point data. Use enumerated error codes and messages when applicable and create new error codes and messages for error conditions that are unique to your site.

The sample below shows how to set up your server to transmit point data.

    parameter (N_KEYS = 4)
    integer buffer(N_KEYS)
    character*256 keys
    character*256 keys
    integer scales(N_KEYS)
    integer length
    character*1 NULL
    data NULL=/'0'/
    integer temp

c---    send four parameters to the client: station ID, temperature
c---    in Celsius, dew point in Kelvin and wind direction

    keys='ID'//NULL//'T'//NULL//'TD'//NULL//'DIR'
    units='CHAR'//NULL//'C'//NULL//'K'//NULL//'DEG'

    scales(1)  = 0
    scales(2)  = 2
    scales(3)  = 2
    scales(4)  = 0

c---    send the key names

    length = lentrim(keys)
    temp=length
    call swbyt4(length, 1)
    call m0sxsend(4, length)
    call m0sxsend(temp * 4, keys)

c---    send the units

    length = lentrim(units)         
    temp=length
    call m0sxsend(4, length)
    call m0sxsend(temp * 4, units)

c---    send the scalings

    call swbyt4(n_vals, 1)
    call m0sxsend(4, n_vals)
    call m0sxsend(N_KEYS, scales)

10  continue

c---    read the new data; assume readnewdata reads a record of 
c---    data values

    ok = readnewdata(buffer)
    if (ok .eq. 0)then
c---      flip the temp, dewpt and direction
      call swbyt4(buffer(2), 3)
      call m0sxsend(4, n_vals)
      call m0sxsend(N_KEYS * 4, buffer)
      goto 10
    endif

Serving weather text data

The ADDE server, wtxgserv, processes a client request and sends back the text header containing information about the data and the actual weather text data. The McIDAS-X command WXTLIST is one command that accesses weather text data.

This server is delivered with the McIDAS-XCD package.

Weather text request syntax

The table below lists the client request syntax options for weather text data.

Keywords Description Remarks

APRO=

AFOS/AWIPS product headers to match

three characters; don't use APRO with the WMO keyword

ASTN=

AFOS/AWIPS stations to match

two or three characters

DAY=

most recent day to begin the search

ccyyddd format (default=current day)

DTIME=

maximum number of hours back in time to search

no default

MATCH=

list of character match strings to find from the text

 

NUM=

number of matches to find

default=1

PROD=

predefined product name

 

SOURCE=

circuit source

default=ALL

WMO=

WMO product headers to match

at least two characters; wildcard characters are allowed; don't use WMO with the APRO keyword

WSTN=

WMO stations to match

four characters

Special rules for transmitting weather text

If the day specified does not equal the current day, the search begins from the end of the day instead of the current time.

Text data is sent to the client as a blank-padded buffer.

The valid standard error values and messages for weather text are located in the range -45000 to -46999. See the wtxgserv source code for error message descriptions.

Converting the text header's format

The information in the table below must be included with each text header sent to the client.

Bytes Description Remarks

0 - 3

circuit source

blank-padded character string

4 - 7

number of bytes in the data section

 

8 - 11

file address where the data is located

usually not important to the client

12 - 15

time the data was ingested

hhmmss format

16 - 19

four-character WMO header

product code and country code

20 - 23

WMO product number

integer value

24 - 27

WMO station origin

four-character ICAO ID

28 - 31

AFOS product header

three characters

32 - 35

AFOS product location

two or three characters

36 - 39

AFOS product issuing station

three characters

40 - 43

Julian day of the data

ccyyddd format

44 - 47

number of bytes per line

usually 80

60 - 63

FAA catalog number

 

Transmitting weather text data to the client

Once all the data is found and formatted, the weather text can be sent to the client. Because TCP may timeout during periods of no data transmission, a heartbeat value (11223344) can be sent to the client periodically client maintain an active connection.

The server sends the client the following information:

The last three pieces of information are repeated until no more data is found.

The sample code below shows you how to set up your server to transmit weather text data.

 
char       *actual_request;
int         text_header[16];
char       *text;
int         req_length;
int         temp_int;

/* send back the client request */

req_length = strlen (actual_request);
temp_int   = req_length;
M0swbyt4 (&temp_int, 1);
M0sxsend (4, &temp_int);

length = 1;
while (length > 0)
{
  int total_bytes;

  /* read the length of the next text block */

  length = ReadNewTextBlock (text_header, &text);

  if (length > 0)
  {
    total_bytes = sizeof (text_header) + length;

    /* send the total data block length */

    M0swbyt4 (&total_bytes, 1);
    M0sxsend (4, &total_bytes);

    /* send the text header */

    M0sxsend (sizeof (text_header), text_header);

    /* send the text */

    M0sxsend (length, text);
    free (text);
  }
  else
  {
    temp_int=length;
    M0swbyt4 (&temp_int,1);
    M0sxsend (4, &temp_int);
    
  }
}

Serving observational weather-text data

The ADDE server, obtgserv, processes a client request and returns the text header containing information about the retrieved data, along with the observational weather-text data. The McIDAS-X command OBSRPT is one that accesses observational weather-text data.

This server is delivered with the McIDAS-XCD package.

Observational weather-text request syntax

The table below lists the client request syntax options for observational weather-text data.

Keywords Description Remarks

CO=co1 .. con

list of countries

2- character country IDs are read from COUNTRY.DAT, which is provided with McIDAS-XCD

ID=id1 .. idn

list of stations

 

IDREQ=

ID request type

must be set to LIST if CO, REG, or ID is specified; if a LATLON option is added to this server, specify GEO

NEWEST=day hour

most recent observation time to allow in the request

default=most recent observation filed

NHOURS=

maximum number of hours back in time to search from the value in NEWEST

no default

NPERIOD=

number of time periods to list

varies among data types

NUM=

number of matches to find for each station

default=1

OLDEST=day hour

oldest observation time to allow in the request

 

REG=reg1 .. regn

list of station regions

the regions list is stored in GROUPS.DAT, which contains the stations for a particular state/province

TYPE=

numeric value for the type of observation

varies among data types

Special rules for transmitting observational weather text

Don't specify both NUM and NPERIOD, or NPERIOD and NHOURS in the same request. If you specify NHOURS, you must specify NEWEST.

The valid standard error values and messages for observational weather text are located in the range -48000 to -48999. See the obgtserv source code for error message descriptions.

Converting the text header's format

The information in the table below must be included with each text header sent to the client.

Bytes Description Remarks

0 - 3

version number

currently zero

4 - 7

observation type number

varies among data types

8 - 11

active observation flag

0=inactive, 1=active

12 - 15

starting observation day

ccyyddd format

16 - 19

starting observation time

hhmmss format

20 - 23

starting observation hour

hhmmss format

24 - 27

ending observation day

ccyyddd format

28 - 31

ending observation time

hhmmss format

32 - 35

ending observation hour

hhmmss format

36 - 39

ID type flag

1 if ICAO ID

40 - 47

station ID

ccyyddd format

48 - 51

number of bytes of data

 

52 - 55

number of lines of data

 

56 - 95

reserved for future use

 

Transmitting observational weather-text data to the client

Once the data is formatted, the text data can be sent to the client. The server sends the client the following information:

This information should be repeated until no more data is found.

The sample code below shows you how to set up your server to transmit observational weather text data to the client.

    integer       header(24)
    integer       n_bytes
    integer       n_bytes_nbo
    character*80  line(1000)

100 continue

       ok = readnewdata(header, line)
       if (ok .eq. 0)then
          n_bytes = 96
          n_bytes_nbo = n_bytes
          call swbyt4(nbyte_nbo, 1)
          call m0sxsend(4, n_bytes_nbo)
          call m0sxsend(n_bytes, header)
          n_bytes = header(13)
          n_bytes_nbo = n_bytes
          call swbyt4(n_bytes_nbo, 1)
          call m0sxsend(4, n_bytes_nbo)
          call m0sxsend(n_bytes, line)
          goto 100
       else
          n_bytes = 4
          n_bytes_nbo = n_bytes
          call swbyt4(n_bytes_nbo, 1)
          call m0sxsend(4, n_bytes_nbo)
          call m0sxsend(4,0)
         endif

 


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