Creating and Working With Variables

In this section:

Reference:

You can use variables to customize a procedure, as described in Customizing a Procedure With Variables. Variables fall into two categories:

Reference: Variable Characteristics

The following features apply to all variables:

  • A variable stores numbers or a string of text and can be placed anywhere in a procedure.

    Note: A Dialogue Manager variable contains only alphanumeric data. If a function or expression returns a numeric value to a Dialogue Manager variable, the value is truncated to an integer and converted to alphanumeric format before being stored in the variable.

  • A variable can refer to a command, a data source field, a verb, or a phrase.
  • The total length of all variable values cannot exceed 32K.
  • A variable can be supplied directly in the command, when you execute the procedure, or through the -DEFAULT, -SET, or -READ commands in the procedure.

Creating and Working With Local and Global Variables

In this section:

How to:

Reference:

Local and global variables are variables whose user-defined values must be supplied at run time.

Note: Values with embedded commas (',') are not allowed.

Reference: Naming Conventions for Local and Global Variables

Local and global variable names are user-defined, while system and statistical variables have predefined names. The following rules apply to the naming of local and global variables:

  • A local variable name is always preceded by an ampersand (&).
  • A global variable name is always preceded by a double ampersand (&&).
  • Embedded blanks are not permitted in a variable name.
  • If a value for a variable might contain an embedded blank, comma, or equal sign, enclose the variable in single quotation marks when you refer to it.
  • A variable name may be any combination of the characters A through Z, 0 through 9, and the underscore. The first character of the name should be a letter.
  • You can assign a number instead of a name to a variable to create a positional variable.
  • The underscore may be included in a variable name, but the following special characters are not permitted: plus sign (+), minus sign (-), asterisk (*), slash (/), period (.), ampersand (&), and semicolon (;).

Syntax: How to Specify a Variable Name 

&[&]name

where:

name

Is the variable name. A single ampersand (&) denotes a local variable, while a double ampersand (&&) denotes a global variable. A single ampersand followed by a numeric string denotes a positional variable.

The name you assign must follow the rules outlined in Naming Conventions for Local and Global Variables.

Example: Variable Names

The following variables are properly named: 

&WHICHPRODUCT
&WHICH_CITY
'&CITY'
&&CITY

The following variables are improperly named for the reason given:

&WHICH CITY

Contains an embedded blank.

&WHICH -CITY

Contains a hyphen.

WHICHCITY

Leading ampersand(s) missing.

Example: Using Local Variables

Consider the following procedure, SALESREPORT, in which &CITY, &CODE1, and &CODE2 are local variables. 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY"
"PRODUCT CODES FROM &CODE1 TO &CODE2"
" "
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &CITY
BY PROD_CODE
IF PROD_CODE IS-FROM &CODE1 TO &CODE2
END

Assume you supply the following values when you call the procedure: 

EX SALESREPORT CITY=STAMFORD, CODE1=B10, CODE2=B20

Dialogue Manager substitutes the values for the variables as follows: 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR STAMFORD"
"PRODUCT CODES FROM B10 TO B20"
" "
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ STAMFORD
BY PROD_CODE
IF PROD_CODE IS-FROM B10 TO B20
END

After the procedure executes and terminates, the values STAMFORD, B10, and B20 are lost.

Example: Using Global Variables

The following example illustrates the use of three global variables: &&CITY, &&CODE1, &&CODE2. The values are substituted in the first procedure, PROC1, and the values are retained and passed to the second procedure, PROC2. 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &&CITY"
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &&CITY
BY PROD_CODE
IF PROD_CODE IS-FROM &&CODE1 TO &&CODE2
END
EX PROC2
TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &&CITY AND PRODUCT &&CODE1"
PRINT UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &&CITY
IF PROD_CODE EQ &&CODE1
END

Concatenating Variables

How to:

You can append a variable to a character string, or you can combine two or more variables and/or literals to concatenate a variable. See the Creating Reports With TIBCO WebFOCUS® Language manual for details on concatenation. When using variables, it is important to separate each variable from the concatenation symbol with a space.

Syntax: How to Concatenate a Variable 

-SET &name3 = &name1 || &name2;

where:

&name3

Is the name of the concatenated variable.

&name1 || &name2

Are the variables, separated by the concatenation symbol and a space on both sides.

Removing Trailing Blanks From a Variable

How to:

You can remove trailing blanks form a variable with the Dialogue Manager TRUNCATE function. TRUNCATE can be used only with Dialogue Manager commands that support functions, such as -SET and -IF commands. It cannot be used in a -TYPE command or in arguments passed to procedures.

The TRUNCATE can act only on one variable at a time. If you attempt to use the Dialogue Manager TRUNCATE function with more than one argument, the following error message is generated: 

(FOC03665) Error loading external function 'TRUNCATE'

Note: A user-written function of the same name can exist without conflict.

Syntax: How to Remove Trailing Blanks 

-SET &var2 = TRUNCATE(&var1);

where:

&var2

Is the Dialogue Manager variable to which the truncated string is returned. The length of this variable is the length of the original string or variable without the trailing blanks. If the original variable consisted of only blanks, a single blank with a length of one is returned.

&var1

Is a Dialogue Manager variable or a literal string enclosed in single quotation marks (‘). System variables and statistical variables are allowed, as well as user-created local and global variables.

Example: Removing Trailing Blanks

In the following example, TRUNCATE removes trailing blanks. 

-SET &LONG = 'ABC   ' ;
-SET &RESULT =  TRUNCATE(&LONG);
-SET &LL = &LONG.LENGTH;
-SET &RL = &RESULT.LENGTH;
-HTMLFORM BEGIN
<HTML>
<BODY>
<P>LONG   =  &LONG     LENGTH =  &LL</P>
<P>RESULT =  &RESULT     LENGTH =  &RL</P>
</BODY>
</HTML>
-HTMLFORM END

The output is:

Example: Removing Trailing Blanks in a String of All Blanks

In the following example, when TRUNCATE removes the trailing blanks, since the string consists of all blanks, a string with the length of 1 is returned. 

-SET &LONG = '      ' ;
-SET &RESULT =  TRUNCATE(&LONG);
-SET &LL = &LONG.LENGTH;
-SET &RL = &RESULT.LENGTH;
-HTMLFORM BEGIN
<HTML>
<BODY>
<P>LONG   =  &LONG     LENGTH =  &LL</P>
<P>RESULT =  &RESULT     LENGTH =  &RL</P>
</BODY>
</HTML>
-HTMLFORM END

The output is:

Example: Using the TRUNCATE Function as an Argument for a Function

In the following example, TRUNCATE is an argument for the EDIT function. 

-SET &LONG = 'ABC   ' ;
-SET &RESULT =  EDIT(TRUNCATE(&LONG)|'Z','9999');
-SET &LL = &LONG.LENGTH;
-SET &RL = &RESULT.LENGTH;
-HTMLFORM BEGIN
<HTML>
<BODY>
<P>LONG   =  &LONG     LENGTH =  &LL</P>
<P>RESULT =  &RESULT     LENGTH =  &RL</P>
</BODY>
</HTML>
-HTMLFORM END

The output is:

Displaying the Value of a Variable

How to:

You can display the value of a variable by issuing a query.

Syntax: How to Display the Value of a Local Variable 

-? &[string]

where:

string

Is a variable name. If this parameter is not specified, the current values of all local, global, system, and statistical variables are displayed.

Syntax: How to Display the Value of Global Variables 

? &&

Assigning the Value of a Variable to a Parameter

How to:

You can capture the value of a SET parameter value in a local variable.

In WebFOCUS, the result is returned in your browser window, or as a comment in the HTML file if there is other HTML output from the request. Use the applicable web browser functions to view the HTML comments (for example, View Source in Microsoft Internet Explorer).

Syntax: How to Assign the Value of a Parameter to a Variable 

-? SET parameter variable

where:

parameter

Is a SET parameter.

variable

Is the name of the variable where the value is to be stored.

Example: Assigning the Value of a Variable to a Parameter

Entering the following stores the value of ASNAMES as the value for &ABC. 

-? SET ASNAMES &ABC

If you omit &ABC from the command, then a variable called &ASNAMES is created that contains the value of ASNAMES.

Working With System and Statistical Variables

Reference:

System and statistical variable values are predefined and automatically supplied by the system when a procedure references them. System and statistical variables have names that begin with a single ampersand (&). Examples of these variables are &LINES, which indicates how many lines of output were produced, and &DATE, which indicates the current date.

Reference: WebFOCUS System Variables

You can override WebFOCUS system-supplied values by assigning a value to the variable explicitly with a -SET or -DEFAULT command. However, we recommend that you do not override these values.

