Documentation

Document Sample
Documentation Powered By Docstoc
					                                   Documentation
                                         for
                                  Pref Version 2.4x
                                     March 2008


1.0    General Information

Pref is a text product creator that works with two types of files, preformat templates and
product templates. It has similar features to an old MSDOS program, HABT when
working with preformats and has features especially suited for preformats with SHEF
data. However, product template files give Pref the ability to create almost any text
product from any data in AWIPS.

Pref supports two types of editing modes, preformat and edit. Preformats are text files
with data slots delimited by square brackets ([ ]) or braces ({ }) and are created using
any text editor. Preformat mode will only let you type inside of slots. When transmitted
to AWIPS, the square brackets are replaced with spaces (blank) and the braces are
deleted completely (strip). This is because some preformats, like ones for SHEF data,
cannot have spaces between data slots while others, like ones with data columns, need
to maintain the spacing. Thus, a single preformat can do both (blank and strip) in the
same product. Edit mode is like a normal text editor but it is limited to a line width of 69
characters. Edit mode does not have all the features of the AWIPS text editor and is
intended to make simple edits.

Product files are templates which contain Python code. The entire power of Python can
be used to create text products. To make programming easier for the product template
creator, a module is included for common AWIPS functions.

Both products and preformats can contain date and time variables which can be
automatically filled-in when they are first loaded or when sent to AWIPS. Variables can
be selected for UTC or local time. These variables can also be filled-in using a menu
command. For a list of the various date and time variable see Appendix 1.

Pref requires Python 2.3 or better and uses Tkinter, which is part of the AWIPS
software baseline.


2.0    User How-To

2.1    Optional Command Line Arguments

The program is started from the command line. You can optionally pass a filename to
load and the working directory. The command line looks like this:
./pref.py -d directory -f filename -a

working directory option
Pref accepts an optional working directory command line argument. If the argument is
present, Pref looks for files in that directory. If no working directory argument is given,
the working directory defaults to the current directory.

filename option
Pref loads the given file into the editor window. If the file is a preformat, the program will
come up in pref mode. If the file is a product template, the Python code will be executed
and the results seen in the editor window in edit mode. All preformats should have a
.pfm extension, and product templates should have .prd extension. Pref assumes any
file which contains a data slot ([ ]) or ({ }) is a preformat. If the output of the product
template contains data slot, the editor will be displayed in pref mode. Thus, it is possible
to create dynamic preformats using product templates.

automatic option
If the –a switch is included, the program will execute the product template file, load the
product, and send it to AWIPS without any user interaction. This option should be used
carefully. Even in automatic mode, Tkinter must work on the target machine. This mode
is only used for product template files.

2.2    Using Pref

Start Up
At start up, if a working directory and filename is given on the command line, the
program will display the file (Figure 1), otherwise the editor window will be empty.

Description of menus

File menu

       Open -          Show the open file dialog box. The box lists blank preformats
                       (.pfm extensions), preformats with data (.dat), product templates
                       (.prd) and all files. While the working directory is the default, the
                       user can move to different directories.

       Save -          Show the save file data dialog box. The box lists the same groups
                       as the open dialog box. This mainly is used to save partially filled-
                       in preformats and new blank preformats. Product template files
                       should be created and edited using a programming editor such as
                       nedit but simple edits can be made inside of Pref. If an extension
                       is not entered, the program will append .dat. This is true even if
                       another group is selected.
      Request -     Request a product from the AWIPS text database. The user can
                    choose to append the requested product to the end of the
                    workspace. If the editor window is not empty and has not been
                    saved or sent, the user will be warned before it is overwritten.

      Send -        Show the send preformat data dialog box (Figure 2). The box lets
                    the user type in an AFOS id. The program converts AFOS ids to
                    AWIPS ids. Pref is delivered using HandleOUP.pl for
                    transmission but it can be changed to use distributeProduct. The
                    user can also send the data to be stored in the local AWIPS text
                    product database without sending it out on the WAN, which uses
                    textdb.

                    The data in can be sent in three ways:

                    SHEF compressed -          SHEF comment lines and lines with all
                                               empty data slots are removed. Brackets
                                               blanked and braces are stripped. Empty
                                               SHEF .B groups are also removed
                                               including the .B and .END lines.
                    Remove blanks -            Lines with all empty data slots are
                                               removed. Brackets are blanked and
                                               braces stripped.
                    Convert slots -            All lines are sent but brackets are blanked
                                               and braces are stripped.

      Print -       The contents in the editor window are sent to lpt1. The workspace
                    is sent as is, no processing is done, ie. brackets and braces are
                    included.
      .
      Exit -        The program tries to exit. However, if the contents of the editor
                    had been modified since the last save or send, the program
                    warns the user.

