Dialogue Manager Commands

Command:

-*

Syntax:

-* text

where:

text

Is a comment. A space is not required between -* and text.

Function:

The command -* signals the beginning of a comment line.

Any number of comment lines follows 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 stored procedure so that its purpose and history are clear to others.

Command:

-?

Syntax:

-? &[string]

where:

string

Is an optional 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.

Function:

The command -? displays the current value of a local variable.

Command:

-CLOSE

Syntax:

-CLOSE filename

where:

filename

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

Function:

-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 external file must be defined to the operating system.

Command:

-AS/400

Syntax:

-AS/400 command

where:

command

Is an IBM i command (formerly known as i5/OS).

Function:

-AS/400 executes an IBM i operating system command from a procedure.

Ignored on all other operating systems.

Command:

-CMS

Syntax:

-CMS command

where:

command

Is a CMS command.

Function:

-CMS executes a CMS operating system command from a procedure.

Ignored on all other operating systems.

Note: The VM/CMS operating system is not supported as of the 7.7.x release level. It is documented here for deprecated command purposes for 7.7.x (and higher) releases.

Command:

-DEFAULTS

Syntax:

-DEFAULTS &[&]name=value [...]

where:

&name

Is a name of a variable.

value

Is the default value assigned to the variable.

Function:

-DEFAULTS supplies an initial (default) value for a variable that had no value before the command was processed.

Override values set with -DEFAULTS by supplying new values:

  • On the function call EDARPC.
  • On the command line EXEC.
  • With the command -SET subsequent to the command -DEFAULTS.

By supplying values to variables in a stored procedure, -DEFAULTS helps ensure that it runs correctly.

Command:

-DOS

Syntax:

-DOS command

where:

command

Is a Windows or DOS command.

Function:

-DOS executes a Windows or DOS operating system command from a procedure.

Ignored on all other operating systems.

Command:

-EXIT

Syntax:

-EXIT

Function:

-EXIT forces a stored procedure to end. All stacked commands are executed and the stored procedure exits (if the stored procedure was called by another one, the calling procedure continues processing).

Use -EXIT for terminating a stored procedure after processing a final branch that completes the desired task.

The last line of a stored procedure is an implicit -EXIT. In other words, the procedure ends after the last line is read.

Command:

-GOTO

Syntax:

-GOTO label 
     .
     .
     .
-label [TYPE text]

where:

label

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 may be confused with functions, arithmetic and logical operations, and so on.

TYPE text

Optionally sends a message to the client application.

Function:

-GOTO forces an unconditional branch to the 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 a message is displayed.

Command:

-IF

Syntax:

-IF expression [THEN] GOTO label1[;]
-[ELSE GOTO label2 [;]]
-[ELSE IF...[;]]

where:

label

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 may be confused with functions, arithmetic or logical operations, and so on.

expression

Is a valid expression. Literals need not be enclosed in single quotation marks unless they contain embedded blanks or commas.

THEN

Is an optional keyword that increases readability of the command.

ELSE GOTO

Optionally passes control to label2 when the -IF test fails.

ELSE IF

Optionally specifies a compound -IF test.

;

Is required at the end of the command.

-

Must begin continuation lines.

Function:

-IF routes execution of a stored procedure based on the evaluation of the specified expression.

A -IF without an explicitly specified ELSE whose expression is false continues processing with the line immediately following it.

Command:

-INCLUDE

Syntax:

-INCLUDE filename

where:

filename

Is the name of the called stored procedure.

Function:

-INCLUDE enables one stored procedure to call another one.

A stored procedure calls any number of other procedures. Up to four -INCLUDE commands are nested.

The called procedure contains fully executable or partial code.

The calling procedure cannot branch to a label in the called procedure and vice versa.

Command:

-label

Syntax:

-label [TYPE message]

where:

label

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 may be confused with functions, arithmetic or logical operations, and so on.

TYPE message

Optionally sends a message to the client application.

Function:

A label is the target of a -GOTO or -IF command.

Command:

-PASS

Syntax:

-PASS password

where:

password

Is a literal FOCUS password or a variable containing a password.

Function:

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

Procedures that set 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 using -PROMPT.

The PASS command provides the same function at the command level, as does the PASS parameter of the SET command.

Command:

-PROMPT

Syntax:

-PROMPT &name [[.format|.(list)] [.text].]

where:

&name

Is a user-defined variable.

format

Optionally specifies alphanumeric or integer data type and length.

list

Optionally specifies a range of acceptable responses. Must be a comma separated list enclosed in parentheses.

text

Optionally specifies prompting text that appears on the screen. Must be delimited by periods.

Function:

Types a message to the terminal (if edastart -t is in use) or creates an input window with the message in a browser if the connection type is HTTP and reads the reply from the user. This reply assigns a value to the variable named.

In edastart -t mode, if a format is specified and the supplied value does not conform, FOCUS displays a message and prompts the user again for the value. In HTTP mode, only a message is displayed.

In edastart -t mode, 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. For HTTP type connections, the list is interpreted as a pull-down list, so only a valid value may be selected.

Note: You cannot use format and list together.

Command:

-QUIT

Syntax:

-QUIT

Function:

