WFO-Advanced Application Interface (original) 29 Apr 97 1 The D-2D Application Interface What's a D-2D application? Current applications Requests and notifications

WFO-Advanced Application Interface (original) 29 Apr 971

The D-2D Application Interface

• What's a D-2D application?• Current applications• Requests and notifications• Composition of an application• Creating applications

– Information files– Making requests– Receiving notifications

• Developing applications• Wrappers


What's a D-2D Application?

• Any program run by D-2D– Specifically, run by the fxa process of D-2D– In this way, D-2D acts as a shell

• Cannot draw directly on an IGC display area– Can create gridded data on-the-fly and load as

contour or image– Can display its own user interface, or none at all

• Applications make requests to and receive notifications from D-2D

• Written using any language• Off-the-shelf software can become D-2D

applications– Little or no modification necessary– Developing a wrapper can simplify application

integration


D-2D Applications

• Volume browser• Product maker• Interactive Skew-T • Text window• Interactive snow • Radar applications

– RPS list editor, one time request, alert request • D-2D dialog boxes

– Print with options, select user ID, time setter, procedure deleter, D-2D version

• FXA initializer


Requests and Notifications

• Applications don't have to be merely programs run

by D-2D - they can interact with D-2D. • They may make requests of D-2D: commands that

ask D-2D to perform certain actions. • They may receive notifications from D-2D:

messages that inform an application of changes in the state of D-2D.

• Applications aren't obligated to make requests.• They aren't obligated to properly receive and

interpret notifications. • Requests and notifications use the standard

input/output channels available to any Unix process.


Applications May Use Any Language

• FORTRAN: PROGRAM CLEARc D-2D Applicationc when run, it clears the main IGC window. PRINT*, '@@-Clear' STOP END

• Java: // D-2D Application that clears the main IGC window.class Clear { public static void main(String[] argv) { System.out.println(“@@-Clear”); } }

• Bourne shell script:#!/bin/sh# D-2D Application: clears the main IGC window.exec echo “@@-Clear”

• Any program - even those for which you don't have access to the source code - can be a D-2D application.


Composition of an Application

• Applications are identified by application keys.• Application keys are listed in the application

information file.• The D-2D menu has entries for application

buttons, which use an application key.• Application buttons launch applications.• A running application is "connected" to D-2D: its

standard input receives notifications from D-2D and its standard output sends requests to D-2D.

• Some applications may be prestarted.• Some applications may be automatically restarted.• D-2D may allow only one instance of some

applications to run at any one time.


Creating Applications

1. Assign an application key and enter it in the

application information file. Pick a place on

the D-2D menus for the application to appear

and add it to the menu configuration file. 2. Create the application.

- Write one from scratch.- Use an existing program verbatim, or modify it.- Develop a wrapper around an existing program.

3. Install the application somewhere alongD-2D's execution PATH.


Information Files: Application Key

• Each application gets a unique application key. • Application keys are text strings.• Examples:

– Volume browser: vb– Product maker: maker– RPS list editor: rps

• Add an entry to $FXA_HOME/data/appInfo.txt • These keys are not site-specific.


Format of the Application Info File

• The format of appInfo.txt is:key I label I executable I arguments I prestart I restart I one-instance– key is the application key (a text string) – label is the label D-2D will use on its menus for launching the

application – executable is the file to execute– arguments are command-line arguments for the executable– prestart tells whether to start the application when D-2D itself

starts– restart tells whether D-2D should restart the application if it

ever terminates– one-instance tells whether D-2D will allow only one copy of the

application to be running at any one time • Example

vb | Volume Browser... | vb | | y | y | yfslInfo | FSL Information... | netscape | http://www.fsl.noaa.gov | n | n | nfavorites | Favorite Products... | favorites | | n | n | y


Information Files: Menus

• The file $FXA-HOME/data/localization/nationalData/

datamenus.txt specifies the layout of all the menus in

the menu bar after the "Scale" menu.• Edit this file and add an entry for your application.• The syntax is simple; see the file for details.• Add your entry by application key.• Example:

menu: ”Tools”productButton: 12002 # BaselinesproductButton: 12005 # Distance BearingproductButton: 12006 # Distance SpeedappButton: setTime # Set the D-2D clockappButton: favorites # Favorite products app


Restart D-2D

• The files…o appInfo.txt o dataMenus.txt

