Customizing a Procedure With Variables

Reference: Rules for Supplying Variable Values

The following rules apply to values for variables:

The maximum length of a variable value is 32,000 characters when using the -TYPE or -WRITE command.
If a value contains an embedded comma, equal sign, or blank, you must enclose the variable name in single quotation marks when you use it in an expression. For example, if the value for &CITY is NY, NY, you must refer to the variable as '&CITY' in any expression.
After a value is supplied for a local or global variable, it is used throughout the procedure unless it is changed with a command, such as -SET or -READ.
Variables that are SET with an IF THEN command require an explicit ELSE clause.
You can populate a global variable each time a procedure is executed by including the variable in a WebFOCUS Reporting Server profile, such as EDASPROF.PRF.

Example: Customizing a Procedure With Variable Values

This example illustrates the use of the -DEFAULT and -SET commands to supply values for variables. The end user supplies the value B10 for &CODE1, B20 for &CODE2, and SMITH for &REGIONMGR as prompted by an HTML form.

Note: In this example, the output was formatted to eliminate page numbering and grids. For information on formatting your output, see the Creating Reports With WebFOCUS Language manual.

The numbers to the left of the example apply to the notes that follow:

1. -DEFAULT &VERB=SUM
2. -SET &CITY=IF &CODE1 GT 'B09' THEN 'STAMFORD' ELSE 'UNIONDALE';
3. -TYPE REGIONAL MANAGER FOR &CITY
    SET PAGE=OFF
4.     TABLE FILE SALES
       HEADING CENTER
       "MONTHLY REPORT FOR &CITY"
       "PRODUCT CODES FROM &CODE1 TO &CODE2"
       " "
       &VERB UNIT_SOLD AND RETURNS AND COMPUTE
       RATIO/D5.1 = 100 * (RETURNS/UNIT_SOLD);
       BY PROD_CODE
       IF PROD_CODE IS-FROM &CODE1 TO &CODE2
       FOOTING CENTER
5.     "REGION MANAGER: &REGIONMGR"
       "CALCULATED AS OF &DATE"
       ON TABLE SET STYLE *
       TYPE=REPORT, GRID=OFF,$
       END
6. -RUN

The procedure executes as follows:

The -DEFAULT command sets the value of &VERB to SUM.
The -SET command supplies the value for &CITY depending on the value the end user entered in the form for &CODE1. Because the end user entered B10 as the value for &CODE1, &CITY becomes STAMFORD.
When the end user runs the report, WebFOCUS writes a message that incorporates the value for &CITY:
```
REGIONAL MANAGER FOR STAMFORD
```
The output from -TYPE is not displayed on the HTML page. Instead, it is written to the HTML source file. To display the message, the end user must view the source file of the document.

The stack contains the following lines:

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR STAMFORD"
"PRODUCT CODES FROM B10 TO B20"
" "
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.1 = 100 * (RETURNS/UNIT_SOLD);
BY PROD_CODE
IF PROD_CODE IS-FROM B10 TO B20
FOOTING CENTER
"REGION MANAGER: SMITH"
"CALCULATED AS OF 07/08/93"
END

The end user supplied the value for &REGIONMGR on the form. WebFOCUS supplies the current date at run time.

The -RUN command causes execution of all commands in the stack. The output from the report request is as follows:

MONTHLY REPORT FOR STAMFORD PRODUCT CODES FROM B10 TO B20
PROD_CODE	UNIT_SOLD	RETURNS	RATIO
B10	103	13	12.6
B12	69	4	5.8
B17	49	4	8.2
B20	40	1	2.5
REGION MANAGER: SMITH CALCULATED AS OF 07/08/93

Supplying a Default Variable Value

How to:

Supply a Default Value
Supply a Default Value for a Hidden Variable

-DEFAULT commands set default values for local or global variables. Supplying default values to variables in a stored procedure helps ensure that it runs correctly.

Note that -DEFAULTS is a synonym for -DEFAULT.

You can issue multiple -DEFAULT commands for a variable. If the variable is global, these -DEFAULT commands can be issued in separate FOCEXECs. At any point before another method is used to establish a value for the variable, the most recently issued -DEFAULT command will be in effect.

However, as soon as a value for the variable is established using any other method (for example, by issuing a -SET command, retrieving a value input by the user, or reading a value from a file), subsequent -DEFAULT commands issued for that variable are ignored.

If you want to initialize a variable and prevent it from being used for WebFOCUS parameter prompting, you can use the -DEFAULTH command to initialize the variable. Variables initialized with -DEFAULTH, are not returned in the XML describe information used for parameter prompting. Since these variables are not displayed by the parameter prompting features, they are hidden from the user.

Syntax: How to Supply a Default Value

-DEFAULT[S] &[&]name=value , [&[&]name=value] [;]

where:

&name: Is the name of the variable.
value: Is the default value assigned to the variable.
;: Is an optional punctuation character.

Note: -DEFAULTS is a synonym for -DEFAULT.

Syntax: How to Supply a Default Value for a Hidden Variable

-DEFAULTH &[&]name=value , [&[&]name=value]

where:

&name: Is the name of the variable. This variable is not returned in the XML describe information used for parameter prompting and is, therefore, hidden from the user.
value: Is the default value assigned to the variable.

Example: Supplying a Default Value

