7.11 SPECIAL SYMBOLS - Ferret/PyFerret Documentation

Ch7 Sec11. SPECIAL SYMBOLS

There are a few symbols, generated automatically by drawing plots or at Ferret run-time. Those are shown like all symbols by SHOW SYMBOLS, and their values can be used in scripts, but they cannot be directly redefined by the user. These are listed here.

In addition PPLUS defines a number of global symbols which are available to the user. They are documented in the chapter "Customizing Plots", section PPLUS special symbols and also listed in the PPLUS Users Guide.

PPL$XPIXEL
PPL$YPIXEL

the number of pixels in the horizontal (X) and vertical (Y) size of the current Ferret output window. Note: these are "0" if there is no current window -- hence they can be used as a test of whether there is an open window.

BYTEORDER

gives "BIG" or "LITTLE" according to endianness of the CPU

FERRET_MEMORY
give the current memory setting (Mwords).

FERRET_VERSION
give the Ferret version that is running.

FERRET_PLATFORM
give the Ferret version and the platform Ferret is running on.

NETCDF_VERSION
Gives the version of the netCDF library Ferret is linked with. (new in v6.6 Ferret)

PROGRAM_NAME
Returns Ferret if running classic Ferret, or PyFerret when running PyFerret. This allows scripts to be written to run under both programs.

To write scripts that run under both Ferret and PyFerret, syntax that is valid only under one or the other programs can be chosen with, for example,

IF ($program_name"0|PyFerret>1|*>0") THEN 
SET TEXT/FONT=arial
ELSE
SET MODE META
ENDIf
 
.. Ferret script commands
 
IF ($program_name"0|PyFerret>1|*>0") THEN 
FRAME/FILE=my_output.pdf
ELSE
CANCEL MODE META
ENDIF

FER_LAST_ERROR
if defined, contains the error string associated with the last Ferret error that was encountered. If it was a multi-line string, the lines are concatenated together.

PEAK_MEMORY
The symbol PEAK_MEMORY contains the peak amount of “essential” memory that has been required since the last time this symbol was zeroed by SET MEMORY/SIZE=<size> or CANCEL MEMORY. See more detailed discussion under Understanding Ferret Memory Management Concepts and Tools.

SPAWN_OK
Has a value of 1 if the last executed SPAWN command returned "success"; 0 if it was a "fail" return.

yes? spawn ls myfile.dat
yes? IF ($spawn_ok) THEN GO list_data ELSE GO create_file

SPAWN_STATUS
Returns the value of the status flag returned by the shell from the last executed SPAWN command. If running in -secure mode, this symbol contains a note to that effect.

LAST_GO_FILE
if defined, contains the name, including the path, of the last GO script that was executed.

Clock and timing symbols:

SESSION_DATE
SESSION_TIME
gives the date and time when the current session began.

CURRENT_DATE
CURRENT_TIME
gives the date and time when the given symbol is evaluated. Resets each time you SHOW SYMBOL CURRENT_DATE (or CURRENT_TIME) or evaluate one of them e.g. SAY ($CURRENT_TIME).

CLOCK_SECS
gives the elapsed time in seconds since the start of the Ferret session. This is done via a call to the intrinsic function SYSTEM_CLOCK and therefore its results may be system dependent. See examples below

DELTA_CPU
When it is evaluated, this calls the intrinsic function Dtime and sets the value to the delta-CPU-time since the last evaluation of this symbol (with SHOW SYMBOL, or with an evaluation of ($DELTA_CPU) ). It is called and set to zero Ferret initializes, so the first evaluation gets delta-cpu time since the start of the Ferret session. See examples below

>ferret
NOAA/PMEL TMAP
FERRET v6.2 
Linux(g77) 2.4.21-32 - 05/06/09
14-May-09 15:44 
 
yes? show symbols ! several symbols are set at startup.
..
FERRET_VERSION = "6.2"
FERRET_PLATFORM = "Linux(g77) 2.4.21-32"
SESSION_DATE = "14-May-09"
SESSION_TIME = "15:44"
DELTA_CPU = "0.01"
CLOCK_SECS = "2.62"
CURRENT_DATE = "14-May-09"
CURRENT_TIME = "15:52:17"
FERRET_MEMORY = "25.6"
 
yes? USE mydata.nc
yes? SHADE/K=1 temp[L=@ave]
yes? SHOW SYM DELTA_CPU, CLOCK_SECS
DELTA_CPU = "0.18"
CLOCK_SECS = "2.89"
 
yes? REPEAT/K=1:10 shade temp[L=@ave]
 
! DELTA_CPU since the evaluation just above on the SHOW SYM.
yes? LET time_ten_plots = ($DELTA_CPU) 
!-> DEFINE VARIABLE time_ten_plots = 0.88
 
! This command evaluates the CPU time since the last 
! evaluation, which was just above.
 
yes? sh sym DELTA_CPU
DELTA_CPU = "0"
 
! To get elapsed time for a particular piece of calculation,
! set a variable or symbol containing one evaluation of CLOCK_SECS
! and subtract that from a later evaluation of CLOCK_SECS.
 
yes? let secs_0 = ($clock_secs)
 
yes? repeat/k=1:10 (shade/pal=rnb2 temp[L=@max])
yes? let elapsed_clock_time = `($clock_secs) - secs_0`
 
! SESSION_DATE and SESSION_TIME are fixed for the entire session,
! CURRENT_DATE and CURRENT_TIME update when they are evaluated.
yes? SH SYM session_date, current_date, session_time, current_time
SESSION_DATE = "14-May-09"
SESSION_TIME = "15:52"
CURRENT_DATE = "14-May-09"
CURRENT_DATE = "15:52:20"