Preformats Menu List every preformat (file ending with .pfm) found in the working
                    directory. To load a preformat into the editor window, click on the
                    desired file. If the editor window is not empty and has not been
                    saved or sent, the user will be warned before it is overwritten.

Product Menu        List every product template (file ending with .prd) found in the
                    working directory. To create a product, click on the desired file. If
                    the editor window is not empty and has not been saved or sent,
                    the user will be warned before it is overwritten.
Edit Menu

       Preformat -       The current editing mode is for preformats. Brackets and braces
                         are not displayed, data slots are highlighted in bold, and only
                         over-typing in slots is allowed.

       Edit -            The current editing mode is normal. All characters are displayed
                         in normal video and typing anywhere is allowed.

       Search -          Show the search target dialog box. If the user clicks on OK,
                         search from the beginning of the file for the target, using a case
                         insensitive search.

       Search again -    Search for the last target but start from the cursor forward.

       Local DateTime - Replace date time variables with the current local date and time.
       UTC DateTime - Replace date time variables with the current UTC date and time.

       Convert Slots -   Blank brackets and strip braces from a preformat. This is a quick
                         way of changing a preformat into a product. The user is warned
                         before the slots are converted.

       Clear -           Clear the contents of the editor window. If the contents have not
                         been saved or sent to AWIPS, the user is warned.

Help Menu

       Keystrokes -      Display an information box showing the special keystrokes.

       Datetime Variables - Display a list of all the date time variables

       About -           Display an information box about the program.


3.0    Troubleshooting Information

If there are problems in the initial start-up of the pref.py application, check these items:

                Python 2.3 or better installed at /usr/local/python/bin/python
                The command line is correct.
4.0   Installation Instructions

1.    Copy the installation file, pref2_4x.tar to /awips/dev/localapps.
      cp pref2_4x.tar /awips/dev/localapps


2.    Untar it.
      tar -xvf pref2_4x.tar


3.    This will create a new directory /awips/dev/localapps/pref, and copy all the files
      there.

4.    Using an editor, create your preformats using Appendix 2 as a guide.

5.    Using a programming editor, create your product templates. See Appendix 3 for
      more information.

6.    Create a shortcut to Pref and/or add Pref to your localapps menu in AWIPS.


5.0   Configuration Information

There are a set of global variables at the top of awips.py which can be altered by the
installer but should work with current version of AWIPS and should need no changes:

PRINTCMD = 'lp %s'
Command to send a file to the printer.

SAVECMD = '/awips/fxa/bin/textdb -w %s < %s'
Command to send a file to the AWIPS text database only.

READCMD= ’/awips/fxa/bin/textdb –r %s’
Command to request a product from the AWIPS text database.

SENDCMD = '/awips/fxa/bin/handleOUP.pl %s %s'
Command to send file out as an official user product.

LOOKUP = '/awips/fxa/data/afos2awips.txt'
File which lists old AFOS IDs with the WMO headers.

SQLCMD = ‘psql’
Command to do a SQL query on a AWIPS database.

DBNCMD = ‘/awips/hydroapps/public/bin/get_apps_defaults.LX db_name’
Command to get the name of the AWIPS hydrologic database.
The next nine variables at the top of pref.py deal with the colors and fonts used by the
program. While the defaults should work on all systems, the installer may want to
experiment with these values. Use only colors and fonts recognized by Tk.