In the following example, -DEFAULT sets a default value for &PLANT:

-DEFAULT &PLANT=BOS
TABLE FILE CENTHR
     .
     .
     .

Supplying Variable Values in an Expression

How to:

Assign a Value in an Expression
Specify Precision for Dialogue Manager Calculations

Reference:

Usage Notes for IN FILE

You can assign a value to the variable by computing the value in an expression or assigning a literal value to a variable with the -SET command. You can also use the IN FILE phrase to test whether a character value exists in a file and populate a variable with the result. The value of the variable is set to 1 if the test value exists in the file and 0 (zero) if it does not.

If you want to set a variable value to a number, the only supported characters you can use are numeric digits, a leading minus sign, and a period to represent following decimal places. These are the only valid characters that Dialogue Manager supports in a number, regardless of EDIT options or the value of CDN.

Syntax: How to Assign a Value in an Expression

-SET &[&]name= {expression|value};

-SET &[&]var3= &var1 IN FILE filename1 [OR &var2 IN FILE filename2 ...];

where:

&name: Is the name of the variable.
expression: Is a valid expression. Expressions can occupy several lines, so you should end the command with a semicolon.
value: Is a literal value, or arithmetic or logical expression assigned to the variable. If the literal value contains commas or embedded blanks, you must enclose the value in single quotation marks. If the value contains a single quote, place two single quotes where you want one to appear.
&[&]var3: Is a variable that is populated with the value 1 if the result of the expression on the right side of the equal sign is true, or with the value 0 if the result is false.
&var1: Is the variable that contains the value to be searched for in filename1.
&var2: Is the variable that contains the value to be searched for in filename2.

Reference: Usage Notes for IN FILE

The result of the IN FILE phrase is an alphanumeric value (1 or 0) that can be used in a logical expression connected with AND and OR operators within same –SET command. This value cannot be used as an argument in an alphanumeric operation such as concatenation within the same -SET command.
In order for IN FILE to return the value 1, the values in the file and the search string must match exactly, starting with the leftmost byte in the file.
The file can be in any order and have duplicate values. The search stops when either the first match is found or the end of the file is reached. If the file is allocated but does not exist, the value 0 is returned. If the file is not allocated, a FOC351 message displays in the View Source.
The length of the variable used in the IN FILE phrase determines the number of bytes from the beginning of each record in the file used for comparison. Only an exact match on that number of bytes will return a 1. Trailing blanks in the variable will require the same number of trailing blanks in the file in order to match. For example, the following will match only the value 'ABC ' (ABC with three trailing blanks):
```
-SET &VAR1 = 'ABC   ';
-SET &VAR2 = &VAR1 IN FILE FILE1;
```

Syntax: How to Specify Precision for Dialogue Manager Calculations

The DMPRECISION setting enables Dialogue Manager -SET commands to display and store accurate numeric variable values.

Without this setting, results of numeric calculations are returned as integer numbers, although the calculations themselves employ double-precision arithmetic. To return a number with decimal precision without this setting, you have to enter the calculation as input into function FTOA, where you can specify the number of decimal places returned.

The SET DMPRECISION command gives users the option of either accepting the default truncation of the decimal portion of output from arithmetic calculations, or specifying up to nine decimal places for rounding.

SET DMPRECISION = {OFF|n}

where:

OFF: Specifies truncation without rounding after the decimal point. OFF is the default value.
n: Is a positive number from 0-9, indicating the point of rounding. Note that n=0 results in a rounded integer value.

Note:

When using SET DMPRECISION, you must include -RUN after the SET DMPRECISION command to ensure that it is set prior to any numeric -SET commands.
As the actual conversion to double precision follows the rules for the operating system, the values may vary from platform to platform.

Example: Using SET DMPRECISION

The following table below shows the result of dividing 20 by 3 with varying DMPRECISION (DMP) settings:

SET DMPRECISION =	Result
OFF	6
0	7
1	6.7
2	6.67
9	6.666666667

Example: Setting a Variable Value in an Expression

In the following example, -SET assigns the value 14Z or 14B to the variable &STORECODE, as determined by the logical IF expression. The value of &CODE is supplied by the end user.

-SET &STORECODE = IF &CODE GT C2 THEN '14Z' ELSE '14B';
   TABLE FILE SALES
   SUM UNIT_SOLD AND RETURNS
   BY PROD_CODE
   IF PROD_CODE GE &CODE
   BY STORE_CODE
   IF STORE_CODE IS &STORECODE
   END

Example: Testing Whether a Variable Value Is in a File

The following FOCEXEC creates an alphanumeric HOLD file called COUNTRY1 with the names of countries from the CAR file. It then sets the variable &C equal to FRANCE. The IN FILE phrase returns the value 1 to &IN1 if FRANCE is in the HOLD file and 0 if it is not:

TABLE FILE CAR                                   
PRINT COUNTRY                                    
ON TABLE HOLD AS COUNTRY1 FORMAT ALPHA           
END                                              
-RUN                                             
-SET &C = 'FRANCE';                              
-SET &IN1 = &C IN FILE COUNTRY1;                
-TYPE THE VALUE IS &IN1

The output shows that FRANCE is in the file COUNTRY1:

THE VALUE IS 1

Supplying Variable Values From Another Procedure

How to:

Supply a Variable Value With Another Procedure

