|
In this section: |
This topic describes all the Dialogue Manager commands.
-* signals the beginning of a comment line.
Any number of comment lines can follow one another, but each must begin with -*. A comment line may be placed at the beginning or end of a procedure, or in between commands. However, it cannot be on the same line as a command.
Use comment lines to document a procedure so that its purpose and history are clear to others.
The syntax is:
-* text
where:
Is a comment. A space is not required between -* and text.
-? displays the current value of a local variable.
The syntax is:
-? &[string]
where:
Is a variable name. If this parameter is not specified, the current values of all local, global, and defined system and statistical variables are displayed, except for those whose values have been hidden using the -DEFAULTH command.
-CLOSE closes an external file opened with the -READ or -WRITE command using the NOCLOSE option. The NOCLOSE option keeps a file open until the -READ or -WRITE operation is complete.
The syntax is:
-CLOSE filename
where:
Is a symbolic name associated with a physical file known to the operating system.
-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.
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.
The syntax is:
-DEFAULT &[&]name=value [...]
where:
Is a name of a variable.
Is the default value assigned to the variable.
-DEFAULTH commands set default values for hidden variables.
You can initialize a variable and prevent it from being used for WebFOCUS parameter prompting by using the -DEFAULTH command. 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 and are not displayed by the -? command, they are hidden from the user.
The syntax is:
-DEFAULTH &[&]name=value [...]
where:
Is a name of a variable. This variable is not used for parameter prompting and is hidden from the user.
Is the default value assigned to the variable.
-DOS executes a DOS operating system command from a procedure.
The syntax is:
-DOS command
where:
Is a DOS command.
-EXIT forces a procedure to end. All stacked commands are executed and the procedure exits. If the procedure was called by another one, the calling procedure continues processing.
Use -EXIT for terminating a procedure after processing a final branch that completes the desired task. The last line of a procedure is an implicit -EXIT.
The syntax is:
-EXIT
-GOTO transfers control to a specified label.
If Dialogue Manager finds the label, processing continues with the line following it. If Dialogue Manager does not find the label, processing ends and an error message is displayed.
The syntax is:
-GOTO label
.
.
-label [TYPE text]where:
Is a user-defined name of up to 64 characters that specifies the target of the -GOTO action.
Do not use embedded blanks or the name of any other Dialogue Manager command except -QUIT or -EXIT. Do not use words that can be confused with functions, arithmetic and logical operations, and so on.
Sends a message to the client application.
-HTMLFORM sends report output to the HTML file you create for a webpage and displays that page in the browser. The output can also be saved as an HTML file that can be displayed later.
The syntax is:
-HTMLFORM filename [SAVE AS htmlpage]
or
-HTMLFORM BEGIN . . . -HTMLFORM END
where:
Is the HTML file that contains placeholders for the report or reports WebFOCUS creates with the command:
ON TABLE HOLD HTMTABLE AS report
Indicates that the HTML page, created when the HTML file filename and the report or reports generated by WebFOCUS are combined, is to be saved.
Is the file name for the HTML page that is created when the HTML file filename and the report or reports generated by WebFOCUS are combined. This file is saved so that it can be displayed later.
Indicates the beginning of an inline HTML form in a procedure.
Indicates the end of an inline HTML form in a procedure.
-IF routes execution of a procedure based on the evaluation of the specified expression.
An -IF command without an explicitly specified ELSE whose expression is false continues processing with the line immediately following it.
The syntax is:
-IF expression [THEN] GOTO label1; [ELSE GOTO label2;]
[ELSE IF...;]where:
Is a user-defined name of up to 64 characters that specifies the target of the GOTO action.
Do not use embedded blanks or the name of any other Dialogue Manager command except -QUIT or -EXIT. Do not use words that can be confused with functions, arithmetic or logical operations, and so on.
Is a valid expression. Literals do not need to be enclosed in single quotation marks unless they contain embedded blanks or commas.
Is optional code that increases readability of the command.
Passes control to label2 when the -IF test fails.
Specifies a compound -IF test.
The semicolon is required at the end of the command, and continuation lines must begin with a hyphen.
-INCLUDE enables one procedure to call another one. A procedure can call any number of other procedures. Up to four -INCLUDE commands can be nested.
The called procedure can contain fully executable or partial code. The calling procedure cannot branch to a label in the called procedure and vice versa.
Note: When calling the WebFOCUS CGI, the CGI uses an -INCLUDE command. Therefore, the end user can include only three nested -INCLUDE commands. When using edastart, this does not occur.
The syntax is:
-INCLUDE filename
where:
Is the name of the called procedure.
For information on syntax for using fully qualified file names, see Using Fully Qualified Names With the -Include Command.
-label is the target of a -GOTO command or -IF criteria.
The syntax is:
-label [TYPE message]
where:
Is a user-supplied name of up to 64 characters that identifies the target for a branch.
Do not use embedded blanks or the name of any other Dialogue Manager command except -QUIT or -EXIT. Do not use words that can be confused with functions, arithmetic or logical operations, and so on.
Sends a message to the client application.
In WebFOCUS, executes an MVS operating system command from a procedure.
The syntax is:
-MVS command
where:
Is an MVS command.
-PASS directly issues and controls passwords. This feature is especially useful for specifying a particular file or set of files that a given user can read or write. Passwords have detailed sets of functions associated with them through the DBA facility.
The procedure that sets passwords can be encrypted so that it and the passwords that it sets cannot be typed and made known.
A variable can be associated with -PASS so that you can prompt for and assign a password value.
The syntax is:
-PASS password
where:
Is a literal FOCUS password or a variable containing a password.
-QUIT forces an immediate exit from a procedure. Stacked commands are not executed.
If the procedure was called by another one, control returns directly to the client application, not to the calling procedure.
-QUIT can also be the target of a branch.
The syntax is:
-QUIT
-QUIT FOCUS terminates the procedure and exits FOCUS. The user returns to the operating system, or the calling program.
Upon exiting FOCUS, the value is returned to the calling program, if one exists. This is useful when FOCUS is called from another Windows application to return a status code indicating the state at which FOCUS was exited.
-QUIT FOCUS can also be made the target of a branch, with the same results as those already described.
The syntax is:
-QUIT FOCUS [n]
where:
Is the application return code value. It can be a constant or an integer variable.
If you do not supply a value, or if you supply a non-integer value for n, the return code is 0 (the default value).
-READ enables the reading of data from an external file that is defined to the operating system.
The length of the variable list must be known before -READ is encountered. Use -DEFAULT to establish the number of characters expected for each variable.
If the list of variables is longer than one line, end the first line with a comma and begin the next line with a hyphen if you are reading a free-format file:
-READ EXTFILE, &CITY, &CODE1, - &CODE2
If you are reading a fixed-format file, begin the next line with a hyphen and comma as follows:
-READ EXTFILE &CITY.A8. &CODE1.A3., -, &CODE2.A3.
The syntax is:
-READ filename[,] [NOCLOSE] &name[.format.][,]...
where:
Is the name of an external file to read, which must be defined to the operating system. A space after filename denotes a fixed-format file, while a comma after filename denotes a free-format file.
Keeps the external file open until the -READ operation is complete. Files kept open with NOCLOSE can be closed using the command -CLOSE filename.
Is a list of variables. For free-format files, you may but are not required to separate the variable names with commas.
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.
-READFILE reads Master File fields into Dialogue Manager variables.
The syntax is:
-READFILE [app/]mastername
where:
Is the application directory in which the file resides.
Is the name of the Master File to be read.
-REPEAT allows looping in a stored procedure. A loop ends when any of the following occurs:
The syntax is:
-REPEAT label n TIMES
or
-REPEAT label WHILE condition;
or
-REPEAT label FOR &variable [FROM fromval] [TO toval] [STEP s]
where:
Identifies the code to be repeated (the loop). A label can include another loop if the label for the second loop has a different name than the first.
Specifies the number of times to execute the loop. The value of n can be a local variable, a global variable, or a constant. If it is a variable, it is evaluated only once, so you cannot change the number of times to execute the loop. The loop can only be ended early using -QUIT or -EXIT.
Specifies the condition under which to execute the loop. The condition is any logical expression that can be true or false. The loop is run if the condition is true.
Is a variable that is tested at the start of each execution of the loop. It is compared with the value of fromval and toval (if supplied). The loop is executed only if &variable is less than or equal to toval when STEP is positive, or greater than or equal to toval when STEP is negative. If toval is not used, another option must be substituted, such as n TIMES.
Is a constant that is compared with &variable at the start of each execution of the loop. 1 is the default value.
Is a value that is compared with &variable at the start of each execution of the loop. The default value is 1,000,000.
Is a constant used to increment &variable at the end of each execution of the loop. It may be positive or negative. 1 is the default value.
Note: The parameters FROM, TO, and STEP can appear in any order.
-RUN causes immediate execution of all stacked commands.
Following execution, processing of the stored procedure continues with the line that follows -RUN.
-RUN is commonly used to do the following:
The syntax is:
-RUN
-SET assigns a literal value, or a value that is computed in an arithmetic or logical expression, to a variable.
Single quotation marks around a literal value are optional unless it contains an embedded blank, comma, or equal sign, in which case you must include them.
The syntax is:
-SET &[&]name= {expression|value};where:
Is the name of a variable whose value will be set.
Is a valid expression. Expressions can occupy several lines, so end the command with a semicolon (;).
Is a literal value 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.
In WebFOCUS, -TSO executes a TSO operating system command from a procedure. This is only supported when the command is RUN.
The syntax is:
-TSO command
where:
Is a TSO RUN command.
-TYPE sends a message to a client application.
Any number of -TYPE commands can follow one another, but each must begin with -TYPE.
Variables may be embedded in the message. The values currently assigned to each variable will be displayed.
The syntax is:
-TYPE text
where:
Is a message that will be sent to a client application, followed by a line feed. If you include quotation marks around text, they will be displayed as part of the message.
The length of text can be up to 256 bytes.
In WebFOCUS, -UNIX executes a UNIX operating system command from a procedure.
The syntax is:
-UNIX command
where:
Is a UNIX command.
In WebFOCUS, -VMS executes a VMS operating system command from a procedure.
The syntax is:
-VMS command
where:
Is a VMS command.
-WINNT executes a Windows operating system command from a procedure.
The syntax is:
-WINNT command
where:
Is a Windows command.
-WRITE writes data to an external file.
If the command continues over several lines, put a comma at the end of the line and a hyphen at the beginning of each subsequent line.
Unless you specify the NOCLOSE option, an opened file is closed upon termination of the procedure with -RUN, -EXIT, or -QUIT.
The syntax is:
-WRITE filename [NOCLOSE] text
where:
Is the name of a physical external file being written to. The filename must be known to the operating system.
Keeps the external file open until the -WRITE operation is complete. Files kept open with NOCLOSE can be closed with the command -CLOSE filename.
Is any combination of variables and text.