PROTECTEDFG = 'black'
Color of text in the protected area, not in a slot.

PROTECTEDBG = 'lightblue'
Color of background of protected area.

PROTECTEDFONT = ('courier', 14)
Font of text in protected area.

EDITABLEFG = 'black'
Color of text in data slot.

EDITABLEBG = 'white'
Background color of data slot.

EDITABLEFONT = ('courier', 14, 'bold')
Font of text in data slot.

NORMALFG = ‘black’
Color of text in edit mode.

NORMALBG = ‘white’
Color of background in edit mode.

NORMALFONT = (‘courier’, 14)
Font of text in edit mode.

Preformats can be created using Pref or any other editor. They are simple and are
covered in Appendix 2. However, do not edit preformats with date/time variables with
Pref. Pref will convert the variables to the current date and time, destroying the
variables.

Creating product template files should be done with a programming editor, such as nedit
or idle. Product template files can be complex and are covered in Appendix 3.


6.0    Maintenance Information

No special maintenance is required.
7.0    Changes from Previous versions

1.1x
      Open dialog box is displayed if no filename is given on command line, working
       directory is appended to filename.
      Use global variables for colors and fonts

1.2x
      Add the edit mode
      Add fill-in UTC time option
      Add default AFOS ID option
      Enhance fill-in UTC time option
      Fix multiple .B SHEF header line bug
      Fix backtab bug on Linux
      Add extra options on Send dialog box setup line

2.0x
      Add product templates files
      Add automatic option
      Add Prefomats and Product menus
      Create awips.py and add methods and functions to it

2.1x
      Add local date/time, VTEC, and clear commands to Edit menu
      Add request command to File menu
      Avoid lazy matches in preformats for better performance
      Fix wordwrap bug
      Fix disappearing cursor bug
      Run product files in their own namespaces
      Add remove brackets command to Edit menu
      Add option to strip brackets instead of blanking them

2.2x
      Fix several product files
      Fix clear workspace bug
      Remove VTEC support
      Add Datetime variable help

2.3x
      Fix another wordwrap bug
      Improve Datetime variable support
      Fix path bugs
      Don’t delete blank lines in remove lines mode
      Use 12 point font
      Force focus after serach dialog
      Sort preformat and product menus

2.4x
      Support bracket blanking and brace stripping
8.0    Maintenance Information

Originating & Maintenance Programmer/Office:      Mike Callahan
                                                  WFO - Louisville, KY

9.0    Abbreviations and Acronyms

pfm       Blank prefomat file
prd       Product template file
dat       Filled-in preformat file with data
SHEF      Standard Hydrologic Exchange Format


10.0 References

Appendix 5: Man pages for handleOUP.pl and distributeProduct
http://www.nws.noaa.gov/mdl/awips/aifmdocs/APPENDIX05.htm

Instructions for using textdb
http://www.nws.noaa.gov/mdl/awips/aifmdocs/sec_4_F.htm



11.0 Figures




       Figure 1. Preformat mode                          Figure 2. Edit Mode
                               Figure 3. Send Dialog Box



Appendix 1         Date/Time Variables

These variables can be included in preformats and product templates.

Variable           Value                              Example
%a                 Abbreviated Weekday                FRI
%A                 Weekday                            FRIDAY
%b                 Abbreviated Month                  FEB
%B                 Month                              FEBRUARY
%d                 Day of Month                       04
%D                 Date                               02/04/05
%e                 Day of Month, blank padded          4
%H                 24 Hour                            07
%I                 12 Hour                            07
%j                 Julian Date                        121
%k                 24 Hour, blank padded               7
%l                 12 Hour, blank padded               7
%m                 Month Number                       09
%M                 Minute                             18
%p                 AM or PM                           AM
%S                 Second                             05
%T                 24 Hour Time                       07:18:05
%U                 Week Number                        06
%w                 Day of Week Number                 4
%y                 Two Digit Year                     04
%Y                 Four Digit Year                    2004
%Z                 Local Time Zone                    EST
%%                 a percent                          %
%-.                No padding
%_.                Blank padding
Appendix 2            Preformats

