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.

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.

• If the position in the dataset is greater than zero, the client is expecting an absolute position number within the dataset.
• If the position in the dataset is less than zero or equal to zero, it is a time relative offset, with 0 being the most recent, -1 being the second most recent, etc.
• If the number of elements is 99999, assume the entire image object will be transmitted.
• If STYPE=VISR, then SPAC=1 and UNITS=BRIT. The prefix is not sent back unless DOC=Y.
• If the UNITS requested is BRIT, SPAC=1. If UNITS is TEMP/ALB, SPAC=2. If UNITS is RAD, SPAC=4.
• If the user asks for data in 2-byte format, but it can be sent back as 1-byte, send it as 1-byte and let the client handle the data expansion. This reduces the data volume sent across the network by half.
• If the request is larger than the source image file, pad the return image with zeros. Padding zeros is only required at the top or to the left of the image being transferred. If zeros are also needed to the right or the bottom of the image, they can be sent as zeros, or words 9 or 10 of the directory can be modified to indicate a smaller image than requested is being sent back (see table below). The client interface will then pad to the right and/or to the bottom of the image.
• If the request is larger than the source image file, pad the return image with zeros. If the server has problems fulfilling the request, use the standard error values and messages found in ~mcidas/src/adderror.doc . The range -11000 to -11999 lists error codes specific to image objects. 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 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.

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:

• 4-byte value containing the total number of bytes to be sent
• 256-byte image header
• navigation (variable length)
• calibration, if requested (variable length)
• image data lines, one at a time:
  line prefix (if requested)
  line of data
• 80-byte comment cards

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

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

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:

• 4-byte value containing the total number of bytes of data for the directory being sent (260 + (80 * NumberOfComments ))
• 4-byte value containing the file number for this image directory
• the 256-byte image directory
• the comment cards, blank padded to 80 characters

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

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

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.

• 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.
• If portions of the grid contain missing values, fill those locations with the value 0x80808080.
• Data must be delivered to the client in column-major format with the first data point in the upper-left corner of the grid.
• If the server has problems fulfilling the request, use the standard error values and messages found in ~mcidas/src/adderror.doc . The range -2100 to -21999 lists error codes specific to grid objects. 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 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:

• Multiple cycles of size 4, each followed by a heart beat; the cycles of size 4 and the heartbeat are optional
• 4-byte value containing the total number of bytes in the grid objects; the number of bytes transmitted is calculated as follows: (numgrids *260 + (total number of data points * 4)) + 8;
  the data size must be sent twice
• 4-byte value containing the number of grids to send to the client
• 256-byte grid header
• grid data object, which has a variable length, (number of rows *number of coulmns )*4
• 4-byte value containing zero

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)

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.

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.

• 4-byte value containing the total number of bytes to transmit
• 4-byte value of zero indicating a new file header is being sent; this information is repeated for each new file header to transfer and is sent after all grids from the previous file are transmitted
• 256-byte grid file header; this information is repeated for each new grid file header to transmit and is sent after the grids from the previous file are transmitted
• 4-byte value of zero indicating a new grid directory is being sent; this information is repeated before each grid directory in the file is sent
• 256-byte grid header; this information is repeated for each grid in the file being sent
• 4-byte value of 1 indicating no more grid directories in the 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)

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

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:

• 4-byte value containing the number of bytes of parameter names
  to be sent
• character string of NULL-separated parameter names
• 4-byte value containing the number of unit-string bytes to be sent
• character string of NULL-separated units
• 4-byte value containing the number of bytes of scaling factors
  to be sent
• array of integer scaling factors for each parameter
• 4-byte value containing the number of bytes of data to be sent
• n bytes of data

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

Weather text request syntax

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

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.

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:

• 4-byte value containing the length of the client request string; this lets users know how their request was expanded when the PROD keyword is specified
• the expanded client request string
• heartbeat value if needed
• 4-byte value containing the total number of bytes of data for this text block, including the 64-byte header and the text
• 64-byte text header
• n bytes of 80-character text, blank padded

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);
    
  }
}

Observational weather-text request syntax

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

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.

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:

• 4-byte value containing the length of the text header, which is currently 96; when all the data is sent, this value is reset to zero
• 96-byte text header
• 4-byte value containing the number of bytes of text to be sent
• n bytes of text; 80 characters per line, blank padded

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