McIDAS Programmer's Manual
Version 2003

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


Text data

Text data stores a variety of information for the McIDAS-X user, such as:

McIDAS-X has two types of text data: flat-file text and general weather text. Both are described in this section along with:

Flat-file text

Flat-file text is the simplest text data available in McIDAS-X. It is used most often on the server machine to convey administrative or configuration information to the user. The McIDAS-X READ command accesses this text.

The data is stored on the server machine as a simple ASCII file that can be manipulated with any file editor. It is delivered to the client one line at a time. There is no practical limit to the length of an individual line.

The table below lists the McIDAS-X library functions for flat file text.

Function Description

M0textgt

opens a connection to read a flat file

M0txtread

reads the text data one line at a time

M0PrintTextFromServer

opens a connection to read a flat file and prints the file contents to the McIDAS-X Text Window

Opening a connection to read a flat file

Because there is a one-to-one relationship between the ADDE dataset name created on the server and the file being served, no selection conditions are needed to access most flat files. Only the dataset name is required.

The ADDE interface to flat-file text is through the function M0textgt. It has one selection condition, FILE=, which can be used to access files that don't have specific dataset names in ADDE. The WXTLIST command with the DIR option is the only command that uses this selection condition.

Reading the text data

Once the connection is opened with M0textgt, the M0txtread function is called continuously until no more lines of text data are found. The code example below demonstrates the M0textgt/M0txtread function pair.

char  *dataset;
char **selects;
int    ok;
.
.
.
ok = M0textgt (dataset, n_select, selects, 1)
;
if (ok < 0)
{
  return (ok);
}

while (ok == 0)
{
  char   line[1000];
  ok = M0txtread (line, sizeof (line))
;
  if (ok == 0)
  {
    Mcprintf ("%s\n", line);
  }
}

General weather text

General weather text is composed of information compiled by weather agencies and distributed to the user community. It typically contains forecasts, public announcements, advisories and warnings. In McIDAS-X, this type of data is ingested and made available from a server running McIDAS-XCD and can be accessed by the user with the McIDAS-X command WXTLIST.

WMO format standards

Because weather agencies provide this data, certain WMO format standards must be used during transmission. The sample text below demonstrates the WMO formatting standards used for text data transmission.

FPUS1 KMKE 251641
SFPWI
WIZALL-252200-
STATE FORECAST FOR WISCONSIN
1040AM CST SAT JAN 25 1997
...LAKE SNOW WARNING IRON COUNTY IN THE LAKE SUPERIOR SNOW AREA
TODAY..
.TODAY... WINDY AND COLD WITH AREAS OF LIGHT SHOW OR FLURRIES.
HEAVIER SQUALLS IN THE LAKE SUPERIOR SNOW BELT OF IRON COUNTY.
HIGHS SINGLE DIGITS NORTHWEST TO THE TEENS EXTREME EAST.

WMO header line

The first line of text is the WMO header line. In the example above, the first two characters, FP, contain the WMO product header. Most WMO product headers begin with one of the following characters:

WMO product header Description

A

advisory

C

climatic

F

forecast

N

notice

R

river

S

surface

T

satellite

U

upper air

The second character of the WMO product header will vary. The third and fourth characters are usually the country code (US) of the bulletin. The country code is followed by a product number (5), which further specifies the type of bulletin being transmitted. The product number is followed by the ID of the station initiating the bulletin (KMKE). The final six digits are the day of the month and time of the bulletin (251641).

AWIPS header line

The second line of the bulletin is an AWIPS header inserted by the U.S. National Weather Service; it is optional. The first three characters are the product code (SFP). The next two or three characters contain the state/province or the station the report is valid for (WI).

General weather text functions

The table below lists the McIDAS-X library functions for reading general weather text.

Function Description

M0wtxget

opens a connection to read the text

M0wtxread

reads the text

Opening a connection to read general weather text

In ADDE, the M0wtxget function opens a connection to the server. This function takes a variety of selection conditions, allowing the user to limit the amount of data searched to fulfill a user request. The more information specified in the selection conditions, the faster the search will be. The valid selection conditions are described in the table below.

Selection clause Description Remarks

APRO=p1 .. pn

list of AWIPS product types to match

three characters; don't use with WMO=

ASTN=s1 .. sn

list of AWIPS station IDs to match

two or three characters

DAY=

most recent day to search

 

DTIME=

maximum number of hours of reports to search

 

MATCH=match1 .. n

list of strings within the body of the text to match

if more than one match string is requested, all match strings requested must be found in each text block for a successful return

NUM=

maximum number of text blocks to list

 

PROD=

predefined product name

to list the available predefined products, use WXTLIST DIR

SOURCE=s1 .. sn

list of circuit sources

seldom used

WMO=w1 .. wn

list of WMO headers to match

minimum of two characters; wildcard characters are allowed; see the help for the WXTLIST command; can't be used with APRO=

WSTN=s1 .. sn

list of WMO station IDs to match

four characters

Reading the text

Once M0wtxget opens the connection, the application makes repeated calls to M0wtxread until all matching text products are received. Each call to M0wtxread returns the actual text along with a 64-byte header containing information about the text data. The components of the header are described in the table below. Note that all character strings are sent blank padded.

Bytes Description

0 - 3

circuit source

4 - 7

number of bytes of data

12 - 15

time of day that the data was received, hhmmss

16 - 19

4-character WMO product ID, such as FPUS

20 - 23

product number

24 - 27

4-character WMO station ID

28 - 31

3-character AWIPS product ID

32 - 35

2- or 3-character AWIPS station ID

36 - 39

3-character product origin (optional)

40 - 43

Julian day of the data

44 - 47

number of bytes per line

60 - 63

FAA catalog number (optional)

The sample code below demonstrates an ADDE general weather text request.

char   **selects;
char    *text;
char     t_string[64];
char     header[64];
int      n_selects;

selects = VecNew ();
sprintf (t_string, "DAY=%d", current_day);

/*
 * we are going to acquire the State Weather Roundups (SWR) from 
 * Wisconsin, Minnesota and Michigan.
 */

selects   = VecAdd (selects, t_string);
selects   = VecAdd (selects, "APRO=SWR");
selects   = VecAdd (selects, "ASTN=WI MN MI");
selects   = VecAdd (selects, "NUM=3");
n_selects = VecLen (selects);

ok = M0wtxget ("RTWXTEXT", n_selects, selects, 1); 
if (ok < 0)
{
  Mceprintf ("No data found\n");
  return (2);
}

while ((ok = M0wtxread (header, &text)) == 0) 
{

  /* text found, do something */

  free (text);
}

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