Preformats are simply text files with data slots. The data slots are marked with an
opening and closing bracket pair ([ ]) or brace pair ({ }). The brackets will take up a
space in the sent preformat, braces will not. If you want the program to fill in the current
date or time in line, see Appendix 1.

Below is an example of a simple preformat for SHEF precipitation data:

:>SDFRR1SDF 0 1 0
.B{R} SDF %y%m%d DH%H/PPDRZ
: ID   PCPN NAME
AAAK2[     ]:ATOWN
BBBK2[     ]:BVILLE
CCCK2[     ]:CBURG
.END

The top line is optional. If it starts with :>, then Pref will assume that the line holds the
settings for the Send dialog box for this product. The first word is the default AFOS ID
for this product. The first number is the desired mode; 0 - SHEF compressed, 1-
remove blank lines and slots, 2 – convert data slots (the default). The second number is
the date/time fill-in flag: 0 if you don’t want to fill in date/times (default), 1 if you want to
fill in dates and times with UTC, 2 if you want to fill in dates and times with local time.
The third number is local store flag: 1 if you want to store in the AWIPS text database
but not transmit the product, 0 if you want to transmit the product (default). Note, this line
only sets up the Send dialog box, the user can override these settings at sending time.

In the example above, the brackets will be blanked and braces will be stripped. The
brackets are used to maintain the columns for easier reading. The braces are used
because in SHEF a space is not allowed after the .B for the revision flag. In other words,
.BR SDF is correct, .B R SDF would generate an error.
Appendix 3            Product Template Files

Product template files are Python scripts which assign the final desired text string to a
variable, result. Therefore the last line always looks like this:

result = some_string

It is a good idea to include a header line at the top of the string similar to the top line of a
preformat. It tells the default product AFOS id, the mode of sending, the date/time replace
flag, and the local store flag. See Appendix 2 for more information. Here is an example:

result = ‘:> SDFCLINW4 2 0 1\n’ + the_rest_of_the_product

In order to make programming easier, several functions not in the standard Python library
are available to the product template programmer. To use these functions just add this line
to the top of the file:

import awips

Here is a list of the functions:

afosToAwips(AFOSid)
      Convert an AFOS id to an AWIPS id. Return None if the AFOS id is not found. The
      programmer should rarely use this function, since this will be called by send().

send(string, AFOSid, local=False)
      Send a string to AWIPS as product with the AFOSid. The function converts the
      AFOS id to the AWIPS id. If local is True, then the product is only stored in the
      AWIPS text database and not transmitted. The programmer should rarely use this
      function and let the user use the send dialog box, or use the automatic option.

request(AFOSid)
      Request an AWIPS text product and return as a string.

sql(query, dbname)
       Send a SQL query to an AWIPS database. If dbname is missing, assume the
       hydro database (IFHS). Return the data as a list of lists. For example: this query
       ‘select lid, name from location’ would return this list:

       [[‘ABEK2’, ‘Aberdeen’],[‘BLSK2’, ‘Blue Licks Spring’],[…,…]]

prin(string)
        Send a string to the printer, usually lpt1. Note: this function is not called ‘print’
        because this might cause some confusion with the standard Python print
        command.
res(regex, string)
       Preform a regular expression search or match on a string using regex. The
       function will return a tuple. The first member will be the matched string, the other
       members will be the matched groups. If there are no groups, the second member
       will be None. If there is no match, the function returns None. This function will
       simplify many regular expression tasks. For more complex tasks use the standard
       Python re module.

wordwrap(string, boundary)
     Word-wrap a string paragraph at a given boundary.

Product files should be straight-forward with no functions or classes. Complex product
files should place most of the Python programming into a pure python file (.py) in the
same directory as Pref, and import this file at the top of the product file.

As you can see, Pref can serve as a programming platform to generate almost any text
product using Python.

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:31
posted:12/10/2011
language:
pages:13