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