Reference:

Rules for Using Named and Positional Variables With EXEC

You can supply values for variables in an EXEC command used in a procedure to call another procedure. See Calling Another Procedure With EXEC for more information on the use of this technique to control application flow.

Values are assigned using a name and value pair, and multiple pairs must be separated by commas. If the list of pairs exceeds the maximum width of the line, insert a comma as the last character on the line and continue the list on the following line. You do not have to enter the pairs in the order in which they are encountered in the procedure.

With EXEC you can supply values for some, but not all, variables used in the procedure. In that case, values not provided in the EXEC command must be supplied using another Dialogue Manager command.

If the variable is positional (that is, if it is a numbered variable), you do not need to specify the variable name in the EXEC command. WebFOCUS matches the EXEC values to the positional variables as they are encountered in the procedure. Therefore, it is critical to enter the appropriate value for each variable in order.

Reference: Rules for Using Named and Positional Variables With EXEC

You can mix named and positional variables freely in the EXEC command by following these rules:

Names must be associated with values for named variables.
Values for positional variables must be supplied in the order that those variables are numbered within the procedure.

The following command is valid for named variables and positional variables:

EX HRINFO SALARY=72000, 5, BOS, STATUS=EMPLOYED

Syntax: How to Supply a Variable Value With Another Procedure

EX[EC] procedure name=value

where:

procedure: Is the name of the procedure that will contain the name/value values.
name: Is the variable name.
value: Is the value you are giving to the variable.

Note: When EXEC is used in Managed Reporting, it is important to note that there is a difference between EX and EXEC. EX statements coded in a procedure are processed by the WebFOCUS Client, which looks for the procedure in the Managed Reporting repository. Procedures that are referenced with an EXEC statement are not processed by the WebFOCUS Client, they are only passed to the WebFOCUS Reporting Server for processing, and these procedures are not looked for in the Managed Reporting repository.

Example: Supplying Values With Another Procedure

Consider the following procedure named SLRPT:

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

You can call this procedure from another procedure and supply values for the variables as parameters using the EX command as follows:

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

Example: Using Positional Variables

Consider the following example:

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

The EX command that calls the procedure is as follows:

EX SLRPT STAMFORD, B10, B20

This command will substitute STAMFORD for the first positional variable, B10 for the second, and B20 for the third.

Reading Variable Values From and Writing Variable Values to an External File

Topics:

Closing an External File

How to:

Retrieve a Variable Value From an External File
Write a Variable Value to an External File
Read Master File Fields Into Dialogue Manager Variables

Reference:

Usage Notes for -READFILE

You can read variable values from an external file, or write variable values to an external file with the -READ and -WRITE commands.

You can supply variable values with the -READ command. For example, an external file may contain the start and end dates of a reporting period. Dialogue manager can read these values from an external file and use them a variable in a WHERE command that limits the range of data selected in a report request.
You can save variable values in an external file with the -WRITE command. For example, a request can store the summed total of sales for the day in an external file so that it can be compared to the total sales of the following day.

The external file can be a fixed-format file (in which the data is in fixed columns) or a free-format file (in which the data is comma delimited).

When using a -READ or -WRITE command, the external file must be included in a FILEDEF command in your procedure. A -RUN command must then separate the FILEDEF command and the -READ or -WRITE command.

You can also read a file using the -READFILE command. The -READFILE command reads a file by first reading its Master File and creating Dialogue Manager amper variables based on the ACTUAL formats for each field in the Master File. It then reads the file and, if necessary, converts the fields from numeric values to alphanumeric strings before returning them to the created variables. Display options in the USAGE formats are not propagated to the variables. The names of the amper variables are the field names prefixed with an ampersand (&).

Syntax: How to Retrieve a Variable Value From an External File

-READ filename[,] [NOCLOSE] &name[.format.][,][&name][.format.]

where:

filename[,]

Is the name of the external file, which must be defined to the operating system. A space after filename denotes a fixed-format file, while a comma denotes a free-format file.

On UNIX and Windows platforms, a FILEDEF for the external file is required.
On z/OS, the external file must be allocated in the JCL or dynamically allocated by WebFOCUS with the ALLOCATE command.

NOCLOSE

Keeps the external file open until the -READ operation is complete. Files kept open with NOCLOSE can be closed using the command -CLOSE filename or a subsequent -WRITE command.

&name[,]

Is the variable name. For free-format files, you may separate the variable names with commas. If the list of variables is longer than one line, end the first line with a comma and begin the next line with a dash followed by a blank. For fixed-format files, including comma-delimited files, begin the next line with a dash, a blank, and a comma (- ,) or a dash and a comma (-,).

Free-format

-READ EXTFILE, &CITY, &CODE1,- &CODE2

Fixed-format

-READ EXTFILE &CITY.A8. &CODE1.A3.,- ,&CODE2.A3.

.format.

Is the format of the variable. For a free-format file, specifying this value is optional. For a fixed-format file, format is the length or the type and the length. The type is either A (alphanumeric), which is the default, or I (numeric). The format value must be delimited by periods. The format is ignored for comma-delimited files.

Note: Instead of using .format., you can specify the length of a variable using -SET and enclosing the corresponding number of blanks in single quotes. For example:

-SET &CITY='        ';
-SET &CODE1='   '; 
-SET &CODE2='   ';

