This topic provides an alphabetical list of all Dialogue Manager commands, including a description of functions and syntax.
It also provides a grouped list of Dialogue Manager defaults and limits.
Note that this information is also presented throughout the chapter in the context of the task to which it applies.
The command -* 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 liberally 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.
The command -? displays the current value of a local variable.
The syntax is
-? &[variablename]
where:
Is a variable name of up to 12 characters. If this parameter is not specified, the current values of all local, global, and defined system and statistical variables are displayed.
-CLOSE closes an external file opened with the -READ or -WRITE NOCLOSE option. The NOCLOSE option keeps a file open until the -READ or -WRITE operation is complete.
The syntax is
-CLOSE {ddname|*}where:
Is the ddname of the open file described to FOCUS via an allocation.
Closes all -READ and -WRITE files that are currently open.
-CRTCLEAR clears the current screen display.
The syntax is
-CRTCLEAR
-CRTFORM creates forms that prompt the user for values for variables.
All lines following a -CRTFORM command that begin with a hyphen and enclose text in double quotation marks (") are part of a single-screen form. Pressing ENTER passes all input data to associated variables.
With -CRTFORM, the first line that does not begin with a -" signals the end of the form. With -CRTFORM BEGIN, the command -CRTFORM END signals the end of the form.
All FIDEL facilities are available to -CRTFORM except HEIGHT, WIDTH, and LINE.
CRTFORM in MODIFY functions identically to -CRTFORM in Dialogue Manager.
For additional information, see -PROMPT Command.
The syntax is
-CRTFORM [TYPE n] [BEGIN|END [LOWER|UPPER]]
where:
Invokes FIDEL and signals the beginning of the screen form.
Enables you to define the number of lines (n) to reserve for messages. You can specify a number from 1 to 4. The default is 4.
Supports the use of other Dialogue Manager commands to help build the form.
Signals the end of the -CRTFORM. Used with -CRTFORM BEGIN.
Reads lowercase data from the screen. Once you specify LOWER, every screen thereafter is a lowercase screen until you specify otherwise.
Translates lowercase letters to uppercase. This is the default.
DEFAULT commands set default values for local or global variables. ‑DEFAULT guarantees that the variables are always given a value and helps ensure that it executes 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, subsequent -DEFAULT commands issued for that variable are ignored.
You can override -DEFAULT values by supplying values for the variables on the command line, by specifically prompting for values with -PROMPT or -CRTFORM, or by supplying a value with -SET subsequent to -DEFAULT.
Default values are provided in other FOCUS modules to anticipate user needs and reduce the need for keystrokes in situations where most users desire a predefined outcome. For additional information, see also -SET Command.
The syntax is
-DEFAULT[S|H] &[&]name=value [...]
where:
Is the name of the variable.
Is the default value assigned to the variable.
-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:
The label in the -label command Is a user-defined name of up to 12 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.
Optionally sends a message to the client application.
-IF routes execution of a procedure based on the evaluation of the specified expression.
An -IF 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 12 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 need not be enclosed in single quotation marks unless they contain embedded blanks or commas.
Is an optional keyword 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 specifies another procedure to be incorporated and executed at run time, as if it were part of the calling procedure. The specified procedure may comprise either a fully developed or partial procedure. Note that a partial procedure does not execute if called outside of the procedure containing -INCLUDE.
When using -INCLUDE, you may not branch to a label outside of the specified procedure.
A procedure may contain more than one -INCLUDE. Any number of -INCLUDEs may be nested, but recursive -INCLUDEs are limited to four levels.
You may use any valid command in a -INCLUDE.
EXEC may also be used to execute a procedure inside another procedure.
The syntax is
-INCLUDE filename [filetype]
where:
Is the procedure to be incorporated in the calling procedure.
Is the procedure's DDNAME. If none is included, FOCEXEC is assumed.
The label specified in the -label command 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 12 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.
-MVS executes a z/OS command. -MVS is a synonym for -TSO. It is only supported with the RUN command.
This command is the same as -TSO RUN.
The syntax is
-MVS RUN
-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 DBA module.
The procedure that sets passwords should 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 PASS command provides the same function at the command level, as does the PASS parameter of the SET command.
The syntax is
-PASS password
where:
Is a literal FOCUS password or a variable containing a password.
Types a message to the terminal and reads the reply from the user. This reply assigns a value to the variable named.
If a format is specified and the supplied value does not conform, FOCUS displays an error message and prompts the user again for the value.
If a (list) is specified and the user does not reply with a value on the list, FOCUS reprompts and prints the list of acceptable values.
Note: You cannot use format and list together.
In MODIFY, PROMPT specifies additional data input needs.
In GRAPH, when it is set on, GPROMPT automatically prompts for all parameters needed to execute the graph request. This is quite a different function from -PROMPT in Dialogue Manager.
For additional information, see -CRTFORM Command.
The syntax is
-PROMPT &name [[.format|.(list)] [.text].]
where:
Is a user-defined variable.
Optionally specifies alphanumeric or integer data type and length.
Optionally specifies prompting text that appears on the screen. Must be delimited by periods.
Optionally specifies a range of acceptable responses. Must be enclosed in parentheses.
-QUIT forces an immediate exit from the procedure. Stacked lines are not executed. This differs from an -EXIT, which executes all lines that are currently on the stack.
Like -EXIT, -QUIT returns the user to the FOCUS prompt.
-QUIT FOCUS takes the user out of FOCUS altogether and returns the user to the operating system level.
-QUIT can be made the target of a branch, with the same results as those already described.
QUIT can be entered in response to -PROMPT or -CRTFORM to force an exit from the procedure. The QUIT command can, however, be turned off from within Dialogue Manager to prevent the user from exiting FOCUS prompt.
The QUIT command can also be used to exit from MODIFY and TABLE requests as well as Dialogue Manager procedures.
The principle of QUIT remains consistent throughout FOCUS, namely that the exited request or procedure is not executed and the user is returned to the FOCUS prompt.
For additional information, see also -RUN Command and -EXIT Command.
The syntax is
-QUIT or -QUIT FOCUS [n]
where:
Is the operating system return code. It can be a constant or an integer variable up to 4095. If you do not supply a value or if you supply a non-integer value for n, the return code is 8 (the default value).
Reads data from an external (non-FOCUS) file. -READ can access data in either fixed or free form.
For additional information, see -WRITE Command.
The syntax is
-READ ddname[,] [NOCLOSE] &name[.format.][,] ...
where:
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.
Indicates that the ddname should be kept open even after a -RUN is executed. The ddname is closed upon completion of the procedure or when a -CLOSE or subsequent -WRITE command is encountered.
Is the variable name. You may specify more than one variable. Using a comma 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
Is the format of the variable. It may be Alphanumeric (A) or Integer (I). Note that format must be delimited by periods. The format is ignored for comma-delimited files.
-READFILE reads a Master File, then reads values from a file into variables based on the fields listed in the Master File.
-READFILE mastername
where:
Is the name of the Master File to be read.
-REMOTE passes execution of the commands within a -REMOTE BEGIN and -REMOTE END command to a server.
For information, see the Overview and Operating Environments Manual.
The syntax is
-REMOTE BEGIN commands -REMOTE END
-REPEAT allows looping in a procedure.
A loop ends when any of the following occurs:
The syntax is
-REPEAT label n TIMES
-REPEAT label WHILE condition
-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 from 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 and incremented by s with each execution. It is compared with the value of fromval and toval, if supplied. The loop is executed only if &variable is greater than or equal to fromval or less than or equal to toval.
Is a constant that is compared with &variable at the start of the execution of the loop. The default value is 1.
Is a value that is compared with &variable at the start of the execution of the loop. The default value is 1,000,000.
Is a constant used to increment &variable at the end of the execution of the loop. It may be positive or negative. The default increment is 1.
Note: The parameters FROM, TO, and STEP can appear in any order.
-RUN causes immediate execution of all stacked FOCUS commands.
Following execution, processing of the 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 the variable.
Is a valid expression. Expressions can occupy several lines, so you should end the command with a semicolon.
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.
-TSO executes a TSO operating system command from within Dialogue Manager. It is only supported with the RUN command.
The syntax is
-TSO command
where:
Is a TSO RUN command.
In TSO, loads and executes the specified user-written function.
Note that the preferred way to execute user-written programs is with the -SET command.
The syntax is
-TSO RUN function
where:
Is the name of a user-written function.
Transmits informative messages to the user at the terminal. Any number of -TYPE lines may follow one another but each must begin with -TYPE.
Substitutable variables may be embedded in text. The values currently assigned to each variable is displayed in the assigned position in the text.
-TYPE1 and TYPE+ are not supported by IBM 3270-type terminals.
TYPE is used in a variety of ways in FOCUS to send informative messages to the screen. A TYPE command may appear on the same line as a label in Dialogue Manager. In MODIFY, TYPE is used to print messages at the start and end of processes, at selected positions in MATCH or NOMATCH, NEXT or NONEXT, and to send a message after an INVALID data condition.
The syntax is
-TYPE[+] text -TYPE[0] text -TYPE[1] text
where:
Sends the text after issuing a page eject.
Sends the text after skipping a line.
Sends the text but does not add a line feed.
Is a character string that fits on a line.
-WINDOW executes a window file. When the command is encountered, control is transferred from the procedure to the specified window file. The window specified in the command becomes the first active window. Control remains within the window file until a menu option is chosen, or a window is activated, for which there is no goto value.
The window file, and the windows in it, are created using Window Painter.
The syntax is
-WINDOW windowfile windowname [PFKEY|NOPFKEY] [GETHOLD][BLANK|NOBLANK][CLEAR|NOCLEAR]
where:
Identifies the file in which the windows are stored. This is a member name. The member must belong to a PDS allocated to ddname FMU.
Identifies which window in the file is displayed first.
Enables you to test for function key values during window execution.
You are unable to test for function key values during window execution.
Retrieves stored amper variables collected from a Multi-Select window.
Clears all previously set amper variable values when -WINDOW is encountered. This is the default setting.
When -WINDOW is encountered, the values of previously set amper variables are retained.
Clears the screen before displaying the first window. This is the default behavior. When specified in conjunction with the Terminal Operator Environment (TOE), the TOE screen is redisplayed when control is transferred back to the procedure.
Displays the specified window directly over the current screen.
-WRITE writes data to a sequential 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.
In TABLE, WRITE is a synonym for SUM; functionally it is quite different from ‑WRITE.
For additional information, see -READ Command.
The syntax is
-WRITE ddname [NOCLOSE] text
where:
Is the logical name of the file as defined to FOCUS using ALLOCATE or DYNAM ALLOCATE.
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.
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 (-).
The -" " syntax is associated with the FIDEL -CRTFORM command. All textual data enclosed by the double quotation marks is printed to the screen. You can use position markers and specify variable fields within double quotation marks.
When -CRTFORM is processed, the screen displays a form and the cursor stops at each amper variable date entry field. If a variable has not been declared prior to the -CRTFORM, FOCUS prompts the user for a value to assign to the variable.
In MODIFY, enclosing data in double quotation marks (" ") without the leading hyphen is used with CRTFORM, or for headings, footings, subheads, and subfoots within a TABLE request.
For additional information, see -CRTFORM Command.
The syntax is
-" "
where:
Enclose textual information, fields and spot markers.
This topic provides you with an easier way of locating default values, operating system and FOCUS limits, summary tables, general rules, and tips for ease-of-use.
General rules to follow when you are creating procedures are:
General rules for supplying values for variables:
EX SLRPT AREA=S, LOCATION='NY, NY'
Operating system default values, limits, and format specifications.
|
|
Information Builders |