Text data

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.

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).

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