are read once, at start-up time of the D-2D display software. After making changes, you must restart D-2D in order for the system to see your updates.


Making Requests

• D-2D monitors the standard output of applications. • Normally, a program's standard output is the screen:

• D-2D intercepts the standard output and attempts to parse it:

xterm$ cat someApp.c#include <stdio.h>void main(){printf(“hello,world\n”);}

$ someApphello, world$

someApp D-2D (fxa process)

standard output

app input

hello, world


Making Requests

• Making a request is as simple as printing text to

standard output. • D-2D looks for requests that start with the special

characters “@@-”• D-2D ignores any text it doesn’t recognize.• The current set of requests are limited but

expandable:– Load– Set load mode– Export loaded data– Print display area– Clear display area– Set and request the user ID


The Load Request

• Syntax:@@-Load depict-key...

• IGC loads the products represented by each depict-key.

• You can list more than one depict key; just separate each with space.

• Example: Tcl/Tk script that loads METAR plot when button is pressed:

$!/usr/local/tk/bin/wishpack [button .b -text “Load METAR Plot” -command {puts “@@-Load 120”}]


Loading On-The-Fly Grids

• The load command also lets you load grids your

application generates on-the-fly.• Your application should make a NetCDF file

containing the grid in the file/tmp/productMaker.nc

• To load it as a contour, issue the request@@-Load 13000

To load it as an image, issue the request@@-Load 13020


Setting the Load Mode

• Syntax:@@-LoadMode mode

• The fxa process sets the load mode to the given mode.

• Values for mode:Latest run 2 Forced 8Valid time seq 3 Forecast match 9Previous run 4 Inventory 10Prognosis loop 5 Slot 11Analysis loop 6 Time resolution 12dProg/dt 7


Exporting Data

• Syntax:@@-export type

• The main IGC will export data of the given type.• Exported data is written to temporary files, in a

format convenient to that type.• Export of data is controlled by depictable in the IGC

process displaying that data.• In response to this request, the application receives

the exported data notification.• There’s only one kind of type so far: type 0, which is

skew-T data.type 1 – DGMtype 2 – IFF


The Print Request

• Print the main IGC display in PostScript format:@@-Print ‘dest’ mvi density copies scale landscape color manual invert

– dest is the destination of the printout: a file name or if the first character is a vertical bar, then the name of a program that will read the PostScript as its standard input

– mvi is the minimum viewable increment (magnification): 1.0 is a good value

– density is density of information: 1.0 is a good value– copies is the number of copies to set in the PostScript output– scale is the scale factor to use: 100 is a good value– landscape is 1 if the printout should be in landscape orientation,

0 for portrait– color tells whether to print color (1) or grayscale (0)– manual tells whether to enable manual feed on the printer (1) or

not (0)– invert tells whether to invert blacks and whites (1) or not (0)


Miscellaneous Requests

• Clear the main display@@-Clear

• Set the current user ID:@@-UserID userID

You can find userIDs in the file $FXA_HOME/data/fxa-users• Get the current user ID:

@@-ReqUserID

The application making this request receives a user ID notification.


Receiving Notifications

• Receiving notifications is as easy as reading standard

input.• Normally, a program's standard output is the keyboard:

• D-2D attaches an application’s standard input to itself:

xterm

$ simpleAppEnter your name: PortnoyHello, Portnoy.$

simpleApp D-2D (fxa process)

standard input

app output

load_mode 3


Receiving Notification

• All notifications are easily parsable plain text. • Notifications arrive asynchronously.

– If your application displays a user interface or otherwise can’t block waiting for data, you must arrange for your standard input to be non-blocking.

– In most user interface toolkits, you can register a callback function that will be called when a file descriptor (such as standard input) becomes ready to read.