Syntax: How to Write a Variable Value to an External File

-WRITE filename [NOCLOSE] text

where:

filename: Is the name of the file being written to or read from. On UNIX and Windows platforms, filename must specify the absolute path and file name for the called procedure.
NOCLOSE: Keeps the external file open until the -WRITE operation is complete. A file kept open with NOCLOSE can be closed using the command -CLOSE filename.
text: Is any combination of variables and text.

Example: Reading a Value From an External File

Assume that EXTFILE is a fixed-format file containing the following data:

STAMFORDB10B20

To detect the end of a file, the following code tests the system variable &IORETURN. When no records remain to be read, a value equal to zero will not be found.

-READ EXTFILE &CITY.A8. &CODE1.A3. &CODE2.A3.
-IF &IORETURN NE 0 GOTO RESUME;
   TABLE FILE SALES
   SUM UNIT_SOLD
   BY CITY
   IF CITY IS &CITY
   BY PROD_CODE
   IF PROD_CODE IS-FROM &CODE1 TO &CODE2
    END
-RESUME
 .
 .
 .

Example: Reading From and Writing to an External File

The following example reads from and writes to text files and uses FILEDEF commands in a procedure. The numbers on the left apply to the notes that follow. In the example, the user supplies a value for &CITY in an HTML form:

1. -TOP
2.    FILEDEF PASS DISK D:PASS.DAT
   -RUN
3. -WRITE PASS &CITY
      TABLE FILE SALES
      HEADING CENTER
      "LOWEST MONTHLY SALES FOR &CITY"
      " "
      PRINT DATE PROD_CODE
      BY LOWEST 1 UNIT_SOLD
      BY STORE_CODE
      BY CITY
      WHERE CITY EQ '&CITY'
      FOOTING CENTER
      "CALCULATED AS OF &DATE"
      ON TABLE SAVE AS INFO
      END
4. -RUN

5.  FILEDEF LOG DISK D:LOG.DAT
   -RUN
      MODIFY FILE SALES
      COMPUTE
      TODAY/I6=&YMD;
      CITY='&CITY';
      FIXFORM X5 STORE_CODE/A3 X15 DATE/A4 PROD_CODE/A3
      MATCH STORE_CODE DATE PROD_CODE
      ON MATCH TYPE ON LOG
      "<STORE_CODE><DATE><PROD_CODE><TODAY>"
      ON MATCH DELETE
      ON NOMATCH REJECT
      DATA ON INFO
      END
6. -RUN
      EX SLRPT3
7. -RUN
8. -GOTO TOP
9. -QUIT

The procedure SLRPT3, which is invoked from the calling procedure, contains the following lines:

10. -READ PASS &CITY.A8.
      TABLE FILE SALES
      HEADING CENTER
      "MONTHLY REPORT FOR &CITY"
      "LOWEST SALES DELETED"
      " "
      PRINT PROD_CODE UNIT_SOLD RETURNS DAMAGED
      BY STORE_CODE
      BY CITY
      WHERE CITY EQ '&CITY'
      FOOTING CENTER
      "CALCULATED AS OF &DATE"
      END
11. -RUN

The procedure processes as follows:

-TOP marks the beginning of the procedure.
The FILEDEF command defines a file named PASS.
The -WRITE command writes the value of &CITY to the text file named PASS. In this case, assume that the value written is STAMFORD.
The -RUN command executes the stacked report request. In this case, a text file named INFO is created with the SAVE command. This is a sequential file, containing the result of the report request.
The FILEDEF command defines a log file for the subsequent MODIFY request.
The -RUN statement executes the stacked MODIFY request. The data comes directly from the INFO file created in the prior report request and is entered using the FIXFORM statement. The product with the lowest value in UNIT_SOLD is deleted from the data source and logged to a log file.
The next -RUN command executes the procedure called SLRPT3.
The -GOTO TOP statement passes control to the start of the procedure.
-QUIT ends processing.
The -READ command reads the value for &CITY from the text file PASS. In this case, the value passed is STAMFORD.
The -RUN command executes the report request and control is returned to the calling procedure.

Syntax: How to Read Master File Fields Into Dialogue Manager Variables

-READFILE [app/]mastername

where:

app: Is the application directory in which the file resides.
mastername: Is the name of the Master File to be read.

Reference: Usage Notes for -READFILE

A -RUN command does not close the file. You must issue a -CLOSE command to close the file. You must be careful not to delete, change, or re-allocate the file before closing it.
If multiple fields have the same field name, only one variable is created, and it contains the value of the last field in the Master File.
-READFILE does not work if the Master File contains DBA restrictions. The following message is generated:
```
(FOC339) DIALOGUE MANAGER -READ FAILED: CHECK FILEDEF OR ALLOCATION FOR: -READFILE filename
```
-READFILE is not supported with text fields. The following message is generated:
```
(FOC702) THE OPTION SPECIFIED IS NOT AVAILABLE WITH TEXT FIELDS: fieldname
```
-READFILE cannot read XFOCUS data sources. The file to be read must have an associated Master File.

Example: Reading Fields From a Data Source Into Dialogue Manager Variables Using -READFILE

The following request creates a binary HOLD file, then uses -READFILE to read the first record from the HOLD file and type the values that were retrieved into Dialogue Manager variables. Note that the names of the variables are the field names prefixed with an ampersand:

TABLE FILE EMPLOYEE                           
PRINT LAST_NAME FIRST_NAME DEPARTMENT CURR_SAL
BY EMP_ID                                     
ON TABLE HOLD AS READF1 FORMAT BINARY         
END                                           
-RUN                                          
-READFILE READF1                              
-TYPE LAST_NAME  IS &LAST_NAME                
-TYPE FIRST_NAME IS &FIRST_NAME               
-TYPE DEPARTMENT IS &DEPARTMENT               
-TYPE CURR_SAL   IS &CURR_SAL                 
-TYPE EMP_ID     IS &EMP_ID

The output is:

>   NUMBER OF RECORDS IN TABLE=       12  LINES=     12 
                                                        
 HOLDING BINARY FILE...                                             
LAST_NAME  IS STEVENS                                   
FIRST_NAME IS ALFRED                                    
DEPARTMENT IS PRODUCTION                                
CURR_SAL   IS     11000.00                              
EMP_ID     IS 071382660

Closing an External File

How to:

Close an External File

The -CLOSE command closes an external file opened with the -READ or -WRITE command with the NOCLOSE option. The NOCLOSE option keeps a file open until the -READ or -WRITE operation is complete.

Syntax: How to Close an External File

-CLOSE filename

where:

filename: Is a symbolic name associated with a physical file known to the operating system.

Supplying Dates as Variable Values

Topics:

Using Variables With Cross-Century Dates

You can use variables to supply dates to Dialogue Manager. A date supplied to Dialogue Manager cannot be more than 20 characters long, including spaces. Dialogue Manager variables only accept full-format dates (that is, MDY or MDYY, in any order).

Example: Setting the Difference Between Two Dates

In the following example, the variable &DELAY is set to the difference in days between &LATER and &NOW and the result is returned to your browser.

-SET &NOW = 'JUN 30 2002';
-SET &LATER = '2002 25 AUG';
-SET &DELAY = &LATER - &NOW;
-TYPE &DELAY

Using Variables With Cross-Century Dates

If you are working with cross-century dates that do not include a four-digit year, variables are available which allow you to identify the century. For details, see the legacy repository.

Performing a Calculation on a Variable

How to:

Perform a Calculation on a Variable

You can use -SET to define a value for a substituted variable based on the results of a logical or arithmetic expression or a combination.

Syntax: How to Perform a Calculation on a Variable

-SET &name = expression;

where:

&name: Is a user-supplied variable that has its value assigned with the expression.
expression: Is an expression following the rules outlined in the Creating Reports With WebFOCUS Language manual, but with limitations as defined in this topic. The semicolon (;) after the expression is required to terminate the -SET command.

Example: Altering a Variable Value

The following example demonstrates the use of -SET to alter variable values based on tests.

-SET &OPERATOR = IF &CHOICE EQ A THEN 'GT' ELSE 'LT'; 
   TABLE FILE SALES
   PRINT PROD_CODE UNIT_SOLD RETAIL_PRICE
   BY STORE_CODE BY DATE
   IF RETAIL_PRICE &OPERATOR 2.00
   END

Assuming the user enters the letter A, -SET assigns the string value GT to &OPERATOR. Then, the value GT is passed to the &OPERATOR variable in the procedure, so that the expanded FOCUS command at execution time is:

IF RETAIL_PRICE GT 2.00

Changing a Variable Value With the DECODE Function

You can use the DECODE function to change a variable to an associated value.

Example: Changing the Value of a Variable

In this example, the variable refers to a movie rating:

&SELECT. ENTER A,B,C,D,E. 
-SET &RATING = DECODE &SELECT (A G B PG13 C R D NR E PG);
TABLE FILE MOVIES
PRINT TITLE BY RATING
IF RATING EQ &RATING
END

For more information on DECODE, see the Using Functions manual.

Validating a Variable Value

Topics:

Verifying the Presence, Value, Length, or Type of User-Supplied Values
Validating Variable Values Without Data File Access: REGEX
Verifying User-Supplied Values Against a Set of Format Specifications
Verifying User-Supplied Values Against a Value Range

To ensure that a supplied value is valid and being used properly in a procedure, you can test it for presence, type, and length. You can also verify that it has an acceptable format and that it falls within a specific range of values. For example, you would not want to perform a numeric computation on a variable for which alphanumeric data has been supplied.

Verifying the Presence, Value, Length, or Type of User-Supplied Values

How to:

Verify the Presence, Value, Length, or Type of Variable Values

You screen a value by adding a suffix to the variable value:

The .EXIST suffix tests the presence of a value.
The .EVAL suffix replaces a variable with its value.
The .LENGTH suffix tests the length of a value.
The .TYPE suffix tests the type of a value.
The .DATE_LOCALE suffix applies the DATE_SEPARATOR, DATE_ORDER, and TIME_SEPARATOR parameter values to date system amper variables.

Reference: Usage Notes for .EVAL