-QUIT forces an immediate exit from a stored procedure. Stacked commands are not executed. In this respect, -QUIT is different from -EXIT, which executes stacked commands.

If the procedure was called by another one, control returns directly to the client application, not to the calling procedure.

-QUIT is the target of a branch.

Command:

-READ

Syntax:

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

where:

filename[,]

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.

NOCLOSE

Optionally keeps the external file open until the -READ operation is complete. Files kept open with NOCLOSE are closed by using the command -CLOSE file name.

&name[,]...

Is a list of variables. For free-format files, you may separate the variable names with commas, but it is not necessary.

.format.

Is the format of the variable. For free-format files, you do not have to define the length of the variable, but you may. For fixed-format files, the format specifies the length or the length and type of the variable (A is the default type). The value of format must be delimited by periods.

Function:

-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 the -READ command is encountered. Use a -DEFAULTS command 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.

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

Command:

-REMOTE

Syntax:

-REMOTE [BEGIN|END]

where:

BEGIN

Specifies the start of commands on an originating server to be sent to a target server.

END

Specifies the end of commands from the originating server.

Function:

-REMOTE commands are the initial form of stored procedure routing, and are available with Hub Services only.

Dialogue Manager commands within the delimiters are executed, and variable substitution takes place before the stack is sent to the target server. A -INCLUDE command takes a Dialogue Manager procedure residing on the originating server and includes the procedure commands in the stack.

The commands within the delimiters must make up a complete server request. Any command valid on the target server is included.

The command EXEC may be included within the delimiters to execute a stored procedure on the target server.

-REMOTE commands cannot be nested.

Command:

-REPEAT

Syntax:

-REPEAT labeln TIMES

or

-REPEAT label WHILE condition

or

-REPEAT label FOR &variable [FROM fromval] [TO toval] 
[STEP s]

where:

label

Identifies the code to be repeated (the loop). A label includes another loop if the label for the second loop has a different name from the first.

n TIMES

Specifies the number of times to execute the loop. The value of n is a local variable, a global variable, or a constant. If it is a variable, it is evaluated only once, so the only way to end the loop early is with -QUIT or -EXIT (you cannot change the number of times to execute the loop).

WHILE condition

Specifies the condition under which to execute the loop. The condition is any logical expression that is either true or false. The loop is run if the condition is true.

FOR &variable

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 (STEP is positive), or greater than or equal to toval (STEP is negative).

Syntax:

(continued)

FROM fromval

Is a constant that is compared with &variable at the start of each execution of the loop. 1 is the default value.

TO toval

Is a value against which &variable is tested. 1,000,000 is the default value.

STEP s

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.

Function:

-REPEAT allows looping in a stored procedure.

The parameters FROM, TO, and STEP appear in any order.

A loop ends when:

  • It is executed in its entirety.
  • A -QUIT or -EXIT is issued.
  • A -GOTO is issued to a label outside of the loop. If a -GOTO is later issued to return to the loop, the loop proceeds from the point it left off.

Command:

-RUN

Syntax:

-RUN

Function:

-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:

  • Generate results from an SQL request that are then used in testing and branching.
  • Close an external file opened with -READ or -WRITE. When a file is closed, the line pointer is placed at the beginning of the file for a -READ. The line pointer for a -WRITE is positioned depending on the allocation and definition of the file.

Command:

-SET

Syntax:

-SET &[&]name=expression;

where:

&name

Is the name of a variable whose value is to be set.

expression

Is a valid expression. Expressions occupy several lines, so end the command with a semicolon.

Function:

-SET assigns a literal value to a variable, or a value that is computed in an arithmetic or logical expression.

Single quotation marks around a literal value are optional unless it contains embedded blanks or commas, in which case the quotation marks must be included.

Command:

-TSO RUN

Syntax:

-TSO RUN command

where:

command

Is a TSO command.

Function:

-TSO executes a TSO operating system command from a procedure.

Ignored on all other operating systems.

Command:

-TYPE

Syntax:

-TYPE text

where:

text

Is a message that is sent to a client application, followed by a line feed. Quotation marks will be displayed as part of the message if included around text.

The length of text can be up to 256 bytes.

Function:

-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 are displayed.

Command:

-UNIX

Syntax:

-UNIX command

where:

command

Is a UNIX command.

Function:

-UNIX executes a UNIX operating system command from a procedure.

Ignored on all other operating systems.

Command:

-VMS

Syntax:

-VMS command

where:

command

Is a VMS command.

Function:

-VMS executes a VMS operating system command from a procedure.

Ignored on all other operating systems.

Command:

-WINNT

Syntax:

-WINNT command

where:

command

Is a Windows or DOS command.

Function:

-WINNT executes a Windows or DOS operating system command from a procedure.

Ignored on all other operating systems.

Command:

-WRITE

Syntax:

-WRITE filename [NOCLOSE] text

where:

filename

Is a symbolic name for a physical external file being written to. The file name must be known to the operating system.

NOCLOSE

Keeps the external file open until the -WRITE operation is complete. Files kept open with NOCLOSE are closed with the command -CLOSE filename.

text

Is any combination of variables and text.

Function:

-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 succeeding line.

Unless you specify the NOCLOSE option, an opened file is closed upon termination of the procedure with -RUN, -EXIT, or -QUIT.


iWay Software