1. Accelerator Controls Application Development
   1. * introduction to application programming & environment
   2. * background needed to start writing an application
   3. * tools to assist with program testing
   5. * this talk is located on WWW:
   6. https:///adwww.fnal.gov/controls/console_s/ tutorial/appintro.html
2. MECCA -- Source-Code Librarian
   1. * mecca/help ...to get help on MECCA
   2. * all code resides in, and built by, MECCA
   3. * provides tools to build and stage test versions
   4. * allows retreat to earlier versions; within limits
   5. * allows (mixture) languages FORTRAN and/or C
   6. * stores applications by unique number
      1. $ dir/col=1 mecca_src:[PA1420]
      2. Directory MECCA_SRC:[PA1420]
      3. CURR.DIR;1 [subdirectory of current version]
      4. HISTORY.TXT;1 [modification history]
      5. INFO.TXT;25 [program description]
      6. OLD1.DIR;1 [previous version]
      7. OLD2.DIR;1 [two versions back]
   7. * see page D15, program info window & more
3. Program Development Cycle
   1. * get a clean directory in your area
   2. * create source-code ...subject of next speaker
   3. * mecca/development ...details to follow
   4. * mecca/newpa
   5. * mecca/ipe
   6. * modifying a program...MECCA checks dates:
      1. source --> object --> executable
      2. xxx.c xxx.obj PAyyyy.exe
      3. (see example on next slide)
4. Example of Program Modification...1
   1. *mecca/copy pa1420
   2. *$ dir/col=1
   3. * Directory USR$SCRATCH:[JOSH]
      1. BUILD_Z_PAGE.COM;2 [command file to build test version]
      2. DESCRIP.MMS;26 [build dependencies; like UNIX make]
      3. LINK.OPT;3 [special link directives]
      4. PA1420.C;23 [a source file]
      5. PA1420.LIS;21 [a compiler listing file]
      6. SHOW_SERVICE_INFO.C;9
      7. SHOW_SERVICE_INFO.LIS;8
   4. *$ edit pa1420.c [...]
   5. *$ @build_z_page.com [this is what mecca/development does]
5. Example of Program Modification...2
   1. * $ mecca pa1420
      1. ============= MECCA version 4.2 =============
      2. Last modified by JWANG on 26-JUN-1995 09:23:34.81 from USR$DISKA:[JWANG.TEMP]
      3. Continue? <Y> N:
      4. No new files will be added to PA1420.
      5. Files to be updated for PA1420:
      6. PA1420.C;24
      7. Build new version of PA1420 for user JOSH.
      8. Last chance to get out before batch job is submitted!!
      9. Continue? <Y> N
6. Program Run Cycle
   1. * when mecca completes, your executable is placed for use
   2. * when user calls-up the program...
      1. stage: system copies new version to console, if needed
      2. load: system loads executable and delivers `initialize' interrupt
      3. runs: system continues to deliver `periodic' interrupts (15 Hz)
      4. end: system delivers a final `terminate' interrupt
7. Data Acquisition...1
8. Data Acquisition...2
   1. *front-ends return raw data; request data by `ftd':
      1. frequency-time descriptor: one-shot, periodic rate or global event
   2. *applications get data through a DataPoolManager process
      1. DPM communicates with front-ends; applications poll for return data
   3. *scaling comes from database; transparent to programmer
   4. *logical atom of control-system is the `device':
      1. device index is a unique integer that identifies a channel
      2. devices have properties: reading, setting, basic status, basic control...etc..
      3. devices also have a more common property; `device name'
      4. address data by combination of device and property
      5. see page D80 for database dump of a device
9. Getting Started
   1. *help
   2. *skeleton program
   3. *program environment
   4. *libraries
   5. *programming aids
