SNAPAPP

table driven application interface to one or more snapper macros (NextMidas Only)

<table>    Optional table of multiple case configurations (defaults to nxm.ice.mcr.snapapp.tbl)
<app 1:N>  Application configuration case name for 1 to N snapper macros

This macro is a GUI to deploy one or more instances of the SNAPPER macro tailored to 
specific ACQUIRE/PLAYBACK applications. 

An example table config file is found int ICEROOT/tbl/snapapp.tbl.
You may wish to modify this, put it somewhere in your AUX path, and supply that as the argument 
to this macro.  For example:

  nM> snapapp myconfig.tbl

There are two types of entries in the config file.

The first is a table named SNAPSET which contains the default parameters for the SNAPPER macro.  
It has the form:

SNAPSET={
  PORT=MODULE1
  FORMAT=SB
  RATE=20
  CLOCK=A
  LENGTH=1.0
  DEC=512
  FREQ=1
  GAIN=0
  NFFT=2k
  PSDR=10
  PSDA=1
  FRAME=2430
  AFNAME=archive
  WAVE=NONE
}

This table is usually followed by multiple Case tables that define specific
parameters for different applications.  Each case table name begins with CASE_
followed by the Application Config Entry name.  This name can be entered from
the command line, or chosen from the interactive configuration menus.
The case entry has the form:

CASE_MCARCH={
  CARD=PIC1IIA
  PORT=TUNER1
  FORMAT=CI
  RATE=10
  CLOCK=I
  LENGTH=1
  FREQ=1
  DEC=32
  NFFT=4K
  AFNAME="mcarch"
  AFQUAL="MAXLINES=16,MAXLINESIZE=8M,AUXLIST=11|12"
  FLAGS=ITDEC
  SWITCHES=MULTI=4/DFREQ=1e3/AAUX=11/ATL=8K/GC={MODE=RTARCH,AOVER=APP,APKT=OFF}/MLOG=MCARCH
}

These parameters can override any of the parameters in the SNAPSET defaults.  All are optional.  
See the explain on SNAPPER for an explanation of these parameters.

Cases can be sub-cased to reuse most of the parameters from previously defined cases. 
For example:

CASE_MCARCH2={
  CASE=MCARCH
  PORT=TUNER2
}

Uses all of the values from CASE_MCARCH but overrides the PORT parameter.
When sub-casing, the special string $CASE will be substituted with the previous case's value of that parameter.
For example:

CASE_MCARCH2={
  CASE=MCARCH
  PORT=TUNER2
  AFQUAL="$CASE|"
  SWITCHES=/MULTI=8/$CASE
}

Note that switches have right to left preferencing and flags have left to right preferencing.

Sub-casing can be nested any number of levels.

Special case table entries are:

  FLAGS - flags for the SNAPPER macro call (second argument to snapper)
  SWITCHES - switches to place on the SNAPPER macro call
  AFQUAL - Archive File qualifiers for the archive file name

When APP1 and APP2 both use the same card, a /NORESET is automatically applied to APP2.
In this case, as well as any master/slave cases the menu items for starting the apps will
sequence the starts and stops properly.  If the individual SNAPPER macro menus are used to 
start the apps, be careful to start slaves 1st, then masters.

The /ACTIONS=list switch allows the user to customize the actions menu list.  
The available actions are:

  Monitor - Real-Time to/from memory buffer
  Rec/PB - Real-Time to/from streaming disk file
  Stop - Pause and/or configuration state
  Snap - snapshot a single memory buffer
  Play - same as RTArchive for playback
  Record - same as RTArchive for acquisition
  Rec/PB - displays Play or Record depending on App1 switches
  Cntrls - toggle viewing of the control widgets
  Exit - exit the application
  PowerOff - exit the application with POWEROFF=TRUE set (test $NM_OS/nmsf POWEROFF)

The /ACTION=item switch applies the <item> action directly after configuration.  
This can be used with /AUTOEXIT, /AUTOARCHIVE, and/or /BATCH to run automated scripts or icons.

If a configuration table contains an APPLIST section the /MENU switch will display this
menu to the user and run snapapp with the arguments list selected by APP name.  For example:

APPLIST={
  APP1="PIC2_OO,PIC1_II"
  APP2="PIC1IOST_O,PIC1IOST_I"
  DRFM="DRFM_PLY1200,DRFM_ACQ1200,/SHOW=0"
  ONESHOT="PIC1TSS,/ACTION=RTARCH,/AUTOEXIT"
}

Running snapapp/menu <table>  will display a menu containing the items "APP1,APP2,DRFM,ONESHOT"
and run snapapp with the listed arguments when selected.  Note: the /menu switch must come directly 
after the command name so as not to be inherited by the internal snapapp call.

