Accelerator Controls Application Development

* introduction to application programming and environment
* background needed to start writing an application
* tools to assist with program testing

* this talk is located on WWW:
https://www-bd.fnal.gov/controls/console_s/tutorial/appintro.html

MECCA -- Source-Code Librarian

* mecca --help ...to get help on MECCA (also see https://www-bd.fnal.gov/controls/linux/mecca.html)
* all code resides in, and built by, MECCA
* provides tools to build and stage test versions
* allows retreat to earlier versions; within limits
* allows (mixture) languages C++ and/or FORTRAN
* stores applications by unique number

dir /usr/local/mecca_head/mecca/pas/pa1420

    drwxrwsr-x  17 xconsys xcons0   4096 Mar  2 12:55 archive/     [archive directories]
    -rw-rw-r--   1 xconsys xcons0     30 Jun  3  2011 depends.opt  [library dependencies]
    -rw-rwxr--   1 xconsys xcons0     52 Apr 22  2005 options.opt  [build options]
    -rwxrwxr-x   1 xconsys xcons0 200040 Mar  2 12:55 pa1420       [current executable]
    -rw-rw-r--   1 xconsys xcons0  94596 Feb 18  2016 pa1420.cpp   [source file]




* see page D15, program info window and more

Program Development Cycle

* get a clean directory in your area
* create source-code ...subject of next speaker
* mecca --development ...details to follow
* mecca --newpa
* index page editor

* modifying a program...MECCA checks dates:

source --> object --> executable
xxx.cpp xxx.o payyyy
(see example on next slide)

Example of Program Modification...1

* mecca --copy pa1420
* $ dir
* Directory

-rw-r--r--   1 hendricks controls     160 Feb 18  2016 build_results.txt    [results from last build]
-rw-rw-r--   1 hendricks hendricks     30 Apr 18  2013 depends.opt          [library dependencies]
-rw-r--r--   1 hendricks controls      52 Apr 22  2005 options.opt          [build options]
-rwxrwxr-x   1 hendricks hendricks  94596 Feb 18  2016 pa1420.cpp           [a source file]
-rwxrwxr-x   1 hendricks hendricks    541 Apr 18  2013 pa1420.h             [a header file]
-rwxrwxr-x   1 hendricks hendricks 199844 Feb 18  2016 pa1420               [executable file]






* $ edit pa1420.cpp [...]
* $ mecca --development [builds a test version of the program]

Example of Program Modification...2

* $ mecca pa1420

The following files will be modified:
pa1420.cpp
The following files will be added:
The following files will be removed:
DO YOU WISH TO CONTINUE(Y)?
y


Program Run Cycle

* when mecca completes, your executable is placed for use
* when user calls-up the program...

stage: system copies new version to console, if needed
load: system loads executable and delivers `initialize' interrupt
runs: system continues to deliver `periodic' interrupts (15 Hz)
end: system delivers a final `terminate' interrupt

Data Acquisition...1

Data Acquisition...2

* front-ends return raw data; request data by `ftd':

frequency-time descriptor: one-shot, periodic rate or global event

* applications get data through a DataPoolManager process

DPM communicates with front-ends; applications poll for return data

* scaling comes from database; transparent to programmer
* logical atom of control-system is the `device':

device index is a unique integer that identifies a channel
devices have properties: reading, setting, basic status, basic control...etc..
devices also have a more common property; `device name'
address data by combination of device and property
see page D80 for database dump of a device

Getting Started

* help
* skeleton program
* program environment
* libraries
* programming aids

Help

* cns_intro

readme.txt - lists files of interest
getting_started.txt - step-by-step program development
intro.txt - control system overview

skeleton programs
example programs

* World Wide Web

overall - https://www-bd.fnal.gov/help/
NEW_USER - https://www-bd.fnal.gov/help/ul_clib/new_user.html
one line help - https://www-bd.fnal.gov/help/ul_clib/oneline.html

* other

clibh, clib_doc, clib_oneline
lib_find, mecca_search, mecca_search_c (CNS40 only)

Guidelines

* Application Style Guide

describes user interface expectations in terms of both appearance and functionality

* Application Programming Guidelines

describes standard coding practices for this environment

Skeleton Program

* basic framework is an infinite event handling loop
* events are served by calls to `window_intype' which should be called BEFORE any screen I/O routine

initialization (occurs once)
periodic (15 Hz)
keyboard (return key or left mouse button)
key up (always preceded by keyboard event)
double click (always preceded by keyboard event)
focus in and focus out of the window
graphics window keyboard
termination (occurs once)

Skeleton Program (continued)

while (TRUE)
    {/* get next interrupt */
    window_intype(&window_id,&int_type,&row,&column,&info);	
    switch (int_type)
        {
        case INTINI:		/* initialization interrupt (event) */
            pgm_ini();
            break;
        case INTTRM:		/* termination interrupt (event) */
            pgm_trm();
            break;
        case INTKBD:		/* keyboard/user interrupt (event) */
            pgm_kbd();
            break;
        case INTPER:		/* periodic interrupt (event) (~15Hz) */
            pgm_per();
            break;
	}
    }

Where should it run?

* window vs. screen

`screen' is an X window
`window' can mean an X window or a portion of one

* Primary Application

best user interaction support
owns one alphanumeric and two graphic windows/screens
do NOT use touch panel window!

* Secondary Application

usually display/monitor only
owns one graphic window/screen

* Nonuser Application

no visible display
started up with console

Libraries

* Do NOT use old/archaic CLIB routines! (TVM,LX,DPM,DBM,etc.)
* routines can be called from either C++ or FORTRAN
* routines with `_c' suffix are `C++ friendly' versions
* top level topics

CLIB_INFO                  CONSOLE_INFO               C_MACROS                   
DATALOGGER                 DATA_MANIPULATION          DIO_ALARMS                 
DIO_DATABASE               DIO_DIGITAL                DIO_MODEL                  
DIO_RAW                    DIO_SCALED                 DIO_TABLE                  
ERROR_LOGGING              EVENTS_AND_CLOCKS          FILE_IO                    
GRAPHICS_SCREENS           GRAPHICS_WINDOWS           INTER_NODE_IO              
INTRA_NODE_IO              KNOB_DATA                  NETWORK_NAMES              
NEWS                       OLD_CLIB                   PRINT                      
NEW_USER                   OTHER_DATA_IO              ARGUMENT_HANDLING          
PROGRAM_CONTROL            PROGRAM_UTILITIES          SAVE_RESTORE               
SCRIPT                     TIME                       TOUCH_PANEL                
TV_WINDOWS                 USER_LIBRARIES                                        

Anatomy of a Library Routine Help Entry

* components of a help entry

calling description with argument data types
routine functional description
verbose description of arguments
description of returned status (if applicable)
required header/include files
related functions (hot links in WWW version)

Anatomy of a Library Routine Help Entry
(continued)

* each argument is listed as - name.data_type.passing_mechanism

status.i4.v = str_is_blank_c(string.i1a.r [,length.i4.v])
(The complete description of possible values is in the `intro_help' help topic.)

* arguments enclosed by square brackets are optional
* The default values of optional arguments should be listed in the help. Zero is NOT the universal default value.

Error Handling/Logging

* ACNET errors are composed of two parts:

facility: integer code that identifies the subsystem that emitted the error
error: integer code that defines the specific error within the facility
for example: 17 -10 indicates a timeout reported by DPM on setting a device

(DPM_TMOSET is the ASCII version of this error code)

* Primary Applications should include an error display window

error_init(_c) - define error display format
can map error messages to console and/or shared log files which can be viewed using `Pgm_Tools'

* display errors with `error_display(_c)'
* display user messages with `error_message(_c)'

Window Manager

* manages usage of alphanumeric (TV) windows
* background window always exists (WMNGR_BACKGROUND)

should always set the background window size during initialization

* coordinates are row and column (usually in that order)
* origin for coordinates in a window is in the upper left hand corner

origin coordinates for the background window are (1,1)
origin coordinates for all other windows are (0,0)

* physical vs. logical coordinates
* windows are referred to by a two byte integer ID or handle
* window text files can be edited on D10

Window Manager (continued)

* basic routines

window_intype - returns program interrupts/events and manages restacking, moving, and resizing windows

window_enable_interrupts - enables automatic window management
window_set_background_size(_c) - sets background window size
window_construct(_c) - creates a new window (returns ID)
window_tvm(_c) - reads or writes a text string (physical coordinates)
window_delete(_c) - deletes a window
window_display_value(_c) - displays a value (many data types) in a window
window_input_value(_c) - inputs a value (many data types from a window)
in_window_field(_c) - tests for an interrupt in a window field
in_window_box(_c) - tests for an interrupt in a window region

window_printf_at_c - printf-like output at a specific location with support for embedded color codes and site specific conversions

Window Manager (continued)

* scrolling routines

window_enable_scroll_io(_c) - enable I/O to the window's scroll buffer
window_entry_to_row_c - converts logical to physical row coordinates
window_row_to_entry_c - converts physical to logical row coordinates
window_write_line_c - writes text strings to sequential rows
window_sequential_write_c - writes text strings either to the last accessed row or the next sequential one
window_write_scroll_c - writes text strings in a scrolling terminal format
window_printf_c - works like printf except that it supports embedded color

codes as well as site specific conversions

Window Manager (continued)

* highlighting routines
* switch routines
* menu bar routines

use two back slashes (\\) to separate menu bar items

* slider routines
* select field routines
* high level dialogs

scroll_menu(_c) - popup menu
decide(_c) - logical decision dialog (`caution user')
winput(_c) - inputs multiple data types
input_array_values_c - input arrays of different types
acknowledge(_c) - simple acknowledge message dialog
many more...
can try out dialog routines using Example Program #5 on W5

WNLIB

* manages usage of graphic (LX) windows
* background window always exists (WN_BACKGROUND)
* coordinates are X and Y
* virtual coordinates

define size and location of windows/view ports
origin is in the lower left hand corner
coordinate values range from 0.0 to 1.0

* world coordinates

real world/engineering coordinates within a window
origin is in the lower left hand corner
coordinate values are set by a call to `wn_world(_c)'

* windows are referred to by a four byte integer ID or handle

WNLIB (continued)

* normal function sequence

wn_view(_c) - create window using virtual coordinates
wn_world(_c) - establish real world/engineering units scaling
wn_active(_c) - make this window the active drawing window
execute drawing or other setup commands

* only the active window can be drawn to

even the background window must be activated before drawing on it

* text coordinates can be either normal world coordinates or row and column coordinates

set by calling `window_text_scaling_c'

* simple plot support

create window and labeled grid in one call using either `wn_grid(_c)' or `wn_quick_grid'
plot a buffer of points by calling `wn_point_set'

WNLIB (continued)

* data manipulation routines

save/recall plotted data
perform simple statistics on saved data
fit saved data

* cursor manipulation routines
* switch routines
* most features can be demonstrated by using the WNTEST program (D110)

DIO

* accesses both `live' and database data

data is addressed by a unique four byte key called a Device Index and by a Property Index (Property Indices are listed in the dbprops header)

* `live' data also requires the specification of a Frequency Time Descriptor (FTD)

FTD_ONESHOT - retrieve the data once and if successful cancel the request
FTD_1HZ * constant - retrieve the data at a periodic rate

(Note: Periodic FTDs are expressed in terms of 60 Hz ticks between data retrievals. Therefore, a larger FTD value indicates slower data retrieval.)

FTD_EVENT_MASK | clock_event - retrieve the data on the occurrence of the specified Tevatron CLocK (TCLK) event

* caches static database information to improve program performance

DIO (continued)

* simplest case - reading a single scaled value

status = dio_get_dev_c(device_index,property,&value,FTD_ONESHOT);

`device_index' can be obtained from the device name by calling the routine `dio_device_index(_c)'.

`property' can be either reading (PRREAD) or setting (PRSET).

`value' is the returned device value.

Since this is a one shot read, the request does not have to be canceled. Otherwise, `dio_can_get_c' would be called to cancel the request.


The returned status is a standard ACNET status value. (OK -> success)

DIO (continued)

* reading an array of scaled values - 3 steps

build the list of requests and return the list ID

status = dio_bld_get_c(&list_id,num_devices,device_indices,

properties,errors,FTD_1HZ);

read the list of values

status = dio_get_lst(&list_id,values,errors);

cancel the list of requests (not a one shot)

dio_can_get_lst(&list_id);

* DIO array status handling

If status is OK, the operation was successful.
If status is less than OK, there was an overall failure and the status value is a standard ACNET status value.
If status is greater than OK, some requests have succeeded and some have failed. The status value is the number of requests which failed. Use the routine `error_in_list(_c)' to find the actual ACNET error.

DIO (continued)

* important routines

dio_get_dev(_c) - retrieve a single scaled device
dio_get_raw(_c) - retrieve a single raw device
dio_get_array_device_c - retrieve a single array device
dio_can_get(_c) - cancel a single device request
dio_set_dev(_c) - set a single scaled device
dio_set_raw(_c) - set a single raw device
dio_set_array_device_c - set a single array device
dio_can_set(_c) - cancel a single device setting request
dio_bld_get - build a scaled device retrieval list
dio_get_lst - retrieve a list of scaled devices
dio_can_get_lst - cancel a retrieval list
dio_bld_set - build a scaled device retrieval list
dio_set_lst - retrieve a list of scaled devices
dio_can_set_lst - cancel a setting list

Data Storage

* relational database tables
* accessed via calls to `db_open, db_select, db_modify, and db_close'
* accessed using SQL

`Visual Guide to SQL' by Trimble and Chappell, John Wiley and Sons

* most appropriate if rows have limited number of fields
* tables are created using interactive SQL (sqsh)

need account from Database Administrators

Simple Data Storage

* for saved data totaling less than 256 bytes
* primarily for saving simple user configuration data
* `pgm_data_storage' - provides unique data for each console
* `pgm_data_storage_shared' - provides the same data for every console

Data Conversions

* numeric_to_ascii(_c) - convert values to ASCII
* ascii_to_numeric(_c) - convert ASCII to numeric values
* clib_sprintf - normal sprintf functionality plus many site specific conversions

User Libraries

* stored in MECCA like applications
* run time linked to applications
* examples

ul_cbsaux - generally useful routines, similar to CLIB

ul_physlib - physics calculation routines which are independent of user interface (includes routines from Numerical Recipes in C)

ul_windowlib - extensions to window_manager routines
ul_dialoglib - more high level dialog routines
ul_friglib - access routines for the refrigerator systems

Development Aids

* cc/standard=portable

use this from the beginning of development
checks for portability problems
eliminate all problems generating portability problems

* lint - `lcl_lint output_file source_file'

finds logic and portability problems that the compiler misses
may save lots of time in the long run
use this from the beginning of development

* useful applications

D10 - supports interactive layout of text windows
WNTEST (D110) - allows interactive use of WNLIB routines
Window Manager TST (D133) - allows interactive use of window_manager routines
Example Program #5 (W5) - allows interactive use of dialog routines

Testing and Debugging

* Z index
* debug_slot
* settings lock
* redirection
* peeker programs

Z index, D7

* testing and debugging
* mecca/development to Z index or D7
* Z index

cleared each morning at 3 a.m.
listed by author and PA number
use normal PA number; Z index version is distinct

* D7 Quick-SA-Test

next launch debug version
cleared on next index load

* select a debugger display method

debug_terminal
debug_window

debug_slot

* debug_terminal vs debug_window

CNS40> debug_slot
Select a slot to debug as follows:
1 = PA A
2 = GRAPHICS 1 SA
3 = GRAPHICS 2 SA
4 = ALARMS slot
5 = PA B
Slot number: 1
Start up the application to be debugged.
Use CONTROL/C to break into executing program.
OpenVMS VAX DEBUG Version V6.2-000
%DEBUG-I-INITIAL, language is C, module set to PA0758
DBG>

debug_slot (cont'd)

SRC: module PA0758 -scroll-source
11454: while (TRUE) {
11455: window_intype(&mwid, &type, &row, &col, &info);
11456: switch (type) {
11457: case 1:
11458: intype_initialize(FALSE,FALSE);
->1459: break;
11460: case 2:
11461: intype_terminate(row,col);
11462: break;
11463: case 3:
11464: intype_interrupt(row,col);
OUT -output
DBG> Step

debug_slot (cont'd)

Settings Lock

* is it pertinent?

console class determines some privileges
able to run a progam (not white index page entry)
able to set from program (index page entry is cyan)
database permit (by console class, little used)

* choices are privilege dependent

disable 5 minutes 15 minutes
1 hour 8 hours forever
remote

* choose minimum
* settings are logged

Redirection

* redirect data acquisition

modify node and SSDN
settings not forwarded to database
settings not logged
utility window lock
check out help on D128
yellow slash

* mirror
* test settings
* test progam flow
* test program error handling

Peeker Programs

* datapool peek, D3

useful to track memory and pool leaks
formatted dump
show process/remote peek

* CLIB Peeker, D22

WNLIB
WMNGR
database
error
process
fshare

* DIO Peeker, D114
* Clockscope, D33
* Database Dump, D80

Finishing Touches

* on-line help
* demo script
* abstract

On-line Help

* check out index page, D43, D44
* creation

press help button
press editor button

select normal text

fill in `about this program', exit and save

select topic names

select create, enter topics, exit and save

select a topic

select normal text and add help text, or ...
select topic names and create 2nd level of help

* editor has replace and insert modes
* row/column help likely to move to bubble help

Demo Script

* consider introduction to your program
* multiple demos eases edits
* creation of a script

normal, restart ... help is available

* insert button action during recording

program pause
settings and file write locks
display image
display text message

* deletion of a script

recording again has option to delete

* playing script

Pgm_Tools
menu of scripts
speed control

Abstract

* check out D15 Show Service Information
* check out sequencer, C48
* something more than help

Security, Privacy, Legal