Supplying and Verifying Values for Variables

In this section:

Reference:

When you design a Dialogue Manager procedure with variables, you must decide how the variables in the procedure acquires values at run time. You can use and/or combine the following techniques.

You can supply variable values directly in procedures, without prompting users for input, using the following methods:

You can prompt users for variable values using the following methods:

Verifying user input: For values supplied by users, you can also verify input by comparing it against:

Reference: Rules for Supplying Variable Values

The following rules apply to values for variables:

  • 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 &LOCATION is BOS, MA, you must refer to the variable as '&LOCATION' in any expression.
  • Once a value is supplied for a local variable, it is used throughout the procedure, unless it is changed by -CRTFORM, -PROMPT, -READ, -SET, or -WINDOW.
  • Once a value is supplied for a global variable, it is used throughout the FOCUS session in all procedures, unless it is changed by -CRTFORM, -PROMPT, -READ, -SET, or -WINDOW, or cleared by LET CLEAR.
  • Dialogue Manager automatically prompts the terminal if a value has not been supplied for a variable.
  • The lengths of values stored in Dialogue Manager (amper) variables vary by context:
    • When used with the commands -READ, -TYPE, and WRITE, the maximum length of a variable is approximately 32,000 characters (32K).
    • When used with other Dialogue Manager commands or the EX command, a variable value cannot exceed 4,096 characters (4K).

Example: Supplying Variable Values in a Procedure

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 Dialogue Manager.

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 
5.     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 
4.     "REGION MANAGER: &REGIONMGR"
       "CALCULATED AS OF &DATE"
       END 
6. -RUN

The procedure executes as follows:

  1. The -DEFAULT command sets the value of &VERB to SUM.
  2. 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.
  3. When the user runs the report, FOCUS writes a message that incorporates the value for &CITY:
    REGIONAL MANAGER FOR STAMFORD
  4. The user supplied the value for &REGIONMGR in response to an implicit prompt. FOCUS supplies the current data at run time.
  5. The FOCUS 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 06/11/03"
END
  6. 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 06/11/03

Supplying a Default Variable Value

How to:

-DEFAULT commands set default values for local or global variables. This technique ensures that a value is passed to a variable so that the user is not prompted for the value.

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.

Note that -DEFAULTS and -DEFAULTH are synonyms for -DEFAULT.

Syntax: How to Supply a Default Value 

-DEFAULT[S|H] &[&]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 and -DEFAULTH are synonyms for -DEFAULT.

Example: Supplying a Default Value

In the following example, -DEFAULT sets the default value for &PLANT to Boston (BOS): 

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

Supplying Variable Values in an Expression

How to:

Reference:

You can assign a variable's value 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.

You can use this technique to supply dates to Dialogue Manager as variable values. A date supplied to Dialogue Manager in a variable 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).

If you are working with cross-century dates that do not include a four-digit year, you can use the SET parameters DEFCENT and YRTHRESH variables to identify the century. For details, see Working With Cross-Century Dates.

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 must 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.

&[&]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.
  • 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 calculate accurate numeric variable values without using the FTOA function.

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 subroutine 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.

  • 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: Setting Precision for Dialogue Manager Calculations

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 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: Setting a Literal Value

The use of single quotation marks around a literal is optional unless the literal contains embedded blanks, commas, or equal signs. In these cases, you must include them as illustrated below: 

-SET &NAME='JOHN DOE';

In prior releases, to assign a literal value that included a single quotation mark, you had to place two single quotation marks where you wanted one to appear: 

-SET &NAME='JOHN O''HARA';

Although this technique still works, it is no longer required. However, to start or end a string with a single quotation mark, you must specify two single quotation marks.

Example: Setting the Difference Between Two Dates

This example supplies dates to Dialogue Manager as variables. The variable &DELAY is set to the difference in days between &LATER and &NOW and the result is returned to your terminal. 

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

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

Example: Initializing a Variable to a Long String

To set the value of a variable with -SET, you need to specify a character string on the right side of the SET command. Since the character string cannot span multiple lines, if necessary, you can concatenate shorter strings or variables to compose the long string.

The following procedure creates a variable named &LONG that contains a long string: 