A Dialogue Manager variable is a placeholder for a value that will be substituted at run time. In some situations, the value of the variable may not be resolved at the point where the command containing the variable is encountered, unless evaluation is forced by using the .EVAL operator. One example where .EVAL Is required is in a -IF statement, when the variable is embedded in a label (for example, GOTO AB&label.EVAL). The .EVAL operator is also required any time a variable is included within single quotation marks (').

Syntax: How to Verify the Presence, Value, Length, or Type of Variable Values

-IF &name{suffix} expression GOTO label...;

where:

&name

Is a user-supplied variable.

suffix

Is one of the following:

.EXIST, which tests for the presence of a value. If a value is not present, a zero (0) is passed to the expression. Otherwise, a non-zero value is passed.
.LENGTH, which tests for the length of a value. If a value is not present, a zero (0) is passed to the expression. Otherwise, the number of characters in the value is passed.
.TYPE, which tests for the type of a value. The letter N (numeric) is passed to the expression if the value can be interpreted as a number up to 10⁹-1 and stored in four bytes as a floating point format. In Dialogue Manager, the result of an arithmetic operation with numeric fields is truncated to an integer after the whole result of an expression is calculated. If the value could not be interpreted as numeric, the letter A (alphanumeric) is passed to the expression.
.EVAL, which replaces a variable with its value. The .EVAL operator enables you to evaluate the value of a variable immediately, making it possible to change a procedure dynamically. The .EVAL operator is particularly useful in modifying code at run time. When the command procedure is executed, the expression is replaced with the value of the specified variable before any other action is performed. Without the .EVAL operator, a variable cannot be used in place of some commands.

expression

Is a valid expression that uses &name with the specified suffix as a variable.

GOTO label

Specifies a label to branch to.

Example: Testing for the Presence of a Variable

If a value is not supplied in the following example, &OPTION.EXIST is equal to zero and control is passed to the label -CANTRUN. The -HTMLFORM displays a message that the procedure cannot run. If a value is supplied, control passes to the label -PRODSALES.

-IF &OPTION.EXIST GOTO HRINFO ELSE GOTO CANTRUN; 
     .
     .
     .
-HRINFO
   TABLE FILE CENTHR
     .
     .
     .
   END
-EXIT
-CANTRUN 
-HTMLFORM BEGIN
<HTML>
<BODY>
TOTAL REPORT CAN'T BE RUN WITHOUT AN OPTION.
</BODY>
</HTML>
-HTMLFORM END
-EXIT

Example: Testing for the Length of a Variable With an HTML Format Message

If the length of the value supplied for &OPTION is more than one character, control passes to the label -FORMAT. Control then continues to the command -HTMLFORM, which displays a message, informing the user that only a single character can be entered.

-IF &OPTION.LENGTH GT 1 GOTO FORMAT ELSE
-GOTO PRODSALES;
     .
     .
     .
-PRODSALES
   TABLE FILE SALES
     .
     .
     .
   END
-EXIT
-FORMAT
-HTMLFORM BEGIN
<HTML>
<BODY>
ONLY A SINGLE CHARACTER IS ALLOWED.
</BODY>
</HTML>
-HTMLFORM END

Example: Testing for the Length of a Variable

If the length of &OPTION is greater than one character, control passes to the label -FORMAT. The -HTMLFORM command then displays a message informing the user that only a single character can be entered.

-TOP
-IF &OPTION.LENGTH GT 1 GOTO FORMAT ELSE
-GOTO PRODSALES;
     .
     .
     .
-PRODSALES
   TABLE FILE SALES
     .
     .
     .
   END
-EXIT
-FORMAT
-HTMLFORM BEGIN
<HTML>
<BODY>
PLEASE ENTER ONLY ONE CHARACTER.
</BODY>
</HTML>
-HTMLFORM 
END

Example: Testing for the Type of a Value

If &OPTION is not alphanumeric, control passes to the label -NOALPHA. -HTMLFORM displays an HTML page that informs the user that only alphanumeric characters are allowed.

-IF &OPTION.TYPE NE A GOTO NOALPHA ELSE
- GOTO HRINFO;
      .
      .
      .
-HRINFO
   TABLE FILE CENTHR
      .
      .
      .
   END
-EXIT
-NOALPHA
-HTMLFORM BEGIN
<HTML>
<BODY>
ENTER A LETTER ONLY.
</BODY>
</HTML>
-HTMLFORM

Example: Using .EVAL to Allow WebFOCUS to Interpret a Variable

The code

-SET &A='-TYPE';
&A HELLO

produces an error message which shows that WebFOCUS does not recognize the value of &A:

Appending the .EVAL operator to the &A variable makes it possible for WebFOCUS to interpret the variable correctly. Adding the .EVAL operator as follows

-SET &A='-TYPE';
&A.EVAL HELLO

produces the following output:

Example: Evaluating a Variable Immediately

The following example illustrates how to use the .EVAL operator in a record selection expression. The numbers to the left apply to the notes that follow the procedure:

1. -SET &R='IF SALARY GT 60000';
2. -IF &Y EQ 'YES' THEN GOTO START;
3. -SET &R = '-*';
   -START
4.   TABLE FILE CENTHR
     PRINT SALARY 
     BY PLANT BY LNAME
5.   &R.EVAL
     END

The procedure executes as follows:

The procedure sets the value of &R to 'IF SALARY GT 60000'.
If &Y is YES, the procedure branches to the START label, bypassing the second -SET command.
If &Y is NO, the procedure continues to the second -SET command, which sets &R to '-*', which is a comment.
The report request is stacked.
The procedure evaluates the value of &R. If the end user wanted a record selection test, the value of &R is 'IF SALARY GT 60000' and this line is stacked.
If the end user did not want a record selection test, the value of &R is '-*' and this line is ignored.

Reference: Applying Date and Time Locale Parameters to System Date Variables

The DATE_SEPARATOR parameter defines a date separator character and the DATE_ORDER parameter defines the order of components for dates, based on your locale. The TIME_SEPARATOR parameter defines the time separator character for the &TOD variable. To use these settings with the Dialogue Manager system variables, (for example, &DATE, &TOD, &YMD, &DATEfmt, and &DATXfmt) append the suffix .DATE_LOCALE to the system variable. This allows system variables that are localized to coexist with non-localized system variables.

Example: Setting Date and Time Parameters for System Variables

The following applies the DATE_ORDER and DATE_SEPARATOR parameters to the &DATE system variable.

SET DATE_SEPARATOR = DASH
SET DATE_ORDER = DMY
-TYPE NON-LOCALIZED: &DATE
-TYPE LOCALIZED: &DATE.DATE_LOCALE

The output is:

NON-LOCALIZED: 04/07/17
LOCALIZED: 07-04-17

Validating Variable Values Without Data File Access: REGEX

How to:

Validate a Variable Value Using a REGEX Mask

You can validate a parameter value without accessing the data by using the REGEX mask. The REGEX mask specifies a regular expression to be used as the validation string. A regular expression is a sequence of special characters and literal characters that you can combine to form a search pattern.

Many references for regular expressions exist on the web. For a basic summary, see the section Summary of Regular Expressions in Chapter 2, Security, of the Server Administration manual.

The following messages display in case of an error:

(FOC2909) INVALID REGULAR EXPRESSION: 
(FOC2910) RESPONSE DOES NOT MATCH THE REGULAR EXPRESSION:

Syntax: How to Validate a Variable Value Using a REGEX Mask

&variable.(|VALIDATE=REGEX,REGEX='regexpression').

where:

&variable: Is the variable to validate.
regexpression: Is the regular expression that specifies the acceptable values.

Example: Using a REGEX Mask to Validate a Social Security Number

The following request validates a Social Security number in either xxxxxxxxx or xxx-xx-xxxx format:

-REPEAT NEXTFMT FOR &FMTCNT FROM 1 TO 2
-SET &EMPID1=DECODE &FMTCNT(1 '071382660' 2 '818-69-2173'); 
-SET &EMPID=IF 
        &EMPID1.(|VALIDATE=REGEX,REGEX='^\d{3}\-?\d{2}\-?\d{4}$').Employee ID. CONTAINS '-' 
-       THEN EDIT(&EMPID1,'999$99$9999') ELSE &EMPID1; 
TABLE FILE EMPLOYEE 
HEADING
" "
"Testing EMPID = &EMPID1</1"                                                                   
PRINT EID CSAL                                                          
WHERE EID EQ '&EMPID.EVAL' 
ON TABLE SET PAGE NOPAGE
ON TABLE SET STYLE *
GRID=OFF,$
END 
-RUN 
-NEXTFMT

The output is

Testing EMPID = 071382660 
  
 
EMP_ID CURR_SAL 
071382660 $11,000.00 
  
Testing EMPID = 818-69-2173 
  
 
EMP_ID CURR_SAL 
818692173 $27,062.00

Example: Using REGEX With an Incorrect Value

In the following request, the second value for &EMPID1 is invalid because it does not conform to the REGEX mask:

-REPEAT NEXTFMT FOR &FMTCNT FROM 1 TO 2
-SET &EMPID1=DECODE &FMTCNT(1 '071382660' 2 '818-69-2173'); 
-TYPE EMPID1 = &EMPID1
-SET &EMPID=&EMPID1.(|VALIDATE=REGEX,REGEX='^\d{3}\d{2}\d{4}$').Employee ID.; 
-TYPE EMPID = &EMPID
-NEXTFMT

The FOC2910 message in the output shows that the second value for &EMPID1 was rejected:

EMPID1 = 071382660
EMPID = 071382660
EMPID1 = 818-69-2173
 ERROR AT OR NEAR LINE      7  IN PROCEDURE __WCFEX FOCEXEC * 
(FOC2910)  RESPONSE DOES NOT MATCH THE REGULAR EXPRESSION: 818-69-2173 
 ERROR AT OR NEAR LINE      7  IN PROCEDURE __WCFEX FOCEXEC *     
(FOC295) A VALUE IS MISSING FOR: &EMPID1

Example: Using REGEX With an Invalid Regular Expression

In the following request, the REGEX mask is not a valid regular expression:

-SET &EMPID1='071382660'; 
-SET &EMPID=&EMPID1.(|VALIDATE=REGEX,REGEX='^\d{3}\d{2)}\d{4}$').Employee ID.;

The FOC2909 message in the output shows that the regular expression is not valid:

ERROR AT OR NEAR LINE      5  IN PROCEDURE __WCFEX FOCEXEC *
(FOC2909)  INVALID REGULAR EXPRESSION: ^\d{3}\d{2)}\d{4}$      
 ERROR AT OR NEAR LINE      5  IN PROCEDURE __WCFEX FOCEXEC *   
