EXECUTE statement

Syntax

EXECUTE commands [CAPTURING variable] [PASSLIST 
[dynamic.array] ]
[RTNLIST [variable] ] [ {SETTING | RETURNING} 
variable]
EXECUTE commands [ ,IN < expression] [ ,OUT > variable]
[ ,SELECT[ (list) ] < dynamic.array] [ ,SELECT[ (list) ] > 
variable]
[ ,PASSLIST [ (dynamic.array) ] ] [ ,STATUS  > variable]
EXECUTE commands [ ,//IN. < expression] [ ,//OUT. > variable]
[ ,//SELECT.[ (list) ] < dynamic.array] [ ,//SELECT.[ 
(list) ] > variable]
[ ,//PASSLIST.[ (dynamic.array) ] ] [ ,//STATUS. > 
variable]

Description

Use the EXECUTE statement to execute InfoSphere® DataStage® commands from within the BASIC program and then return execution to the statement following the EXECUTE statement.

EXECUTE creates a new environment for the executed command. This new environment is initialized with the values of the current prompt, current printer state, Break key counter, the values of in-line prompts, KEYEDIT statements, KEYTRAP statements, and KEYEXIT statements. If any of these values change in the new environment, the changes are not passed back to the calling environment. In the new environment, stacked @Variables are either initialized to 0 or set to reflect the new environment. @variables that are not stacked are shared between the EXECUTE and calling environments.

commands can be sentences, paragraphs, verbs, procedures, menus, or BASIC programs. You can specify multiple commands in the EXECUTE statement in the same way they are specified in a UniVerse paragraph. Each command or line must be separated by a field mark (ASCII CHAR 254).

The EXECUTE statement has two main syntaxes. The first syntax requires options to be separated by spaces. The second and third syntaxes require options to be separated by commas. In the third syntax, the "//" preceding the keywords and the periods following them are optional; the compiler ignores these marks. Except for the slashes and periods, the second and third syntaxes are the same.

In the first syntax the CAPTURING clause assigns the output of the executed commands to variable. The PASSLIST clause passes the current active select list or expression to the commands for use as select list 0. The RTNLIST option assigns select list 0, created by the commands, to variable. If you do not specify variable, the RTNLIST clause is ignored. Using the SETTING or RETURNING clause causes the @SYSTEM.RETURN.CODE of the last executed command to be placed in variable.

In the second syntax the executed commands use the value of expression in the IN clause as input. When the IN clause is used, the DATA queue is passed back to the calling program, otherwise data is shared between environments. The OUT clause assigns the output of the commands to variable. The SELECT clauses let you supply the select list stored in expression as a select list to the commands, or to assign a select list created by the commands to variable. If list is not specified, select list 0 is used. The PASSLIST clause passes the currently active select list to the commands. If you do not specify list, select list 0 in the current program's environment is passed as select list 0 in the executed command's environment. The STATUS clause puts the @SYSTEM.RETURN.CODE of the last executed command in variable.

The EXECUTE statement fails and the program terminates with a run-time error message if:

dynamic.array or expression in the IN clause evaluates to the null value.
The command expression evaluates to the null value.

In transactions you can use only the following InfoSphere DataStage commands and SQL statements with EXECUTE:

CHECK.SUM INSERT SEARCH SSELECT COUNT LIST SELECT (RetrieVe) STAT DELETE (SQL) LIST.ITEM SELECT (SQL) SUM DISPLAY LIST.LABEL SORT UPDATE ESEARCH RUN SORT.ITEM

INFORMATION Flavor

In INFORMATION flavor accounts, the EXECUTE statement without any options is the same as the PERFORM statement. In this case executed commands keep the same environment as the BASIC program that called them. Use the EXEC.EQ.PERF option of the $OPTIONS statement to cause EXECUTE to behave like PERFORM in other flavors.

Example

The following example performs a nested SELECT, demonstrating the use of the CAPTURING, RTNLIST, and PASSLIST keywords:

CMD = "SELECT VOC WITH TYPE = V"
EXECUTE CMD RTNLIST VERBLIST1
CMD = "SELECT VOC WITH NAME LIKE ...LIST..."
EXECUTE CMD PASSLIST VERBLIST1 RTNLIST VERBLIST2
CMD = "LIST VOC NAME"
EXECUTE CMD CAPTURING RERUN PASSLIST VERBLIST2
PRINT RERUN

The program first selects all VOC entries that define verbs, passing the select list to the variable VERBLIST1. Next, it selects from VERBLIST1 all verbs whose names contain the string LIST and passes the new select list to VERBLIST2. The list in VERBLIST2 is passed to the LIST command, whose output is captured in the variable RERUN, which is then printed.