-SET &LONG = 'THIS IS A LONG AMPER VARIABLE. NOTE THAT IN ORDER '
- |'TO SET ITS VALUE USING -SET, YOU MUST CONCATENATE SHORTER STRINGS, '
- |'EACH OF WHICH MUST FIT ON ONE LINE.';
-TYPE &LONG
END

The output is:

THIS IS A LONG AMPER VARIABLE.NOTE THAT IN ORDER TO SET ITS VALUE USING 
-SET, YOU MUST CONCATENATE SHORTER STRINGS, EACH OF WHICH MUST FIT ON 
ONE LINE.

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

How to:

Reference:

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

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).

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 ddname[,] [NOCLOSE] &name[.format.][,] ...

where:

ddname

Is the logical name of the file as defined to FOCUS using ALLOCATE or DYNAM ALLOCATE.

A space after the ddname denotes a fixed format file while a comma denotes a comma-delimited file.

NOCLOSE

Indicates that the file should be kept open even if a -RUN is encountered. The file is closed upon completion of the procedure or when a -CLOSE or subsequent -WRITE command is encountered.

name

Is the variable name. You may specify more than one variable. Using commas to separate variables is optional.

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 comma-delimited files or a dash followed by a comma followed by a blank (-,) for fixed format files. For example:

Comma-delimited files 

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

Fixed format files

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

Is the format of the variable. It may be Alphanumeric (A) or Numeric (I). Note that format must be delimited by periods. The format is ignored for comma-delimited files.