(FOC295) A VALUE IS MISSING FOR: &EMPID1

Verifying User-Supplied Values Against a Set of Format Specifications

Reference:

Format Specifications for Variables

You can specify that a variable must adhere to a set of format conditions against which entered values can be compared. If the entered value does not have the specified format, a message displays informing the user that there are too many characters. The user can acknowledge the message and can try again to enter a valid value.

Reference: Format Specifications for Variables

Alphanumeric formats are described by the letter A, followed by the number of characters. The number of characters can be from 1 to 3968.

Numeric formats are described by the letter I, followed by the number of digits to be entered. The number of digits can be from 1 to 10 (value must be less than 2³¹-1), and the value supplied for the number can contain a decimal point.

The description of the format must be enclosed within periods (.).

If you test field names against input variable values, specify formats of the input variables. If you do not, and the supplied value exceeds the format specification from the Master File, the procedure is ended and error messages are displayed. To continue, the procedure must be executed again. However, if you do include the format, and the supplied value exceeds the format, the entered value will be rejected and the user is prompted again.

Note: Parameter values are internally stored in memory as alphanumeric codes. To perform arithmetic operations, the parameter value is converted to double precision floating point decimal and then the result is converted back to alphanumeric codes, dropping the decimal places. For this reason, do not perform tests that look for the decimal places in the numeric codes.

