1. 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 Composition of an application Creating applications –Information files –Making requests –Receiving notifications Developing applications Wrappers

2. WFO-Advanced Application Interface (original) 29 Apr 97 2 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

3. WFO-Advanced Application Interface (original) 29 Apr 97 3 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

4. WFO-Advanced Application Interface (original) 29 Apr 97 4 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.

5. WFO-Advanced Application Interface (original) 29 Apr 97 5 Applications May Use Any Language FORTRAN: PROGRAM CLEAR c D-2D Application c 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.

6. WFO-Advanced Application Interface (original) 29 Apr 97 6 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.

7. WFO-Advanced Application Interface (original) 29 Apr 97 7 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 along D-2D's execution PATH.

8. WFO-Advanced Application Interface (original) 29 Apr 97 8 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.

9. WFO-Advanced Application Interface (original) 29 Apr 97 9 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 | y fslInfo | FSL Information... | netscape | http://www.fsl.noaa.gov | n | n | n favorites | Favorite Products... | favorites | | n | n | y

10. WFO-Advanced Application Interface (original) 29 Apr 97 10 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# Baselines productButton: 12005# Distance Bearing productButton: 12006# Distance Speed appButton: setTime# Set the D-2D clock appButton: favorites# Favorite products app

11. WFO-Advanced Application Interface (original) 29 Apr 97 11 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.

12. WFO-Advanced Application Interface (original) 29 Apr 97 12 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 void main(){printf( “ hello,world\n ” );} $ someApp hello, world $ someApp D-2D (fxa process) standard output app input hello, world

13. WFO-Advanced Application Interface (original) 29 Apr 97 13 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

14. WFO-Advanced Application Interface (original) 29 Apr 97 14 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/wish pack [button.b -text “ Load METAR Plot ” -command {puts “ @@-Load 120 ” }]

15. WFO-Advanced Application Interface (original) 29 Apr 97 15 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

16. WFO-Advanced Application Interface (original) 29 Apr 97 16 Setting the Load Mode Syntax: @@-LoadMode mode The fxa process sets the load mode to the given mode. Values for mode: Latest run2Forced 8 Valid time seq3Forecast match 9 Previous run4Inventory10 Prognosis loop5Slot11 Analysis loop6Time resolution12 dProg/dt7

17. WFO-Advanced Application Interface (original) 29 Apr 97 17 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 – DGM type 2 – IFF

18. WFO-Advanced Application Interface (original) 29 Apr 97 18 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)

19. WFO-Advanced Application Interface (original) 29 Apr 97 19 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.

20. WFO-Advanced Application Interface (original) 29 Apr 97 20 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 $ simpleApp Enter your name: Portnoy Hello, Portnoy. $ simpleApp D-2D (fxa process) standard input app output load_mode 3

21. WFO-Advanced Application Interface (original) 29 Apr 97 21 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); }

22. WFO-Advanced Application Interface (original) 29 Apr 97 22 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.

23. WFO-Advanced Application Interface (original) 29 Apr 97 23 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.

24. WFO-Advanced Application Interface (original) 29 Apr 97 24 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.

25. WFO-Advanced Application Interface (original) 29 Apr 97 25 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

26. WFO-Advanced Application Interface (original) 29 Apr 97 26 Setup #!/usr/local/tk/bin/wish set 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

27. WFO-Advanced Application Interface (original) 29 Apr 97 27 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 both pack [label.load_mode.label -text “ Load mode: ” -anchor w] -side left pack [label.load_mode.current -textvar load_mode -width 15 -anchor w] \ -side left

28. WFO-Advanced Application Interface (original) 29 Apr 97 28 Setting Up Product Buttons set num 0 foreach 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 }

29. WFO-Advanced Application Interface (original) 29 Apr 97 29 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 2147614760 load_mode 3 blah, 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.

30. WFO-Advanced Application Interface (original) 29 Apr 97 30 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.

31. WFO-Advanced Application Interface (original) 29 Apr 97 31 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 0 2.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.

32. WFO-Advanced Application Interface (original) 29 Apr 97 32 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

33. WFO-Advanced Application Interface (original) 29 Apr 97 33 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.