Note: -SET provides an alternate method for defining the length of a variable using the corresponding number of characters enclosed in single quotation marks ('). For example, the following command defines the length of &CITY as 8: 

-SET &CITY='        ';

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 is not 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
 .
 .
 .

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

-WRITE ddname [NOCLOSE] text

where:

ddname

Is the logical name of the file as defined to FOCUS using ALLOCATE or DYNAM ALLOCATE. For information about file allocations, see the Overview and Operating Environments manual.

NOCLOSE

Indicates that the file should be kept open even if a -RUN is encountered. The file is closed upon completion of the procedure or when a -CLOSE or subsequent -READ command is encountered.

text

Is any combination of variables and text. To write more than one line, end the first line with a comma (,) and begin the next line with a hyphen followed by a space (-).

-WRITE opens the file to receiving the text and closes it upon exit from the procedure. When the file is reopened for writing, the new material overwrites the old. To reopen to add new records instead of overwriting existing ones, use the attribute DISP MOD when you define the file to the operating system.

Example: Writing to a File

The following example reopens the file PASS to add new text: 

DYNAM ALLOC DD PASS DA USER1.PASS.DATA MOD
-WRITE PASS &DIV &RED &TEST RESULT IS,
- &RECORDS AT END OF RUN

Example: Reading From and Writing to an External File

The following example illustrates reading from and writing to sequential files. It also illustrates the use of operating system commands. The numbers in the margin refer to notes that follow the example. 

    SET HOLDLIST=PRINTONLY
    -RUN 
1.  -TOP 
2.  -PROMPT &CITY.ENTER NAME OF CITY -- TYPE QUIT WHEN DONE. 
3.  DYNAM ALLOC DD PASS DA USER1.PASS.DATA LRECL 80 RECFM FB
    -RUN         
4.  -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
        IF CITY EQ &CITY
        FOOTING CENTER
        "CALCULATED AS OF &DATE"
        ON TABLE SAVE AS INFO
        END
5.  -RUN 
6.  DYNAM ALLOC DD LOG DA USER1.LOG.DATA LRECL 80 RECFM FB
        -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 
7.  -RUN
        EX SLRPT3 
8.  -RUN 
11. -GOTO TOP 
12. -QUIT

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

9.  -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
        IF CITY EQ &CITY
        FOOTING CENTER
        "CALCULATED AS OF &DATE"
        END 
10.  -RUN

The following annotations explain the logic and show the dialogue between the user and the screen. User entries are in lowercase:

  1. -TOP marks the beginning of the procedure.
  2. -PROMPT sends the following prompt to the screen after the procedure is executed:
    ENTER NAME OF CITY -- TYPE QUIT WHEN DONE<STAMFORD
  3. DYNAM defines and opens a file named PASS.
  4. -WRITE writes the value of &CITY to the sequential file named PASS. In this case the value written is STAMFORD.
  5. -RUN executes the stacked TABLE request. In this case, a sequential file named INFO is created with the SAVE command. This is a sequential file, containing the result of the report request as shown below.
    NUMBER OF RECORDS IN TABLE=        8  LINES=      8
    ALPHANUMERIC RECORD NAMED  INFO
FIELDNAME                         ALIAS         FORMAT        LENGTH
 
UNIT_SOLD                         SOLD          I5              5
STORE_CODE                        SNO           A3              3
CITY                              CTY           A15            15
DATE                              DTE           A4MD            4
PROD_CODE                         PCODE         A3              3
 
TOTAL                                                          30
SAVED...
  6. DYNAM defines a log file for the subsequent MODIFY request.
  7. -RUN executes the stacked MODIFY request. The data comes directly from the INFO file created in the prior TABLE request and is entered using FIXFORM. Hence, the product with the lowest UNIT_SOLD is deleted from the file, and logged to a log file. 
    SALES   FOCUS   A1 ON 09/04/2003 AT 10.04.35
    TRANSACTIONS:         TOTAL =     1  ACCEPTED=     1  REJECTED=     0
SEGMENTS:             INPUT =     0  UPDATED =     0  DELETED =     1
  8. The next -RUN executes another procedure called SLRPT3.
  9. -READ reads the value for &CITY from the sequential file PASS. In this case the value passed is STAMFORD.
  10. The -RUN executes the TABLE request and control is routed back to the calling procedure. 
                        MONTHLY REPORT FOR STAMFORD
                       LOWEST SALES DELETED
 
STORE_CODE  CITY             PROD_CODE  UNIT_SOLD  RETURNS  DAMAGED
----------  ----             ---------  ---------  -------  -------
14B         STAMFORD         B10               60       10        6
                             B12               40        3        3
                             B17               29        2        1
                             C7                45        5        4
                             D12               27        0        0
                             E2                80        9        4
                             E3                70        8        9
 
                        CALCULATED AS OF 09/04/03
  11. -GOTO TOP routes control to the top.
  12. When the user types QUIT, processing ends.

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

-READFILE mastername

where:

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

Syntax: How to Close an External File

The -CLOSE command closes an external file opened with the -READ or -WRITE command. The NOCLOSE option keeps a file open even when -RUN is encountered. 

-CLOSE {ddname|*}

where:

ddname

Is the ddname of the open file described to FOCUS via an allocation.

*

Closes all -READ and -WRITE files that are currently open.

Reading or Writing an Entire File

In this section:

Using the EDAGET and EDAPUT commands, you can read or write an entire file of a specified type.

EDAGET: Reading a File of a Specified Type

How to:

Using the EDAGET command, you can retrieve and display an entire file.

The -READ command only reads one line at a time, so this is a way to avoid issuing repeated commands for reading a single file.

Syntax: How to Read a File of a Specified Type 

EX EDAGET filetype,[app/]filename,content-type

where:

filetype

Is the type of file. On z/OS, this is a DDNAME. The following table lists some of the most common FOCUS file types. Other FOCUS-readable files use the standard extensions, and the file types match the extensions:

File Type

Extension

MASTER

.mas

ACCESS

.acx

FOCEXEC

.fex

FOCSQL

.acx

FOCSTYLE

.sty

DATA

.dat

FOCCOMP

.fcm

FOCTEMP

.ftm

FOCUS

.foc

HOLDMAST

.mas

HOLDACC

.acx

HTML

.htm

EXCEL

.xls

MAINTAIN

.mnt

FOCPSB

.psb

WINFORMS

.wfm

TTEDIT

.tte
app

Is an optional application name where the file resides. On z/OS, you can specify an app if you have enabled application logic in the EDASERVE configuration file and created the data sets associated with the application.

filename

Is the file name.

content-type

Is the type of data in the file. Valid values are:

  • T, which means a text file.
  • B, which means a binary file.

Note: EDAGET cannot retrieve a file that was written to memory by EDAPUT.

Example: Reading a File Using EDAGET

The following EDAGET command reads a Master File named tempmas.mas in the app1 application. The content type is text: 

EX EDAget MASTER,app1/tempmast,T

Using the tempmas.mas file created in BAD XREF HERE "EDAPUT: Writing a Sequential File of a Specified Type, the output is: 

FILENAME=TEMPMAST, SUFFIX=FIX,$ SEGNAME=ONE, SEGTYPE=S1 ,$ FIELD=FIELD1 ,ALIAS= ,A10 ,A10 ,$ FIELD=FIELD2 ,ALIAS= ,P18 ,A18 ,$

EDAPUT: Writing a File of a Specified Type

How to:

Using the EDAPUT command, you can write any number of lines and save them as common FOCUS file types, either in memory or on disk.

The -WRITE command only writes one line at a time, so this is a way to avoid issuing repeated commands for writing a single file.

Syntax: How to Write a File of a Specified Type 

EX -LINES n EDAPUT filetype,[app/]filename,type,location

where:

n

Is the number of lines that will be written, including the EDAPUT line.

filetype

Is the type of file. You specify the file type and, on Windows and UNIX, the file is saved with the associated extension. On z/OS, this is a DDNAME and the file is stored in the PDS associated with the DDNAME. The following table lists some of the most common FOCUS file types. Other FOCUS-readable files use the standard extensions, and the file types match the extensions:

File Type

Extension

MASTER

.mas

ACCESS

.acx

FOCEXEC

.fex

FOCSQL

.acx

FOCSTYLE

.sty

DATA

.dat

FOCCOMP

.fcm

FOCTEMP

.ftm

FOCUS

.foc

HOLDMAST

.mas

HOLDACC

.acx

HTML

.htm

EXCEL

.xls

MAINTAIN

.mnt

FOCPSB

.psb

WINFORMS

.wfm

TTEDIT

.tte
app

Is an optional application name under which to store the file. On z/OS, you can specify an app if you have enabled application logic in the EDASERVE configuration file and created the data sets associated with the application.

filename

Is the file name.

type

Is the creation type. Valid values are:

  • CV, create variable.
  • C, create fixed
  • A, append to file.
location

Is the location for the created file. Valid values are:

  • FILE, write to current location (this will overwrite an existing file of the same name and extension in the same location).
  • MEM, write to memory only (this will not overwrite an existing file on disk). Files written to memory are first in the path.
Example: Writing a Master File to Disk

The following EDAPUT command writes a Master File named tempmast.mas to the app1 application directory in variable format. On z/OS, it writes member TEMPMAST to the APP1.MASTER.DATA data set under the high-level qualifier assigned as approot in the EDASERVE configuration file: 

EX -LINES 5 EDAPUT MASTER,app1/tempmast,CV,FILE,
FILENAME=TEMPMAST, SUFFIX=FIX,$
SEGNAME=ONE, SEGTYPE=S1 ,$
  FIELD=FIELD1  ,ALIAS=  ,A10 ,A10 ,$ 
  FIELD=FIELD2  ,ALIAS=  ,P18 ,A18 ,$

Supplying Variable Values on the Command Line

How to:

Reference:

When a user knows the values required by a procedure, some or all of the values can be typed on the command line using the EXEC command following the name of the procedure. This saves time since FOCUS now has values to pass to each local or global variable so the user is not prompted to supply them.

Syntax: How to Supply a Variable Value on the Command Line 

EX[EC] procedure [[&&][variable=]value, ...]

where:

procedure

Is the name of the procedure that contains the name/value values.

variable

Is the name of the variable for which you are supplying a value. Omit for a positional variable.

For a local variable, do not include the ampersand in the variable name.

For a global amper variable, you must supply the double ampersand in the variable name: 

EX SLRPT &&GLOBAL=value, CITY = STAMFORD, CODE1=B10, CODE2=B20
value

Is the value you are giving to the variable.

Name/value pairs must be separated by commas.

When the list of values to be supplied exceeds the width of the terminal, insert a comma as the last character on the line and enter the balance of the list on the following line(s), as shown: 

EX SLRPT AREA=S, CITY = STAMFORD, VERB=COUNT, FIELDS = UNIT_SOLD, CODE1=B10, CODE2=B20

Reference: Rules for Using Named and Positional Variables With EXEC

You can mix named and positional variables freely in the EXEC command. Positional variables are unnamed values passed to a procedure when it is invoked.

Follow these rules:

  • Names must be associated with values for named variables.

    It is not necessary to enter the name=value pairs in the order encountered in the procedure.

  • Values for positional variables must be supplied in the order that those variables are numbered within the procedure.

    If the variable is positional (it is a numbered variable), you do not need to specify the variable name in the EXEC command. FOCUS matches the EXEC values to the positional variables as they are encountered in the procedure. For an example, see Using Positional Variables.

Example: Supplying Values on the Command Line

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 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 substitutes STAMFORD for the first positional variable, B10 for the second, and B20 for the third.

Example: Mixing Named and Positional Variables

The report request SLRPT includes named and positional variables: 

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

The following EX command executes SLRPT and populates the named and positional variables: 

EX SLRPT CITY=STAMFORD, B10, B20, VERB=COUNT

&CITY is a named variable whose value is STAMFORD.

&1 is a positional variable whose value is B10.

&2 is a positional variable whose value is B20.

&VERB is a named variable whose value is COUNT.

Prompting Directly for Values With -PROMPT

The Dialogue Manager command -PROMPT solicits values before the variables to which they refer are used in the procedure. The user is prompted for a value as soon as -PROMPT is encountered. If a looping condition is present, -PROMPT requests a new value for the variable, even if a value exists already. Thus, each time through the loop, the user is prompted for a new value.

With -PROMPT you can specify format, text, and lists in the same way as all other variables.

Example: Prompting for Variable Values

The following is an example of the use of -PROMPT: 

-PROMPT &CODE1
-PROMPT &CODE2
-SET &CITY = IF &CODE1 GT B09 THEN STAMFORD ELSE UNION;
-TYPE REGIONAL MANAGER FOR &CITY
-PROMPT &REGIONMGR
    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
    FOOTING CENTER
    "REGION MANAGER: &REGIONMGR"
    "CALCULATED AS OF &DATE"
    END

-PROMPT sends the following prompts to the screen. User input is shown in lowercase: 

PLEASE SUPPLY VALUES REQUESTED
 
CODE1=  > b10
CODE2=  > b20
REGIONAL MANAGER FOR STAMFORD
REGIONMGR=  > smith

Note how the sequence of supplied values determines the overall flow of the procedure. The value of &CODE1 determines the value of &CITY that gives meaning to the -TYPE command. -TYPE gives the user the necessary information to make the correct choice when supplying the value for &REGIONMGR.

By default, all user input is automatically converted to uppercase.

Prompting for Values on Screens With -CRTFORM

-CRTFORM sets up full-screen menus for entering values. The -CRTFORM command in Dialogue Manager and the CRTFORM command in MODIFY are two versions of FIDEL for use in different contexts. The syntax, functions and features are fully outlined in the Maintaining Databases manual.

Prompting for Values on Menus and Windows With -WINDOW

You can create a series of menus and windows using Window Painter, and then display those menus and windows on the screen using the -WINDOW command. When displayed, the menus and windows collect data by prompting a user to select a value, to enter a value, or to press a program function (PF) key For details, see Designing Windows With Window Painter.

Prompting for Values Implicitly

If a value for a variable is not supplied by any other means, FOCUS automatically prompts the user for the value. This is known as an implicit prompt. These prompts occur sequentially as each variable is encountered in the procedure.

Example: Automatically Prompting for Variable Values

Consider the following example: 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY"
.
.
.
BY PROD_CODE
IF PROD_CODE IS-FROM &CODE1 TO &CODE2
.
.
.
FOOTING CENTER
"REGION MANAGER: &REGIONMGR"
"CALCULATED AS OF &DATE"
END

When you execute the procedure, FOCUS prompts for the values for the variables one at a time. The terminal dialogue is as follows. User input is in lowercase: 

PLEASE SUPPLY VALUES REQUESTED
 
CODE1=  > b10
CODE2=  > b20
REGIONAL MANAGER FOR STAMFORD
REGIONMGR=  > smith

At the point when all variables have values, FOCUS processed the report request.

Verifying User-Supplied Values Against a Set of Format Specifications

Reference:

You can specify variables with format conditions against which entered values can be compared. If the entered values do not have the specified format, FOCUS prints error messages and prompts the user again for the value(s).

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 231-1), and the value supplied for the number can contain a decimal point.