10. Help
    1. *cns_intro
       1. readme.txt - lists files of interest
       2. getting_started.txt - step-by-step program development
       3. intro.txt - control system overview
       4. help_def.com - defines useful logicals and symbols
       5. skeleton programs
       6. example programs
    2. *World Wide Web
       1. overall - https:///adwww.fnal.gov/controls/libraries.html
       2. NEW_USER - https:///adwww.fnal.gov/controls/clib/new_user.html
       3. one line help - https:///adwww.fnal.gov/controls/clib/clib_oneline.html
    3. *other
       1. clibh, clib_doc, clib_oneline
       2. lib_find, mecca_search, mecca_search_c (CNS40 only)
11. Guidelines
    1. *Application Style Guide
       1. describes user interface expectations in terms of both appearance and functionality
    2. *Application Programming Guidelines
       1. describes standard coding practices for this environment
12. Skeleton Program
    1. *basic framework is an infinite event handling loop
    2. *events are served by calls to `window_intype' which should be called BEFORE any screen I/O routine
       1. initialization (occurs once)
       2. periodic (15 Hz)
       3. keyboard (return key or left mouse button)
       4. key up (always preceded by keyboard event)
       5. double click (always preceded by keyboard event)
       6. focus in and focus out of the window
       7. graphics window keyboard
       8. termination (occurs once)
13. Skeleton Program (continued)
    1. while (TRUE)
    2. {/* get next interrupt */
    3. window_intype(&window_id,&int_type,&row,&column,&info);
    4. switch (int_type)
       1. {
       2. case INTINI:/* initialization interrupt (event) */
       3. pgm_ini();
       4. break;
       5. case INTTRM:/* termination interrupt (event) */
       6. pgm_trm();
       7. break;
       8. case INTKBD:/* keyboard/user interrupt (event) */
       9. pgm_kbd();
       10. break;
       11. case INTPER:/* periodic interrupt (event) (~15Hz) */
       12. .
       13. .
14. Where should it run?
    1. *window vs. screen
       1. `screen' is an X window
       2. `window' can mean an X window or a portion of one
    2. *Primary Application
       1. best user interaction support
       2. owns one alphanumeric and two graphic windows/screens
       3. do NOT use touch panel window!
    3. *Secondary Application
       1. usually display/monitor only
       2. owns one graphic window/screen
    4. *Nonuser Application
       1. no visible display
       2. started up with console
15. Libraries
    1. *Do NOT use old/archaic CLIB routines! (TVM,LX,DPM,DBM,etc.)
    2. *routines can be called from either C or FORTRAN
    3. *routines with `_c' suffix are `C friendly' versions
    4. *top level topics
16. Anatomy of a Library Routine Help Entry
    1. *components of a help entry
       1. calling description with argument data types
       2. routine functional description
       3. verbose description of arguments
       4. description of returned status (if applicable)
       5. required header/include files
       6. related functions (hot links in WWW version)
