Variables, Variables, Everywhere
Walter F. Blood
Director of Product Management
1
Agenda
Variables – A Quick Review
Variables in Reports
Variables in Procedures
Variables in Masters
2
A Quick Review
3
The Basics
Two types of Variable
Local - &xxx - scope limited to procedure
Named - &ABC
Positional - &1 – passed in order from invocation
Global - &&xxx - scope expanded to session
Value retained from procedure to procedure
Classes of variables
System – value supplied by system
Statistical – generated by WebFOCUS during processing
Special -- variables for interactive use including &ECHO
4
Classes of Variables
System Variables always available
&APPROOT
&DATE
&DATEfmt
&DATXfmt
&DMY/&DMYY
&FOCCODEPAGE
&FOCEXURL
&FOCFEXNAME
&FOCFOCEXEC
&FOCINCLUDE
&FOCMODE
&FOCNEXTPAGE
&FOCQUALCHAR
&ECHO
&FOCHTMLURL
&FOCREL
&TOD
&YMD/YYMD
&RETCODE
&SETFILE
&AUTOINDEX
&MDY/&MDYY
5
Classes of Variables
Statistical variables follow activity
&BASEIO
&FOCDISORG
&INDEXIO
&FOCERRNUM
&LINES
&READS
&RECORDS
&SORTIO
6
The Basics
Characteristics
– All variables are strings of characters
• Data treated as Alphanumeric
• All numeric treated as Integer
• Use SET DMPRECISION to add decimal precision
– Maximum number of variables – 1024 active
– Maximum length of variable – 32K
– Variable Name - 100 characters
• A to Z, a to z, numbers, and ‘_’
• Named must start with alpha
• Numeric only name treated as positional
7
Information About Variables
Existence
• Test the existence of a variable with &variable.EXIST
– Returns 0 if variable does not exist – test with EQ
– Returns non-zero if variable exists – test with NE
Length of data
• Retrieve length of data value in variable with
&variable.LENGTH
– Returns 0 if the variable is not present
8
Information About Variables
Variable Data Type
• Test character of content with &variable.TYPE
– Numeric – TYPE = N
• Can the contents be converted to a floating point number?
• Integer is the norm – no decimal points
• Add decimal places with SET DMPRECISION
• SET DMPRECISION = OFF/number
• Calculation requires conversion to double precision
• Calculation result truncated without DMPRECISION
– Alpha – TYPE = A
– Undefined – TYPE=U
9
Information About Variables
Evaluate Variable Immediately
• Evaluate variable on demand with &variable.EVAL
– Used when variable may not be fully resolved
– Complex expression
– Variable used within quotes
Automatic Single Quote Handling
• Automatic adjustment to handle single quotes in data with
&variable.QUOTEDSTRING
– Useful to accommodate single quotes which must be doubled in
order to be passed
10
Basic Actions
Setting the variable to a given value
– -SET – creates variable and assigns value
• Requires terminator - ;
• Can be set to
– Literal value, including null, alpha in quotes
– Another variable
– Arithmetic, alphanumeric, logical, or compound expressions
– -READ <ddname &xxx.A5 &yyy.I3
• Load variable by reading file physically – position
• DDNAME must be FILEDEFd or ALLOCATEd
• All space must be accounted for
• Use for Fixed or Comma-delimited files
11
Basic Actions
Setting the variable to a given value
– -DEFAULT and -DEFAULTH
• Creates default value for use if none is –SET
• -DEFAULTH hides value on AUTOPROMPT/PROMPT
• Cannot be set to expression
– -READFILE <filename>
• Uses Master file to read the file
• Assigns data values to &FIELDNAME
12
Basic Actions
Working with variables
– EX procedure ABC= value1, value2, &DEF=value3
• Key/value pair
– ABC assigned to &ABC
– &DEF assigned to &&DEF
• Value - assigned positionally - &2
– Implicit prompting
• Unassigned variable forces prompting
• AUTOPROMPT with -WFDESCRIBE
– -PROMPT, -WINDOW, -CRTFORM
• Explicit methods to get value for variables from FOCUS
13
Basic Actions
Prompting allows additional extensions
– &variable.format. – control format of data entered
• Type and length tested
• Incorrect entry – FOC291 error
– &variable.(text). – add text to display when prompting
• Use apostrophe if text contains parenthesis
14
Basic Actions
Prompting allows additional extensions
– &variable.list. – list of acceptable values for prompt
• List - comma-delimited string
• Range of values – FROM a TO b
• Dynamic list – FIND field IN file
– &variable.VALIDATE
• Security – prevent injection
• Validate data received at runtime
• List, Range, FIND, REGEX
15
Variables in Reports
16
Variables in Reports
Self-service based upon user choice
– Create launch page to collect variable values
• Populate parameters passed with focexec
• Use values to generate report dynamically
– Allows you to add information
• Procedure information and variable description
• Headings and Footings
• Make use of default variable values
17
Variables in Reports- Auto-Prompting
18
Variables in Requests - Auto Prompting
All variables must have values before running
– Request scanned for variables
• Evaluated from –SET, -DEFAULT, -DEFAULTH
• Variables without values trigger prompting
– Variable ignored in prompting
• -SET variable
• Global variable - &&
• -DEFAULTH variables (hidden)
– Special character handling
• ‘( ‘ - make sure there is space before it
• ‘&’ - to use this as a character use ‘&|’
• -HTMLFORM BEGIN NOEVAL to suppress ‘&’ evaluation
19
Variables in Report - Selection
• Static Single Select List of Values
WHERE STORENAME EQ ‘&STORENAME.(eMart,TV City, WebSales).’
• Dynamic Single Select List of Values
WHERE STORENAME EQ ‘&STORENAME.(FIND STORENUM,
STORENAME IN CENTORD). Store Name. ’
20
Variables in Selection
• Static Multi-Select List of Values
WHERE STORENAME EQ
‘&STORENAME.(OR (eMart,TV City, WebSales).Store Name.’
• Dynamic Multi-Select List of Values
WHERE STORENAME EQ ‘&STORENAME.(OR(FIND STORECODE,
STORENAME IN CENTORD)). Store Name. ’
21
Variables in Selection
Special selection values
– FOC_ALL – Select All option
• WHERE -set to all values in multi-select list separated by OR
/AND
– No selection
• _FOC_NULL – default value
– Can be reset in IBIF_describe_null variable
– Phrase or expression containing _FOC_NULL removed
from request before run
• FOC_NONE – applies to non-DM line
– Line removed before request is run
22
Variables in Display or Sort – Static Single Select
• Static Single Select List of Display fields
SUM &SumFlds.(<Sales,DOLLARS>,<Budget,BUDDOLLARS>,
<Units,UNITS>).Sum.
• Static Single Select List of BY fields
BY &SortBy.(<Category,GGSALES.SALES01.CATEGORY>,
<PRODUCT>).By.
• Static Single Select List of ACROSS fields
ACROSS &Acrs.(<Area,REGION>,<State,ST>,
<None,FOC_NONE>).Across.
23
Variables in Display or Sort – Static Multi-Select
• Static Multi-Select list of display fields
SUM &SumFlds.(AND(<Sales,DOLLARS>,<Budget,BUDDOLLARS>,
<Units,UNITS>)).Sum.
• Static Multi-Select list of BY fields
BY &SortBy.(AND(<Category,GGSALES.SALES01.CATEGORY>,
<PRODUCT>)).By.
• Static multi-select list of ACROSS fields
ACROSS &Acrs.(AND(<Area,REGION>,<State,ST>,
<None,FOC_NONE>)).Across.
24
Variables in Display or Sort – Dynamic Single Select
• Dynamic Single Select List of Display fields
SUM &SumFlds.(FIND NAME, FLDDESC IN GGDETFLD). Sum Field.
• Dynamic Single Select List of BY fields
BY &SortBy.(FIND NAME, FLDDESC IN GGBYFLD).By Field.
• Dynamic Single Select List of ACROSS fields
ACROSS &Acrs.(FIND NAME, FLDDESC IN GGACRFLD).Across Field.
25
Variables in Display or Sort –Dynamic Multi-Select
• Dynamic Multi- Select List of Display fields
SUM &SumFlds.(AND(FIND NAME, FLDDESC IN GGDETFLD))
.Sum Fields.
• Dynamic Multi-Select List of BY fields
BY &SortBy.(AND(FIND NAME, FLDDESC IN GGBYFLD)).By Fields.
• Dynamic Multi-Select List of ACROSS fields
ACROSS &Acrs.(AND(FIND NAME, FLDDESC IN GGACRFLD))
.Across Fields.
26
Variables in Selection
Additional considerations
– What else can be parameterized in a report?
• Titles, Headings, SubHeads, SubFoots, Footings
• Calculations
– On retrieval with DEFINE
– On output with COMPUTE
– Variable values can also be created in
• HTML
• Javascript
27
Variables in Procedures
28
Variables in procedures
System Variables always available for testing or info
&APPROOT
&DATE
&DATEfmt
&DATXfmt
&DMY/&DMYY
&FOCCODEPAGE
&FOCEXURL
&FOCFEXNAME
&FOCFOCEXEC
&FOCINCLUDE
&FOCMODE
&FOCNEXTPAGE
&FOCQUALCHAR
&ECHO
&FOCHTMLURL
&FOCREL
&TOD
&YMD/YYMD
&RETCODE
&SETFILE
&AUTOINDEX
&MDY/&MDYY
29
Variables in procedures
Statistical variables available following activity
&BASEIO
&FOCDISORG
&INDEXIO
&FOCERRNUM
&LINES
&READS
&RECORDS
&SORTIO
30
Variables in procedures - Navigation
Calling other local procedures
– Use Global variables that last for the session
– EX <focexecname> <parm1> <parm2>
• Variables not evaluated in calling focexec
• Variables are passed as parameters
• Existing local variables are lost
– -INCLUDE <focexecname>
• Variables in –INCLUDE focexec are evaluated
• Existing local variables survive
• Code is added at parse time of calling focexec
31
Variables in procedures - Navigation
Calling other local procedures
– Use Global variables that last for the session
– EX <focexecname> <parm1> <parm2>
• Variables not evaluated in calling focexec
• Variables are passed as parameters
• Existing local variables are lost
– -INCLUDE <focexecname>
• Variables in –INCLUDE focexec are evaluated
• Existing local variables survive
• Code is added at parse time of calling focexec
32
Variables in procedures - Navigation
Calling procedures on other systems
– To send code to be run on another system surround code with
• -REMOTE BEGIN
• -REMOTE END
– To run a focexec on another system within remote block
• EXEC <focexecname> <parm1> <parm2>
– What to do with the output?
• ON TABLE HOLD leaves data and metadata on remote system
• ON TABLE PCHOLD retrieves data and metadata
33
Variables in procedures - navigation
Controlling the flow of the procedure
• Branch to perform an action – -GOTO – unconditional
-- -IF ..GOTO ELSE …GOTO.. – conditional
LOOKUP
FILE ?
NO
CREATE LOOKUP FILE
YES
RUN REPORT
-SET &A=‘ ‘;
-READ LOOKUP &A.1.
-IF &A NE ‘ ‘ THEN GOTO RUNREPORT ELSE
- GOTO CREATEREPORT ;
34
Variables in procedures - navigation
Controlling the flow of the procedure
• Storing multiple values for a single variable
-SET &A=‘ ‘;
-SET &CTR=0;
-LOOP
-SET &CTR=&CTR + 1;
-READ LOOKUP &A.&CTR.1.
-IF &IORETURN NE 0 THEN GOTO DONE
- ELSE GOTO LOOP;
-DONE
SET COUNTER
LOOP
READ RECORD
YES
MORE
RECORDS
?
NO
DONE
35
Variables in procedures - navigation
REPEAT WHILE
Controlling the flow of the procedure
• REPEAT process a variable number of times
-REPEAT DONE WHILE &IORETURN NE 0;
-READ LOOKUP &A
-WRITE OUTPUT NOCLOSE &A
-DONE
READ
WRITE
YES
• REPEAT label N TIMES
• REPEAT label FOR variable FROM x TO y STEP n
IORETURN
NE 0?
NO
DONE
36
Variables in procedures
Gathering data values
– Testing if variable value in file
-SET &A=&C IN FILE FILENAME;
– Using the master file to load field variables
-READFILE CAR
-TYPE COUNTRY IS &COUNTRY
-TYPE CAR IS &CAR
-CLOSE CAR
– Place SET values in variables
-? SET ASNAMES &ABC
37
Variables in procedures
Displaying values in variables
– Local variables - list specific & variable
-? &ABC
– Global variables – list all && variables
? &&
38
Variables in procedures -HTMLFORM
Passing information using HTMLFORM
-IF &OPTION.EXIST GOTO HRINFO ELSE GOTO CANTRUN;
-HRINFO
TABLE FILE CENTHR
...
END
-CANTRUN
-EXIT -HTMLFORM BEGIN
<HTML>
<BODY>TOTAL REPORT CAN'T BE RUN WITHOUT AN OPTION. TIME &TOD
</BODY>
</HTML>
-HTMLFORM END
-EXIT
39
Variables in procedures
Variables in web pages
– Referring to variable value
Local variable
Global variable
!IBI.AMP.variablename;
!IBI.GLB.variablename;
– Referring to variable value length
Local variable
Global variable
!IBI.AML.variablename;
!IBI.GLL.variablename;
– Variable in form input field
<INPUT TYPE=TEXT NAME=variable VALUE=“IBI.AMP.variable;”>
40
Variables in Master Files
41
Master File global variables
Global variables declared in Master files
VARIABLE NAME=[&&]var, USAGE=Aln,
[DEFAULT=defvalue,] [QUOTED={OFF|ON},] $
– Global variables for use in requests based upon the Master
– Global variables for use in Master File profiles
– Global variables for attributes including
• TITLE
• DBA USERID and VALUE
• ACCESS file parameters – TABLENAME, CONNECTION
42
Master File Profile
MFD Profile opens new possibilities
FILE=name, SUFFIX=SQLMSS, MFD_PROFILE=profilename…,$
– MFD Profile is standard focexec
• Run as soon as Master File is opened
• Contains any standard syntax
• Beware infinite loops – self referencing
– Possibilities
• Tailoring Field Titles by a condition
• Dynamic conditional creation of DBA or FILTER FILE
• Changing data location or allocation dynamically
• Dynamic alteration of request elements in Master
• Dynamic DECODE table generation
43
Master File – MFD Profile
MFD Profile characteristics
– Executed for commands
• TABLE, TABLEF, MATCH, GRAPH,
• CREATE,
• DEFINE,
• CHECK, ?F, and ?FF
– MATCH/MORE –executed in reverse order
– JOINed files – all MFD PROFILES are executed
– Variables will be subject to order of MFD PROFILES !
– Ignored for MODIFY, MAINTAIN and READFILE
– Do not call the master the MFD PROFILE is in – infinite loop
44
Socialize to Win! Daily Prizes Awarded!
Tweet at @infobldrs and
tag #IBSummit during the event!
Tag @informationbuilders in your
#IBSummit pics!
Check our Summit Facebook & LinkedIn pages
for updates, photos, and announcements