– For example, if you’re using Motif:void read_D2D_notification(XtPointer ignore, int* ignore, XtInputId* ignore) { char buffer [256] gets (buffer); // Do something with buffer}...main() { ... XtAppAddInput (appContext, 0, XtInputReadMask, read_d2d_notification, 0);}


Exported Data Notifications

• Syntax: exported file...• Each file is the full pathname to the exported data.• There can be more than one file if there was more

than one overlay loaded that could export data of the requested type.

• There can be no files – which means no overlays were loaded that could export data of the requested type.

• Received only by the application that sent the@@-Export request.


Visibility Notification

• Syntax: visible• The application information file lets you specify

that only one instance of certain applications may be running at once.

• When the forecaster selects such an application, the process is started if it isn’t already running.

• If it isn’t already running, this notification is sent to the process.

• In response, the process should deiconify and raise whatever user interface windows it might have.


Miscellaneous Notifications

• Scale changes– Syntax: set_scale newscale– The newScale is an index into the scale table.– Received by all running applications.

• Load mode changes– Syntax: load_mode newMode– The newMode is the same number used in the

@@-LoadMode request.– Received by all running applications.

• User ID– Syntax: USER: userID– Received only by the application that sent the

@@-ReqUserID request.


Developing Applications

• Sample application: favorite product loader

• Notifications from D-2D update the load mode display. • Buttons load some “favorite” products.• Written in Tcl/Tk.

Favorite Products

Load mode: Valid time seq

METAR

Nowrad

IR Satellite

ETA 3-Pack


Setup

#!/usr/local/tk/bin/wishset load_mode_labels(2) “Latest run”set load_mode_labels(3) “Valid time seq”set load_mode_labels(4) “Previous run”set load_mode_labels(5) “Prognosis loop”set load_mode_labels(6) “Analysis loop”set load_mode_labels(7) “dProg/dt”set load_mode_labels(8) “Forced”set load_mode_labels(9) “Forecast match”set load_mode_labels(10) “Inventory”set load_mode_labels(11) “Slot”set load_mode_labels(12) “Time resolution”

set load_mode “Unknown”

wm title . “Favorite Products”wm resizable . 0 0


Setting Up the Notification Receiver

proc read_d2d_notification {} { if {[eof stdin]} { exit 0 }

set notification {gets stdin} switch -glob -- $notification { load_mode* { set new_load_mode [lindex $notification 1] global load_mode load_mode_labels set load_mode $load_mode_labels($new_load_mode) } default { return } }}

fileevent stdin readable read_d2d_notification

pack [frame .load_mode] -side top -fill bothpack [label .load_mode.label -text “Load mode:” -anchor w] -side leftpack [label .load_mode.current -textvar load_mode -width 15 -anchor w] \ -side left


Setting Up Product Buttons

set num 0foreach depict_key {120 200 801 *2147614752 2147614808 2147614760*} \ label {“METAR” “Nowrad” “IR Satellite” “ETA 3-Pack”} {

pack [button .button$num -text $label \ -command “puts ‘@@-Load $depict_key’”] -fill x incr num}


Favorite Products

Load mode: Valid time seq

METAR

Nowrad

IR Satellite

ETA 3-Pack

xterm

$ favorites@@-Load 120@@-Load 200@@-Load 801@@-Load 2147614752 2147614808 2147614760load_mode 3blah, blah, blah

Testing the Application

• It’s easiest to test an application without D-2D. • Type notifications by hand and see if the

application reacts correctly.• Press the app’s buttons and see if it produces

the correct output.


Developing a Wrapper

• For use when modifying an existing program is

difficult or impossible.• Abstractly, it translates requests the program

makes into D-2D requests, and D-2D notifications into notifications the program can accept.

• May convert file formats or serve other functions.• Typically a script.• The wrapper is the application as far as D-2D is

concerned.


Wrapper Example

• Interactive Skew-T Program (ISP).• ISP accepts a single skew-T file as a command-line

argument.• The ISP Wrapper script is the D-2D application.

1. On start up, it sends an export request: @@-Export 02. It waits for the exported notification.

– If there was exactly one file in the notification, it executes ISP on that file.

– If there weren’t any files, it displays a dialog box saying that no skew-T data was loaded.

– If there was more than one file, it displays a dialog box listing each file. The forecaster can select one file; it then executes ISP on that file.


Summary

• What is a D-2D application• Current applications• Requests and notifications• Composition of an application• How to create an application

– Information files– Requests applications can make– Notifications applications can receive

• Sample application• Wrappers


End Notes

This document was created April 1997, no

doubt by Sean Kelly. The material was used

for a presentation to the Taiwan CWB, and is

included in a spiral-bound document titled

“WFO-Advanced Seminar.” It was recreated

December 2005 by John Osborn from a 4-up

hard copy. The blue text on slide 17 was

hand-written annotation by Herb Grote,

probably added on the trip. The most recent

edits are by Joe Wakefield, March 2006.

Documents

WFO-Advanced Application Interface (original) 29 Apr 97 1 The D-2D Application Interface What's a D-2D application? Current applications Requests and notifications