You can use a variety of techniques to manipulate and test Dialogue Manager variables.
|
How to: |
To ensure that a supplied value is valid and being used properly in a procedure, you can test it for presence, type, and length. For example, you would not want to perform a numerical computation on a variable for which alphanumeric data has been supplied.
-IF &name{.LENGTH|TYPE} rest_of_expression GOTO label...; where:
Is a user-supplied variable.
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.
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 231-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. If the value is not defined, the letter U is passed to the expression.
Is the remainder of an expression that uses &name with the specified suffix.
Specifies a label to branch to.
If the length of &OPTION is more than one character, control passes to the label -FORMAT, which informs the client application that only a single character is allowed.
-IF &OPTION.LENGTH GT 1 GOTO FORMAT ELSE
-GOTO PRODSALES;
.
.
.
-PRODSALES
TABLE FILE SALES
.
.
.
END
-EXIT
-FORMAT
-TYPE ONLY A SINGLE CHARACTER IS ALLOWED. The following example sets the variable &WORDLEN to the length of the string contained in the variable &WORD.
-PROMPT &WORD.ENTER WORD. -SET &WORDLEN = &WORD.LENGTH;
You can use this technique when you want to use one variable to populate another.
If &OPTION is not alphanumeric, control passes to the label -NOALPHA, which informs the client application that only alphanumeric characters are allowed.
-IF &OPTION.TYPE NE A GOTO NOALPHA ELSE
- GOTO PRODSALES;
.
.
.
-PRODSALES
TABLE FILE SALES
.
.
.
END
-EXIT
-NOALPHA
-TYPE ENTER A LETTER ONLY. -IF &name.EXIST GOTO label...;
where:
Is a user-supplied variable.
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.
Specifies a label to branch to.
If no value is supplied, &OPTION.EXIST is equal to zero and control is passed to the label ‑CANTRUN. The procedure sends a message to the client application and then exits. If a value is supplied, control passes to the label ‑PRODSALES.
-IF &OPTION.EXIST GOTO PRODSALES ELSE GOTO CANTRUN;
.
.
.
-PRODSALES
TABLE FILE SALES
.
.
. END -EXIT -CANTRUN -TYPE TOTAL REPORT CAN'T BE RUN WITHOUT AN OPTION. -EXIT
|
How to: |
The .EVAL operator enables you to replace a variable with its value immediately, making it possible to change a procedure dynamically. The .EVAL operator is particularly useful in modifying code at run time.
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 (').
[&]&variable.EVAL
where:
Is a local or global variable.
When the command procedure is executed, the expression is replaced with the value of the specified variable before any other action is performed. The command that contains this value is then re-evaluated.
Without the .EVAL operator, a variable cannot be used in place of some commands.
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 100000';
2. -IF &Y EQ 'YES' THEN GOTO START;
3. -SET &R = '-*';
-START
4. TABLE FILE CENTHR
SUM SALARY
BY PLANT
5. &R.EVAL
END
The procedure executes as follows:
The report request is stacked.
Without .EVAL, Dialogue Manager interprets a variable only once. Therefore, in the following example,
-SET &A='-TYPE'; &A HELLO
Dialogue Manager does not recognize that &A is the -TYPE command so it does not display the word HELLO and generates the error message:
UNKNOWN FOCUS COMMAND -TYPE
Appending the .EVAL operator to the &A variable enables Dialogue Manager to interpret the variable correctly. The code
-SET &A='-TYPE'; &A.EVAL HELLO
produces the following output:
HELLO >>
|
How to: |
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:
&variable.(|VALIDATE=REGEX,REGEX='regexpression').
where:
Is the variable to validate.
Is the regular expression that specifies the acceptable values.
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
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
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|
How to: |
You can append a variable to a character string or combine two or more variables and/or literals. See the Creating Reports manual for complete information on concatenation. When using variables, it is important to separate each variable from the concatenation symbol (||) with a space.
-SET &name3 = &name1 || &name2;
where:
Is the name of the concatenated variable.
Are the variables, separated by a space and the concatenation symbol.
Note: The example shown uses strong concatenation, indicated by the || symbol. Strong concatenation moves any trailing blanks from &name1 to the end of the result. Conversely, weak concatenation, indicated by the symbol |, preserves any trailing blanks in &name1.
|
How to: |
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; it can be set, incremented, and tested in a procedure.
-SET &name.&index[.&index...] = expression;
where:
Is a variable.
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.
Is a valid expression. For information on the kinds of expressions you can write, see the Creating Reports manual.
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 do not change.
Indexed variables are included in the system limit of 1024, which includes variables reserved by FOCUS.
|
How to: |
|
Reference: |
Character strings must be enclosed in single quotation marks to be handled by most database engines. In addition, embedded single quotation marks are indicated by two contiguous single quotation marks. FOCUS, WebFOCUS, and iWay require quotes around variables containing delimiters, which include spaces and commas.
The QUOTEDSTRING suffix on a Dialogue Manager variable applies the following two conversions to the contents of the variable:
Dialogue Manager commands differ in their ability to handle character strings that are not enclosed in single quotation marks and contain embedded blanks. An explicit or implied ‑PROMPT command can read such a string. The entire input string is then enclosed in single quotation marks when operated on by .QUOTEDSTRING.
Note: When using the -SET command to reference a character string, ensure the character string is enclosed in single quotes to prevent errors.
&var.QUOTEDSTRING
where:
Is a Dialogue Manager variable.
The following example shows the results of the QUOTEDSTRING suffix on input strings.
-SET &A = ABC; -SET &B = 'ABC'; -SET &C = O'BRIEN; -SET &D = 'O'BRIEN'; -SET &E = 'O''BRIEN'; -SET &F = O''BRIEN; -SET &G = OBRIEN'; -TYPE ORIGINAL = &A QUOTED = &A.QUOTEDSTRING -TYPE ORIGINAL = &B QUOTED = &B.QUOTEDSTRING -TYPE ORIGINAL = &C QUOTED = &C.QUOTEDSTRING -TYPE ORIGINAL = &D QUOTED = &D.QUOTEDSTRING -TYPE ORIGINAL = &E QUOTED = &E.QUOTEDSTRING -TYPE ORIGINAL = &F QUOTED = &F.QUOTEDSTRING -TYPE ORIGINAL = &G QUOTED = &G.QUOTEDSTRING
The output is:
ORIGINAL = ABC QUOTED = 'ABC' ORIGINAL = ABC QUOTED = 'ABC' ORIGINAL = O'BRIEN QUOTED = 'O''BRIEN' ORIGINAL = O'BRIEN QUOTED = 'O''BRIEN' ORIGINAL = O'BRIEN QUOTED = 'O''BRIEN' ORIGINAL = O''BRIEN QUOTED = 'O''''BRIEN' ORIGINAL = OBRIEN' QUOTED = 'OBRIEN'''
ORIGINAL = ABC QUOTED = 'ABC' ORIGINAL = ABC QUOTED = 'ABC' ORIGINAL = O'BRIEN QUOTED = 'O''BRIEN' ORIGINAL = O'BRIEN QUOTED = 'O''BRIEN' ORIGINAL = O'BRIEN QUOTED = 'O''BRIEN' ORIGINAL = O''BRIEN QUOTED = 'O''''BRIEN' ORIGINAL = OBRIEN' QUOTED = 'OBRIEN'''
Note: The -SET command will remove single quotes around a string. Notice in the example above that the result of -SET &B = 'ABC' was changed to ORIGINAL = ABC (as shown in the output), prior to the QUOTEDSTRING conversion.
The following -TYPE command accepts quoted or unquoted input and displays quoted output.
-TYPE THE QUOTED VALUE IS: &E.QUOTEDSTRING
The output is:
PLEASE SUPPLY VALUES REQUESTED E= O'BRIEN THE QUOTED VALUE IS: 'O''BRIEN'
The following procedure creates an Oracle table named SQLVID from the VIDEOTRK data source.
TABLE FILE VIDEOTRK SUM CUSTID EXPDATE PHONE STREET CITY STATE ZIP TRANSDATE PRODCODE TRANSCODE QUANTITY TRANSTOT BY LASTNAME BY FIRSTNAME WHERE LASTNAME NE 'NON-MEMBER' ON TABLE HOLD END -RUN CREATE FILE SQLVID -RUN MODIFY FILE SQLVID FIXFORM FROM HOLD DATA ON HOLD END
Consider the following SQL Translator request:
SET TRACEUSER = ON SET TRACEON = STMTRACE//CLIENT SQL SELECT * FROM SQLVID WHERE LASTNAME = &1.QUOTEDSTRING; END
When this request is executed, you must enter a last name, in this case O'BRIEN:
PLEASE SUPPLY VALUES REQUESTED 1= O'BRIEN
In the generated SQL request, the character string used for the comparison is correctly enclosed in single quotation marks, and the embedded single quote is doubled:
SELECT SQLCOR01.CIN , SQLCOR01.LN , SQLCOR01.FN , SQLCOR01.EXDAT , SQLCOR01.TEL , SQLCOR01.STR , SQLCOR01.CITY , SQLCOR01.PROV , SQLCOR01.POSTAL_CODE , SQLCOR01.OUTDATE , SQLCOR01.PCOD , SQLCOR01.TCOD , SQLCOR01.NO , SQLCOR01.TTOT FROM SQLVID SQLCOR01 WHERE SQLCOR01.LN = 'O''BRIEN';
The output is:
CIN LN FN ... --- -- -- ... 5564 O'BRIEN DONALD ...
The following input variations are translated to the correct form of quoted string demonstrated in the trace.
'O'BRIEN' 'O''BRIEN'
Any other variation results in:
Error - Semi-colon or END expected
Error - Missing or Misplaced quotes
Error - (value entered) is not a valid column
Error - Syntax error on line ... Unbalanced quotes
Strings without embedded single quotation marks can be entered without quotes or embedded in single quotation marks, either SMITH or 'SMITH'.
If you use &1 without the QUOTEDSTRING suffix in the request, acceptable input strings that retrieve O'Brien's record are:
'''O'''BRIEN''' '''O''''BRIEN'''
Using &1 without the QUOTEDSTRING suffix, the acceptable form of a string without embedded single quotation marks is '''SMITH'''.
To make a string enclosed in single quotation marks acceptable without the QUOTEDSTRING suffix, use '&1' in the request. In this case, in order to retrieve O'Brien's record, you must enter the string that would have resulted from the QUOTEDSTRING suffix:
'O''''BRIEN'
To enter a string without embedded single quotation marks using '&1', you can either omit the surrounding single quotation marks or include them: SMITH or 'SMITH'.
Note: The form '&1.QUOTEDSTRING' is not supported.
An unmatched single quotation mark at the beginning of a character string is treated as invalid input and generates the following message:
(FOC257) MISSING QUOTE MARKS: value;
|
How to: |
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.
-SET &name = expression;
where:
Is a user-supplied variable that has its value assigned with the expression.
Is an expression following the rules outlined in the Creating Reports manual, but with limitations as defined in this topic. The semicolon after the expression is required to terminate the -SET command. For information about setting a precision for Dialogue Manager calculations, see Specify Precision for Dialogue Manager Calculations.
The following example demonstrates the use of -SET to alter variable values based on tests.
-START -TYPE RETAIL PRICE ABOVE OR BELOW $1.00 IN THIS REPORT? -PROMPT &CHOICE.ENTER A OR B. -SET &REL = 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 &REL 1.00 END
In the example, the &CHOICE variable receives either A or B as the value supplied through -PROMPT. Assuming the user enters the letter A, -SET assigns the string value GT to &REL. Then, the value GT is passed to the &REL variable in the procedure, so that the expanded FOCUS command at execution time is:
IF RETAIL_PRICE GT 1.00
You can use the DECODE function to change a variable to an associated value.
In this example the variable refers to a label:
1. -PROMPT &SELECT. ENTER CHOICE (A,B,C,D,E).
2. -SET &GO=DECODE &SELECT (A ONE B TWO C THREE
- D FOUR E FIVE ELSE EXIT);
3. -GOTO &GO
-ONE
.
.
.
-TWO
.
.
.
The example processes as follows:
In the example, &GO can be another procedure (see Dialogue Manager Quick Reference) that is executed, depending on the value that is decoded:
-TOP -TYPE -PROMPT &SELECT.ENTER 1, 2, 3, 4, 5, OR EXIT TO END. -SET &GO=DECODE &SELECT (1 ONE 2 TWO 3 THREE - 4 FOUR 5 FIVE ELSE EXIT); -IF &GO IS EXIT GOTO EXIT; EX &GO -RUN -GOTO TOP -EXIT
For more information on DECODE, see the Using Functions manual.
You can use the mask option of the EDIT function with amper variables. You can insert characters into an alphanumeric value, or extract certain characters from the value.
In this example, EDIT extracts a particular character, in this case the J, for comparison in order to branch to the appropriate label. Assume there are nested menus and the user must supply a number to branch to a particular menu. If the first character is a J, the branch is to the label JUMP that enables the user to jump in nested menus (the numbers refer to the explanation below):
1. -TYPE CHOOSE 1 for Edit, 2 for Print, 3 for Math
1. -TYPE TO JUMP LEVELS OF MENUS TYPE J1.3 ETC.
2. -PROMPT &OPTION.A4.Please enter selection:.
3. -SET &XYZ = EDIT(&OPTION, '9$$$');
4. -IF &XYZ EQ J THEN GOTO JUMP;
.
.
.
5. -JUMP
.
.
.
The example processes as follows:
|
How to: |
The Dialogue Manager TRUNCATE function removes trailing blanks from Dialogue Manager amper variables and adjusts the length accordingly.
The Dialogue Manager TRUNCATE function has only one argument, the string or variable to be truncated. 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'
This function can only be used in Dialogue Manager commands that support function calls, such as -SET and -IF commands. It cannot be used in -TYPE or -CRTFORM commands or in arguments passed to stored procedures.
Note: A user-written function of the same name can exist without conflict.
-SET &var2 = TRUNCATE(&var1);
where:
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 minus the trailing blanks. If the original string consisted of only blanks, a single blank, with a length of one is returned.
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.
The following example shows the result of truncating trailing blanks:
-SET &LONG = 'ABC ' ; -SET &RESULT = TRUNCATE(&LONG); -SET &LL = &LONG.LENGTH; -SET &RL = &RESULT.LENGTH; -TYPE LONG = &LONG LENGTH = &LL -TYPE RESULT = &RESULT LENGTH = &RL
The output is:
LONG = ABC LENGTH = 06 RESULT = ABC LENGTH = 03
The following example shows the result of truncating a string that consists of all blanks:
-SET &LONG = ' ' ; -SET &RESULT = TRUNCATE(&LONG); -SET &LL = &LONG.LENGTH; -SET &RL = &RESULT.LENGTH; -TYPE LONG = &LONG LENGTH = &LL -TYPE RESULT = &RESULT LENGTH = &RL
The output is:
LONG = LENGTH = 06 RESULT = LENGTH = 01
The following example uses the TRUNCATE function as an argument for EDIT:
-SET &LONG = 'ABC ' ; -SET &RESULT = EDIT(TRUNCATE(&LONG)|'Z','9999'); -SET &LL = &LONG.LENGTH; -SET &RL = &RESULT.LENGTH; -TYPE LONG = &LONG LENGTH = &LL -TYPE RESULT = &RESULT LENGTH = &RL
The output is:
LONG = ABC LENGTH = 06 RESULT = ABCZ LENGTH = 04
|
How to: |
Any function name encountered in a Dialogue Manager expression that is not recognized as a system standard name or FOCUS function is assumed to be a function. These functions are externally programmed by users and stored in a library that is available at the time referenced. One or more arguments are passed to the user program, which performs an operation or calculation and returns a single value or character string.
Dialogue Manager variables can receive the values from functions through the -SET command.
-SET &name = routine(argument,...,'format');
where:
Is the name of the variable in which the result is stored.
Is the name of the function.
Represents the argument(s) that must be passed to the function. Numeric arguments are converted to double-precision (D) format.
Is the predefined format of the result. This is used to convert numeric results back to character representation. It must be enclosed in single quotation marks.
In the following example, FOCUS invokes the function RATE, adds 0.5 to the calculated value, and then formats the result as a double precision number. This result is then stored in the variable &COST:
-PROMPT &COMPANY.WHAT COMPANY ARE YOU USING?. -PROMPT &DEST.WHERE ARE YOU SENDING THE PACKAGE TO?. -PROMPT &WEIGHT.HOW HEAVY IS THE PACKAGE IN POUNDS?. -SET &COST = RATE(&COMPANY,&DEST,&WEIGHT,'D6.2') + 0.5; -TYPE THE COST TO SEND A &WEIGHT pound PACKAGE -TYPE TO &DEST BY &COMPANY IS &COST
These Dialogue Manager commands cause a function to be loaded and executed.
The commands provide an alternative to -SET, which is generally the preferred method for calling user-supplied functions (see Set a Variable Value Based on the Result From a Function).
However,-TSO/-MVS RUN must be used for this purpose when the function being called:
The syntax is
{-TSO|-MVS} RUN routine[, argument,...] where:
Is the name of the function.
Represents the argument(s) being passed to the function. Arguments that are variables must have sizes predefined in prior -SET commands.
If you use this syntax, please note the foIlowing:
In this example, the function is CODENAME. The arguments that are variables are either prompted for or set at the beginning of the procedure and values are then supplied for the arguments.
-PROMPT &MYCODE.A3. -SET &MYNAME = ''; -SET &MYFACTOR = '' ; -TSO RUN CODENAME,&MYCODE,&MYNAME,&MYFACTOR
A variable can refer to a FOCUS command or to a particular field. Therefore, the command structure of a procedure can be determined by the value of the variable.
In this example, the variable &FIELD determines the field to print in the TABLE request.
In the file named SALES, the variable &FIELD can display the values RETURNS, DAMAGED, or UNIT_SOLD.
TABLE FILE SALES . . . PRINT &FIELD BY PROD_CODE . . .
|
|
Information Builders |