17. Anatomy of a Library Routine Help Entry
    (continued)
    1. *each argument is listed as - name.data_type.passing_mechanism
       1. status.i4.v = str_is_blank_c(string.ch.d [,length.i4.v])
       2. (The complete description of possible values is in the `intro_help' help topic.)
    2. *arguments having the type `.ch.d' can be passed EITHER by descriptor or by reference
    3. *arguments enclosed by square brackets are optional
    4. *The default values of optional arguments should be listed in the help. Zero is NOT the universal default value.
18. Error Handling/Logging
    1. *ACNET errors are composed of two parts:
       1. facility: integer code that identifies the subsystem that emitted the error
       2. error: integer code that defines the specific error within the facility
       3. for example: 17 -10 indicates a timeout reported by DPM on setting a device
          1. (DPM_TMOSET is the ASCII version of this error code)
    2. *Primary Applications should include an error display window
       1. error_init(_c) - define error display format
       2. can map error messages to console and/or shared log files which can be viewed using `Pgm_Tools'
    3. *display errors with `error_display(_c)'
    4. *display user messages with `error_message(_c)'
19. Window Manager
    1. *manages usage of alphanumeric (TV) windows
    2. *background window always exists (WMNGR_BACKGROUND)
       1. should always set the background window size during initialization
    3. *coordinates are row and column (usually in that order)
    4. *origin for coordinates in a window is in the upper left hand corner
       1. origin coordinates for the background window are (1,1)
       2. origin coordinates for all other windows are (0,0)
    5. *physical vs. logical coordinates
    6. *windows are referred to by a two byte integer ID or handle
    7. *window text files can be edited on D10
20. Window Manager (continued)
    1. *basic routines
       1. window_enable_interrupts - enables automatic window management
       2. window_set_background_size(_c) - sets background window size
       3. window_construct(_c) - creates a new window (returns ID)
       4. window_tvm(_c) - reads or writes a text string (physical coordinates)
       5. window_delete(_c) - deletes a window
       6. window_display_value(_c) - displays a value (many data types) in a window
       7. window_input_value(_c) - inputs a value (many data types from a window)
       8. in_window_field(_c) - tests for an interrupt in a window field
       9. in_window_box(_c) - tests for an interrupt in a window region
21. Window Manager (continued)
    1. *scrolling routines
       1. window_enable_scroll_io(_c) - enable I/O to the window's scroll buffer
       2. window_entry_to_row_c - converts logical to physical row coordinates
       3. window_row_to_entry_c - converts physical to logical row coordinates
       4. window_write_line_c - writes text strings to sequential rows
       5. window_sequential_write_c - writes text strings either to the last accessed row or the next sequential one
       6. window_write_scroll_c - writes text strings in a scrolling terminal format
       7. window_printf_c - works like printf except that it supports embedded color
          1. codes as well as site specific conversions
22. Window Manager (continued)
    1. *highlighting routines
    2. *switch routines
    3. *menu bar routines
       1. use two back slashes (\\) to separate menu bar items
    4. *slider routines
    5. *select field routines
    6. *high level dialogs
       1. scroll_menu(_c) - popup menu
       2. decide(_c) - logical decision dialog (`caution user')
       3. winput(_c) - inputs multiple data types
       4. input_array_values_c - input arrays of different types
       5. acknowledge(_c) - simple acknowledge message dialog
       6. many more...
       7. can try out dialog routines using Example Program #5 on W5
23. WNLIB
    1. *manages usage of graphic (LX) windows
    2. *background window always exists (WN_BACKGROUND)
    3. *coordinates are X and Y
    4. *virtual coordinates
       1. define size and location of windows/view ports
       2. origin is in the lower left hand corner
       3. coordinate values range from 0.0 to 1.0
    5. *world coordinates
       1. real world/engineering coordinates within a window
       2. origin is in the lower left hand corner
       3. coordinate values are set by a call to `wn_world(_c)'
    6. *windows are referred to by a four byte integer ID or handle
24. WNLIB (continued)
    1. *normal function sequence
       1. wn_view(_c) - create window using virtual coordinates
       2. wn_world(_c) - establish real world/engineering units scaling
       3. wn_active(_c) - make this window the active drawing window
       4. execute drawing or other setup commands
    2. *only the active window can be drawn to
       1. even the background window must be activated before drawing on it
    3. *text coordinates can be either normal world coordinates or row and column coordinates
       1. set by calling `window_text_scaling_c'
    4. *simple plot support
       1. create window and labeled grid in one call using either `wn_grid(_c)' or `wn_quick_grid'
       2. plot a buffer of points by calling `wn_point_set'
25. WNLIB (continued)
    1. *data manipulation routines
       1. save/recall plotted data
       2. perform simple statistics on saved data
       3. fit saved data
    2. *cursor manipulation routines
    3. *switch routines
    4. *most features can be demonstrated by using the WNTEST program (D110)
26. DIO
    1. *accesses both `live' and database data
    2. *`live' data also requires the specification of a Frequency Time Descriptor (FTD)
       1. FTD_ONESHOT - retrieve the data once and if successful cancel the request
       2. FTD_1HZ * constant - retrieve the data at a periodic rate
       3. FTD_EVENT_MASK | clock_event - retrieve the data on the occurrence of the specified Tevatron CLocK (TCLK) event
    3. *caches static database information to improve program performance
27. DIO (continued)
    1. *simplest case - reading a single scaled value
       1. status = dio_get_dev_c(device_index,property,&value,FTD_ONESHOT);
       3. `device_index' can be obtained from the device name by calling the routine `dio_device_index(_c)'.
       5. `property' can be either reading (PRREAD) or setting (PRSET).
       7. `value' is the returned device value.
       10. The returned status is a standard ACNET status value. (DIO_OK -> success)
28. DIO (continued)
    1. *reading an array of scaled values - 3 steps
       1. build the list of requests and return the list ID
          1. status = dio_bld_get_c(&list_id,num_devices,device_indices,
             1. properties,errors,FTD_1HZ);
       2. read the list of values
          1. status = dio_get_lst(&list_id,values,errors);
       3. cancel the list of requests (not a one shot)
          1. dio_can_get_lst(&list_id);
    2. *DIO array status handling
       1. If status is DIO_OK, the operation was successful.
       2. If status is less than DIO_OK, there was an overall failure and the status value is a standard ACNET status value.
29. DIO (continued)
    1. *important routines
       1. dio_get_dev(_c) - retrieve a single scaled device
       2. dio_get_raw(_c) - retrieve a single raw device
       3. dio_get_array_device_c - retrieve a single array device
       4. dio_can_get(_c) - cancel a single device request
       5. dio_set_dev(_c) - set a single scaled device
       6. dio_set_raw(_c) - set a single raw device
       7. dio_set_array_device_c - set a single array device
       8. dio_can_set(_c) - cancel a single device setting request
       9. dio_bld_get - build a scaled device retrieval list
       10. dio_get_lst - retrieve a list of scaled devices
       11. dio_can_get_lst - cancel a retrieval list
       12. dio_bld_set - build a scaled device retrieval list
       13. dio_set_lst - retrieve a list of scaled devices
       14. dio_can_set_lst - cancel a setting list
30. Data Storage
    1. *relational database tables
    2. *accessed via calls to `db_send_c'
    3. *accessed using SQL
       1. `Visual Guide to SQL' by Trimble and Chappell, John Wiley and Sons
    4. *most appropriate if rows have limited number of fields
    5. *tables are created using Interactive SQL (ISQL)
       1. need account from Database Administrators
31. Simple Data Storage
    1. *for saved data totaling less than 256 bytes
    2. *primarily for saving simple user configuration data
    3. *`pgm_data_storage' - provides unique data for each console
    4. *`pgm_data_storage_shared' - provides the same data for every console
32. Data Conversions
    1. *numeric_to_ascii(_c) - convert values to ASCII
    2. *ascii_to_numeric(_c) - convert ASCII to numeric values
    3. *clib_sprintf - normal sprintf functionality plus many site specific conversions
33. User Libraries
    1. *stored in MECCA like applications
    2. *object linked to applications
    3. *examples
       1. ul_cbsaux - generally useful routines, similar to CLIB
       2. ul_windowlib - extensions to window_manager routines
       3. ul_dialoglib - more high level dialog routines
       4. ul_friglib - access routines for the refrigerator systems
34. Development Aids
    1. *cc/standard=portable
       1. use this from the beginning of development
       2. checks for portability problems
       3. eliminate all problems generating portability problems
    2. *lint - `lcl_lint output_file source_file'
       1. finds logic and portability problems that the compiler misses
       2. may save lots of time in the long run
       3. use this from the beginning of development
    3. *useful applications
       1. D10 - supports interactive layout of text windows
       2. WNTEST (D110) - allows interactive use of WNLIB routines
       3. Window Manager TST (D133) - allows interactive use of window_manager routines
       4. Example Program #5 (W5) - allows interactive use of dialog routines
35. Testing and Debugging
    1. *Z index
    2. *debug_slot
    3. *settings lock
    4. *redirection
    5. *peeker programs
36. Z index, D7
    1. *testing and debugging
    2. *mecca/development to Z index or D7
    3. *Z index
       1. cleared each morning at 3 a.m.
       2. listed by author and PA number
       3. use normal PA number; Z index version is distinct
    4. *D7 Quick-SA-Test
       1. next launch debug version
       2. cleared on next index load
    5. *select a debugger display method
       1. debug_terminal
       2. debug_window
37. debug_slot
    1. *debug_terminal vs debug_window
       1. CNS40> debug_slot
       2. Select a slot to debug as follows:
       3. 1 = PA A
       4. 2 = GRAPHICS 1 SA
       5. 3 = GRAPHICS 2 SA
       6. 4 = ALARMS slot
       7. 5 = PA B
       8. Slot number: 1
       9. Start up the application to be debugged.
       10. Use CONTROL/C to break into executing program.
       11. OpenVMS VAX DEBUG Version V6.2-000
       12. %DEBUG-I-INITIAL, language is C, module set to PA0758
       13. DBG>
38. debug_slot (cont'd)
    1. SRC: module PA0758 -scroll-source
    2. 11454: while (TRUE) {
    3. 11455: window_intype(&mwid, &type, &row, &col, &info);
    4. 11456: switch (type) {
    5. 11457: case 1:
    6. 11458: intype_initialize(FALSE,FALSE);
    7. ->1459: break;
    8. 11460: case 2:
    9. 11461: intype_terminate(row,col);
    10. 11462: break;
    11. 11463: case 3:
    12. 11464: intype_interrupt(row,col);
    13. OUT -output
    14. DBG> Step
39. debug_slot (cont'd)
40. Settings Lock
    1. *is it pertinent?
       1. console class determines some privileges
       2. able to run a progam (not white index page entry)
       3. able to set from program (index page entry is cyan)
       4. database permit (by console class, little used)
    2. *choices are privilege dependent
       1. disable 5 minutes 15 minutes
       2. 1 hour 8 hours forever
       3. remote
    3. *choose minimum
    4. *settings are logged
41. Redirection
    1. *redirect data acquisition
       1. modify node and SSDN
       2. settings not forwarded to database
       3. settings not logged
       4. utility window lock
       5. check out help on D128
       6. yellow slash
    2. *mirror
    3. *test settings
    4. *test progam flow
    5. *test program error handling
42. Peeker Programs
    1. *datapool peek, D3
       1. useful to track memory and pool leaks
       2. formatted dump
       3. show process/remote peek
    2. *CLIB Peeker, D22
       1. WNLIB
       2. WMNGR
       3. database
       4. error
       5. process
       6. fshare
    3. *DIO Peeker, D114
    4. *Clockscope, D33
    5. *Database Dump, D80
43. Finishing Touches
    1. *on-line help
    2. *demo script
    3. *abstract
44. On-line Help
    1. *check out index page, D43, D44
    2. *creation
       1. press help button
       2. press editor button
          1. select normal text
             1. fill in `about this program', exit and save
          2. select topic names
             1. select create, enter topics, exit and save
          3. select a topic
             1. select normal text and add help text, or ...
             2. select topic names and create 2nd level of help
    3. *editor has replace and insert modes
    4. *row/column help likely to move to bubble help
45. Demo Script
    1. *consider introduction to your program
    2. *multiple demos eases edits
    3. *creation of a script
       1. normal, restart ... help is available
    4. *insert button action during recording
       1. program pause
       2. settings and file write locks
       3. display image
       4. display text message
    5. *deletion of a script
       1. recording again has option to delete
    6. *playing script
       1. Pgm_Tools
       2. menu of scripts
       3. speed control
46. Abstract
    1. *check out D15 Show Service Information
    2. *check out sequencer, C48
    3. *something more than help

Security, Privacy, Legal