Example: Using a Format Specification to Verify User Input

Consider the following format specification for the STATE and QTY_IN_STOCK fields.

TABLE FILE CENTORD
BY QTY_IN_STOCK 
BY STATE
BY PROD_NUM
BY PRODNAME
ON TABLE SUBHEAD
"Inventory Report"
WHERE STATE EQ '&STATE.A2.US State:.'
WHERE QTY_IN_STOCK LT '&PRODNUM.I7.Quantity in Stock below:.'
END

If, in the above example, the user enters more than two alphanumeric characters for the STATE value it is rejected, the message There are too many characters in your entry. is displayed, and the user is prompted again.

If, in the above example the user enters more than seven numeric characters for the QTY_IN_STOCK, the value is rejected, the message There are too many digits in your entry: (format is 'I7') is displayed, and the user is prompted again.

Verifying User-Supplied Values Against a Value Range

Reference:

Value Range Specifications for Variables

You can specify that a variable value must fall within a range of values against which entered values can be compared. If the entered value is not within the specified value range, a message displays informing the user that there are too many characters. The user can acknowledge the message and can try again to enter a valid value.

Reference: Value Range Specifications for Variables

A value range is enclosed within parenthesis specifying (FROM value1 TO value2), where value1 is a numeric value less than value2. For example,

&QTY_IN_STOCK.(FROM 1 TO 10000)

Note: Parameter values are internally stored in memory as alphanumeric codes. To perform arithmetic operations, the parameter value is converted to double precision floating point decimal, and then the result is converted back to alphanumeric codes, dropping the decimal places. For this reason, do not perform tests that look for the decimal places in the numeric codes.

Example: Using a Value Range Specification to Verify User Input

Consider the following value range specification for the &QTY_IN_STOCK variable.

TABLE FILE CENTINV
PRINT QTY_IN_STOCK 
BY PROD_NUM 
BY PRODNAME
ON TABLE SUBHEAD
"Inventory Report"
WHERE QTY_IN_STOCK LT &QTY_IN_STOCK.(FROM 1 TO 10000).Quantity in Stock below:.
END

If, in the above example, the user enters a value less than 1 and more than 10000 for the Quantity in Stock below parameter value, the value is rejected and the message value entered is not within range 1 - 10000 is displayed.

Counting With an Indexed Variable

How to:

Create an Indexed Variable

You can append the value of one variable to the value of another variable, creating an indexed variable. This feature applies to both local and global variables.

If the indexed value is numeric, the effect is similar to that of an array in traditional computer programming languages. For example, if the value of index &K varies from 1 to 10, the variable &AMOUNT.&K refers to one of ten variables, from &AMOUNT1 to &AMOUNT10.

A numeric index can be used as a counter, and it can be set, incremented, and tested in a procedure.

Syntax: How to Create an Indexed Variable

-SET &name.&index[.&index...] = expression;

where:

&name

Is a variable.

.&index

Is a numeric or alphanumeric variable whose value is appended to &name. The period is required.

When more than one index is used, all index values are concatenated and the string appends to the name of the variable.

For example, &V.&I.&J.&K is equivalent to &V1120 when &I=1, &J=12, and &K=0.

expression

Is a valid expression. For information on the kinds of expressions you can write, see the Creating Reports With WebFOCUS Language manual.

Example: Using an Indexed Variable in a Loop

An indexed variable can be used in a loop. The following example creates the equivalent of a DO loop used in traditional programming languages:

-SET &N = 0;
-LOOP
-SET &N = &N+1;
-IF &N GT 12 GOTO OUT;
-SET &MONTH.&N=&N;
-TYPE &MONTH.&N 
-GOTO LOOP
-OUT

In this example, &MONTH is the indexed variable and &N is the index. The value of the index is supplied through the command -SET. The first -SET initializes the index to 0, and the second -SET increments the index each time the procedure goes through the loop.

If the value of an index is not defined prior to reference, a blank value is assumed. As a result, the name and value of the indexed variable will not change.

Indexed variables are included in the system limit of 384 variables.