The following table lists the system variables available in WebFOCUS.

System Variable

Description

Format or Value

 
&APPROOT

Contains directories and data. By default, this is the Application Root directory (APPROOT directory) in which WebFOCUS looks for project files. Sample files are provided in the \ibinccen and \ibisamp directories. 

d:\ibi\apps
 
&AUTOINDEX

Retrieves data faster by automatically taking advantage of indexed fields in most cases where TABLE requests contain equality or range tests on those fields. Applies only to FOCUS data sources.

AUTOINDEX is never performed when the TABLE request contains an alternate file view, for example, TABLE FILE filename.filename. Indexed retrieval is not performed when the TABLE request contains BY HIGHEST or BY LOWEST phrases and AUTOINDEX is ON. 

No
 
&DATE

Returns the current date.

 
MM/DD/YY
 
&DATEfmt
&DATXfmt

Returns the current date or date-time value, where fmt can be any valid date or date-time format. &DATEfmt retains trailing blanks in the returned value. &DATXfmt suppresses trailing blanks in the returned value.

Note: Using the concatenation symbol (|) to remove punctuation between components is not supported. To return a value without punctuation between the components, use &YYMD or &DATEHYYMDN.

For information about date and date-time formats, see Chapter 4, Describing an Individual Field, in the Describing Data With TIBCO WebFOCUS® Language manual.

Returns the current date or date-time value, where fmt can be any valid date or date-time format. Because many date format options can be appended to the prefix DATE to form one of these variable names, you should avoid using DATE as the prefix when creating a variable name. 

&DMY

Returns the current date.

 
DDMMYY
 
&DMYY

Returns the current (four-digit year) date. 

DDMMCCYY
 
&ECHO

Displays command lines as they execute in order to test and debug procedures. 

ON,OFF, ALL, or NONE
 
&EXITRC

Return code value from execution an operating system command. Referencing &EXITRC forces the execution of all stacked commands, like the command -RUN.

Any value returned by a command is valid, but zero is considered normal (successful) execution.

 
&FOCCODEPAGE

Returns the code page being used by the server.

An integer value.

 
&FOCEXURL

Runs and executes drill downs remotely. The drill down program can be on your local machine or on a remote machine. 

/ibi_apps/
WFServlet?IBIF_webapp=
/ibi_apps&IBIC_server
 
&FOCFEXNAME

Returns the name of the FOCEXEC running even if it was executed using an EX command or a -INCLUDE command from within another FOCEXEC. This variable differs from the &FOCFOCEXEC variable because &FOCFOCEXEC returns the name of the calling FOCEXEC only.

 

 
&FOCFOCEXEC

Manages reporting operations involving many similarly named requests that are executed using the EX command. &FOCFOCEXEC enables you to easily determine which procedure is running by returning the fully qualified path for the procedure. &FOCFOCEXEC can be specified within a request or a Dialogue Manager command to display the name of the current procedure.

 

 
&FOCHTMLURL

Allows you to access resources with an alias other than /ibi_apps/ibi_html.

To generate an alias other than /ibi_html on the WebFOCUS Reporting Server, use the SET FOCHTMLURL command to set the alias that will be generated instead of /ibi_apps/ibi_html.

This command will most likely be used in a server profile (EDASPROF.PRF) or in one of the WFS files (site.wfs) to establish a default setting for the installation. 

/ibi_apps/ibi_html
 
&FOCINCLUDE

Manages reporting operations involving many similarly named requests that are included using the -INCLUDE command. &FOCINCLUDE can be specified within a request or a Dialogue Manager command to display the name of the current procedure.

 

 
&FOCLANGCODE

Holds the three-character language code, for example, GER for GERMAN or FRE for FRENCH. This variable is blank when the language is English, either AME or ENG.

 

 
&FOCMODE

Identifies the operating environment.

CMS, CRJE, MSO, OS, or TSO.

 
&FOCNEXTPAGE

Is a variable whose value is determined by the last page number used by the last report. Its value is one more than the last page number used in the last report. 

0
 
&FOCQUALCHAR

Returns the character used to separate the components of qualified field names.

. : ! % | \

 
&FOCREL

Identifies the FOCUS release number.

The release number.

 
&FOCSECUSER

Returns the user ID of the user connected to the running agent on a Reporting Server running with security ON.

 

 
&FOCSECGROUP

Returns the primary group ID of the user ID stored in &FOCSECUSER.

 

 
&FOCSECGROUPS