The description of the format must be enclosed by 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, Dialogue Manager rejects the value and the user is prompted again.

Note: FOCUS internally stores all Dialogue Manager variables as alphanumeric codes. To perform arithmetic operations, Dialogue Manager converts the variable value to double-precision floating point decimal and then converts the result 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: 

&STORECODE.A3.

No special message is sent to the screen detailing the specified format. However, if in the above example the user enters more than three alphanumeric characters, the value is rejected, the error message FOC291 is displayed and the user is prompted again.

Note the following example detailing the dialogue between FOCUS and the user: 

PLEASE SUPPLY VALUES REQUESTED
 
STORECODE=  > cc14
(FOC291) THE VALUE IN THE PROMPT REPLY EXCEEDS THE MAXIMUM LENGTH: 03
CHARS:CC14
STORECODE=

Verifying User Input Against a Pre-Defined List of Values

How to:

You can define values that constitute acceptable responses to prompts. If the user does not enter one of the available options, the terminal displays the list and re-prompts the user. This is an excellent way to limit the values supplied and to provide help information to the screen while prompting.

In addition, you can supply text that either explains what type of value is needed or lists choices of acceptable values on the screen.

Example: Providing a List of Valid Values With -PROMPT

The following lists acceptable responses for &CITY: 

-PROMPT &CITY.(STAMFORD,UNIONDALE,NEWARK).