To expose a list of cases other than all CASE_* entries in the table, add the PUBLIC=x,y,z table entry.

  PUBLIC="MCARCH1,MCARCH2"

To hide a list of cases that are contained in the table, add the PRIVATE=x,y,z table entry.

  PRIVATE="MCARCH1,MCARCH2"

A custom operational control panel is configured by the COMMON_CONTROLS=tbl and CONTROLS=tbl entries in 
the configuration file.  The /CCT=tbl switch can be used to specify a unique Common Controls Table at 
runtime or for different scenarios. These controls are tagged with instance name "_0" and are tied to all
snapper instances. They must be initialized to the desired setting. 

COMMON_CONTROLS={
  GAIN={VALUE=5}
  RFFREQ={MIN=1000,MAX=2000}
}

Copies the GAIN widget to the SNAPAPP global controls and sets the value to 5.
Also copies the RFFREQ widget to the global controls and bounds the widget between 1000 and 2000 MHz.

The CASE specific snapper controls are defined in the CASE_xxx.CONTROLS table of the config file.  
These controls are initialized to the values in the underlying snapper instance at startup.  

CASE_MCARCH2={
  CASE=MCARCH
  PORT=TUNER2
  CONTROLS={
    DEC={}
  }
}

Copies the DECimation widget to the SNAPAPP controls for all SNAPPERS running or subcasing case MCARCH2.

All global and case specific controls that are non-editable (/edit=f) are polled once per second to display 
the current value of the underlying snapper. Common controls poll the 1st snapper instance only.

To prevent the <Cntrls> button from toggling through the non-custom SNAPPER controls sections, add the MODCNTRLS table entry.

  MODCNTRLS=2

If the /SERVICE=port switch is applied to snapapp, a /SERVER=port+N switch is applied to each of the N 
snapper instances called by snapapp.  This will create a seperate web server for the SNAPAPP operator
controls and each of the individual SNAPPER engineering controls.  These controls are available through
HTTP or RMIF calls.  See the help on ICENET for Midas and non-Midas client code.  For example:

  nM> icenet SET 192.168.0.123:9001 {CHAN=4,FREQ=1.23,GAIN=3} HTTP

Sets the CHAN, FREQ, and GAIN widgets of the 1st snapper instance if /SERVICE=9000 is placed on the SNAPAPP call.

  http::192.168.0.123:9000/Controls/Set?{ACTION=MON}

Sets the ACTION widget of the SNAPAPP macro starting all of the underlying SNAPPERS in monitor mode.

For status of the system snapapp is operating on, see the help on ICE CONCEPTS NETWORK SERVICE:

Switches: 
  /ACTION=item - initiate the named action menu item (i.e. Monitor, Rec/PB, SnapShot)
  /ACTIONS=list - over-ride the default comma separated list of available actions
  /AFLAGSx=list - additional flags for application x=1|2...
  /APPEXT=macro - Application Extension Macro name
  /AUTOARCHIVE - to be inherited by SNAPPER submacros
  /AUTOCONFIG - override the card alias with an auto-detected configuration result
  /AUTOEXIT - to be inherited by SNAPPER submacros, exit when all snappers exit
  /AUTOEXIT=N - wait for the first N submacros to exit
  /AUTOSYNC - auto synchronize snapper starts to 1st App (applies XSOE,SGO,XTGO,RGO as appropriate)
  /BSIDE - run this case for the B side of the card
  /FILE=tbl - table of global controls to apply to all snapper instances (or query from snap1)
  /FILL=s - fill mode for populating panel (default s=LRTB Left2Right Top2Bott, also TBLR)
  /MAXCHK=n - inherited by ICEDIFF to limit number of samples in data check operations
  /MENU - popup a menu of the config table's APPLIST entry for selection 
  /NW=n - number of application windows to display
  /QUIET - suppress messages about internally applied flags and switches
  /SERVICE=port - add webserver to SNAPAPP and each SNAPPER submacro
  /SHOW=n - control display of widget panels 0=none 1=appControls 2=snapControls 3=allControls (default=2)
  /TBL=name - name of table file (checks aux path and ICEROOT/tbl paths for named .tbl file)
  /TEST - output the flags and switches for each SNAPPER invocation but do not execute
  /TIMEOUT=n - run for N seconds and quit
  /TP - use internal test port to auto synchronize multiple cards instead of eXternal SMB
  /USE={} - use entries in table to override any of the configuration entries (ex /use={card=pic3,clock=px}
  /USEGC={} - use entries in table to override any of the /GC={} graphical controls (ex /usegc={RFFREQ==1200,RFBW=30}
  /VERBOSE=n - pass the /verbose on to the snapper macros