Returns list of group IDs of the user ID stored in &FOCSECUSER.

The length limit of the returned list is 4000 characters.

 

 
&MDY

Returns the current date. Useful for numeric comparisons.

 
MMDDYY
 
&MDYY

Returns the current (four-digit year) date.

 
MMDDCCYY
 
&RETCODE

Is the value returned after a server command is executed.

&RETCODE executes all stacked commands, like the command -RUN.

Any value defined by the server command.

Any value returned by a command is valid (for example, CALLPGM flag values), but zero is considered normal (successful) execution.

The one exception is the &RETCODE value of dash operating system commands, such as -DOS, -UNIX, VMS, -AS/400, and -WINNT, represent the success, not of the command they are running, but of the ability of the server to spawn out to the OS and run the command. In this case, the &RETCODE value is normally zero because it reflects that the spawn executes normally regardless of the results of the specific command. For this case, the amper variable &EXITRC should be used to check the command result or the non-dash version of the command should be used. 

&SETFILE

Contains the value from the SET FILE command.

 

 
&TOD

Returns the current time. When you enter FOCUS, this variable is updated to the current system time only when you execute a MODIFY, SCAN, or FSCAN command. To obtain the exact time during any process, use the HHMMSS function. 

HH.MM.SS
 
&YMD

Returns the current date.

 
YYMMDD
 
&YYMD

Returns the current (four-digit year) date.

 
CCYYMMDD

Example: Retrieving the Date With &DATE

The following example incorporates the system variable &DATE into a request. The footing uses the system variable &DATE to insert the current system date at the bottom of the report. 

TABLE FILE SALES
SUM UNIT_SOLD
BY PROD_CODE
FOOTING 
"CALCULATED AS OF &DATE"
END

Example: Retrieving the Procedure Name With &FOCFOCEXEC

The following example incorporates the system variable &FOCFOCEXEC in a report request to display the name of the current procedure. 

SET PAGE=OFF
TABLE FILE EMPLOYEE
"REPORT: &FOCFOCEXEC -- EMPLOYEE SALARIES"
PRINT CURR_SAL BY EMP_ID
ON TABLE SET STYLE *
TYPE=REPORT, SIZE=10, GRID=OFF,$
END

If the request is stored as a FOCEXEC called SALPRINT, the output is: 

REPORT: SALPRINT -- EMPLOYEE SALARIES
 
EMP_ID
 
CURR_SAL
 
071382660
 
$11,000.00
 
112847612
 
$13,200.00
 
115360218
 
$.00
 
117593129
 
$18,480.00
 
119265415
 
$9,500.00
 
119329144
 
$29,700.00
 
121495681
 
$.00
 
123764317
 
$26,862.00
 
126724188
 
$21,120.00
 
219984371
 
$18,480.00
 
326179357
 
$21,780.00
 
451123478
 
$16,100.00
 
543729165
 
$9,000.00
 
818692173
 
$27,062.00

Reference: WebFOCUS Statistical Variables

The following statistical variables are available in WebFOCUS.

Statistical Variable

Description

 
&BASEIO

Is the number of input/output operations.

 
&FOCDISORG

Is the percentage of disorganization for a FOCUS file. 

&FOCERRNUM

Is the last error number, in the format FOCnnnn, displayed after the execution of a procedure. If multiple errors occurred, this variable holds the number of the most recent error. If no error occurred, the variable has a value of 0. 

&INDEXIO

Is the number of indexed input/output operations.

 
&LINES

Is the number of lines printed in last answer set. 

&READS

Is the number of physical reads from an external file. 

&RECORDS

Is the number of records retrieved in last answer set. 

&SORTIO

Is the number of sorted input/output operations.

Example: Counting the Number of Printed Lines With &LINES

In the following example, the system calculates the value of the statistical variable &LINES. If &LINES is 0, control passes to the TABLE FILE EMPLOYEE request identified by the label -RPT2. If the value is not 0, control passes to the label -REPTDONE, and processing is terminated. 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY"
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &CITY
BY PROD_CODE
IF PROD_CODE IS-FROM &CODE1 TO &CODE2
END
-RUN 
-IF &LINES EQ 0 GOTO RPT2 ELSE GOTO REPTDONE;
-RPT2
TABLE FILE EMPLOYEE
   .
   .
   .
END
-RUN 
-QUIT
-REPTDONE
-EXIT