A message is printed if the user does not respond with one of the values on the list. This is followed by a display of the values list. Then, another prompt is issued for the needed value. For example: 

PLEASE SUPPLY VALUES REQUESTED
 
CITY=  > union
PLEASE CHOOSE ONE OF THE FOLLOWING:
 STAMFORD,UNIONDALE,NEWARK
CITY=  >

Syntax: How to Create a Reply List as a Variable

You can provide a reply list as a variable, then prompt for the values you have defined for that variable. The syntax is 

-SET &list='value,...';
-PROMPT &variable.(&list)[.text.]

where:

list

Is the name of the reply list variable. Note that in the -PROMPT command, the value is substituted between the parentheses and delimited by periods. If the prompt text has parentheses, enclose that text in single quotation marks (').

value

Is the desired value. You may list more than one value, separated by commas. Enclose the value(s) in single quotation marks ('). A semicolon is required when using -SET.

variable

Is the name of the variable for which you are prompting the user for values.

.text

Optionally provides prompting text.

Example: Using a Variable to Provide a Reply List

In this example, three acceptable values are defined for &CITY: 

-SET &CITIES='STAMFORD,UNIONDALE,NEWARK';
-PROMPT &CITY.(&CITIES).'(ENTER CITY)'.

The resulting screen is exactly the same as when the list itself is provided in the parentheses. See Providing a List of Valid Values With -PROMPT.

You can also create more complex combinations. For example: 

-SET &CITIES=IF &CODE1 IS B10 THEN 'STAMFORD, NEWARK'
- ELSE 'STAMFORD, UNIONDALE, NEWARK';

Example: Supplying Text for Variable Prompting

This example uses customized text to prompt for a values for &CITY, &CODE1, &CODE2, and &REGIONMGR: 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY.ENTER CITY. "
    .
    .
    .
BY PROD_CODE
IF PROD_CODE IS-FROM &CODE1.A3.BEGINNING CODE. TO
       &CODE2.A3.ENDING CODE.
    .
    .
    .
"REGION MANAGER: &REGIONMGR.REGIONAL SUPERVISOR."
"CALCULATED AS OF &DATEMDYY"
END

Notice that text has been specified for &CITY and &REGIONMGR without specification of a format.

Based on the example, the terminal displays the following prompts one by one: 

ENTER CITY
stamford
BEGINNING CODE
b10
ENDING CODE
b20
REGIONAL SUPERVISOR
smith
 Information Builders