PERFORM Statement
Executes a TCL command from DataBasic. Data (including lists) can be passed between the command and the program.
Syntax
PERFORM command
{ PASSLIST {inputListVar} }
{ RTNLIST {outputListVar} }
{ CAPTURING captureVar }
{[ SETTING || RETURNING ] settingVar }
{ PASSDATA passdataExpr }
{ RTNDATA rtndataVar }
Note
PERFORM clauses can be used in any order.
Syntax elements
command An expression that evaluates to a string containing a single TCL command to be executed (including any parameters and options). Any terminal input required can be provided by appending it to command (as a dynamic array) or by DATA statements that precede the PERFORM statement. For more details, see Responses to Prompts.
PASSLIST {inputListVar}
Passes a select list (in the form of a dynamic array) to the called program. If supplied, inputListVar must be the name of a variable containing the select list to be passed. The array must contain only attributes; any values or subvalues will not be processed correctly.
If inputListVar is omitted, the content of the default select variable is passed.
RTNLIST {outputListVar}
Used when the PERFORM statement causes a select list to be generated. The select list is returned in the variable outputListVar, if supplied. The resulting list can be used in a READNEXT statement or in the PASSLIST clause of a subsequent PERFORM.
If outputListVar is omitted, the generated select list replaces the contents of the default select variable.
CAPTURING captureVar
Specifies an alternative destination for text that would otherwise be displayed on the terminal. Each line of output becomes one attribute in captureVar. Output directed to the printer is unaffected.
If required, captureVar can be set to the keyword NULL, which causes PERFORM to discard terminal output. This saves the overhead of building the screen output as an internal string.
Note
The output of the CRT command is not captured.
SETTING settingVar
RETURNING settingVar
Specifies that error message numbers and their parameters are assigned to the variable
PASSDATA passdataExpr
Passes the data specified by passdataExpr to the called program, to be retrieved by a COLLECTDATA statement in that program. passdataExpr is any valid DataBasic expression.
RTNDATA rtndataVar
Assigns data returned by a RTNDATA statement in the called program to the variable
Requirements and restrictions
-
The executed command runs in its own context. Any active select list created by the command is local to that context and will not be available on return unless returned using the RTNLIST clause.
-
A file select list created with the SELECT statement cannot be used in the PASSLIST clause. However, any of the following lists may be used:
-
If PASSLIST is used without inputListVar, the content of the default select list is used.
Note
Any file-name passed to the called command must be the literal name of a file in the current account (or a file name identified via a Q-pointer), not a file variable which is the result of an OPEN statement.
-
The PASSLIST, RTNLIST, PASSDATA and RTNDATA clauses cannot be used when executing the SYS command.
-
You cannot use PERFORM to run the LOGTO command.
Operation
For a discussion of important related efficiency considerations, refer to Programming in DataBasic.
SETTING clause
When you use the SETTING (or RETURNING) clause each attribute in settingVar represents a particular message and its parameters, and can be examined, or printed using the PRINTERR statement. The error message text is sent to the terminal or printer (or to captureVar), whether or not the SETTING clause is used.
PASSDATA and RTNDATA clauses
You can use the PASSDATA and RTNDATA clauses independently or together. This means that you can pass data to a called program without having to return anything, or you can return data from a called program without having to pass anything.
Responses to prompts
If a command executed with PERFORM prompts the user for input, the are two ways in which you can provide responses to those prompts:
-
Precede your PERFORM statement with DATA statements containing the user responses. Multiple responses can be specified in separate DATA statements or as an ordered list, separated by commas. Individual responses must be less than 140 bytes long.
For example:
PERFORM 'SELECT CUST WITH ORDER-DATE < "4/11/90"' RTNLIST CUST.LIST DATA "(CUST-HIST" PERFORM 'COPY CUST' PASSLIST CUST.LIST
When using DATA statements, specify the user responses for only one PERFORM statement at a time. TCL attempts to process every currently available DATA string, so there will be none remaining when you return from a PERFORM statement.
-
Append the responses to command as a dynamic array.
For example:
PERFORM 'SELECT CUST WITH ORDER-DATE < "4/11/90"' RTNLIST CUST.LIST PERFORM 'COPY CUST':@AM:'(CUST-HIST' PASSLIST CUST.LIST
Note
It is recommended you use only one of these these methods. If you combine them, responses specified in DATA statements are processed before those appended to command.
You cannot provide responses to prompts generated by a Proc or by the SYS command.
Performing Procs
While the PERFORM statement can be used to execute a Proc, you cannot provide responses to prompts for user input. Stacked data appears to the Proc as data in the secondary output buffer, but is ignored by the Proc input commands.
When executing a Proc with the PERFORM statement, the Proc primary input buffer is initialized to contain the value of the PERFORM expression. Thus in the statement:
PERFORM "PROCNAME PARAM1 PARAM2"
the Proc primary input buffer would contain 3 parameters with 'PROCNAME' being the first parameter.
Pending list
A PERFORM statement without a RTNLIST clause creates a "pending" list when it executes a list-creating command (such as SELECT). The next PERFORM statement empties the pending list.
If the next PERFORM statement is without a PASSLIST clause, the pending list is passed to the command being called as if it were in a PASSLIST clause.
Nesting PERFORMS
The number of PERFORM statements that can be issued in a program is unlimited, but the number of PERFORM statements that can be nested is limited to thirty-one.
Examples
Example 1
STMT = 'SSELECT CUST WITH PAST-DUE BY LASTNAME'
PERFORM STMT RTNLIST LATECUST
LOOP WHILE READNEXT ID FROM LATECUST DO
.
.
REPEAT
Creates a list of customers with late payments that can then be used throughout the program.
Example 2
STMT = 'SORT CUST BY DUE-DATE NAME DUE-DATE PAST-DUE (P'
PERFORM STMT PASSLIST LATECUST
Passes the previously assigned list of customers with late payments to a command called with PERFORM.
Example 3
STMT = "SSELECT CUST WITH PAST-DUE BY LAST-NAME" ST = "SORT CUST BY DUE-DATE NAME DUE-DATE PAST-DUE (P" PERFORM STMT RTNLIST PERFORM ST PASSLIST
In this example, the list is saved in and passed from the default list.
Example 4
GETLIST "LISTNAME" TO INT.LIST.NAME PERFORM "LIST FILENAME" PASSLIST INT.LIST.NAME
The GETLIST command passes the list to the LIST command for processing.
Example 5
ST1="SORT CUST WITH " ST2="PAST-DUE " ST3="DUE-DATE " ST4="BY LAST-NAME" IF CHOICE = 1 THEN STMT=ST1:ST2:ST4 PERFORM STMT RTNLIST LATECUST END ELSE STMT=ST1:ST3:ST4 PERFORM STMT RTNLIST CUSTDUE END
This example shows how command can be built separately from the PERFORM statement. Selection criteria for an English statement can be tailored depending on variables within the DataBasic program.
The value of CHOICE could be determined by a menu selection. If the value is 1, the English statement is SORT CUST WITH PAST-DUE BY LAST-NAME and the resulting select list is returned in the variable LATECUST. If the value is not 1, the English statement is
SORT CUST WITH DUE-DATE BY LAST-NAME and the select list is returned in CUSTDUE.
Example 6
PROG1 001 THERE = 'HERE WE ARE' 002 PERFORM 'RUN BP PROG2' PASSDATA THERE RTNDATA HERE 003 PRINT HERE
PROG2 001 COLLECTDATA GETIT 002 PRINT GETIT 003 RTNDATA 'WE ARE BACK'
In this example, the program PROG1 is run. On line 002 it PERFORMs the program PROG2 and passes the variable THERE that has been assigned the string 'HERE WE ARE' in line 001. When PROG2 is executed, the COLLECTDATA statement in line 001 retrieves the data passed by the PASSDATA clause in the first program and stores it in the variable GETIT. Line 002 of PROG2 displays the value of GETIT, the string 'HERE WE ARE'. On line 003 the RTNDATA statement returns the string 'WE ARE BACK' to the variable HERE as specified in the RTNDATA clause in the first program. Line 003 of PROG1 then prints the contents of the variable HERE, the string 'WE ARE BACK'.
Example 7
PROG 001 PRINT 'ENTER INTERNAL DATA' : 002 INPUT INTERNAL 003 PERFORM 'GETDATE' PASSDATA INTERNAL RTNDATA EXTERNAL 004 PRINT 'THE DATA IS ':EXTERNAL
GETDATE 001 COLLECTDATA IDATE 002 RTNDATA IDATE 'D'
In this example, the program GETDATE is used to convert a date in internal format to external format. The program PROG prompts for the internal date on lines 001 and 002, then PERFORMs the GETDATE program passing the data entered. After the GETDATE program executes, it gets the data in line 001 and returns the converted value in line 002. The program PROG assigns the new value to EXTERNAL and displays it.
Note
Examples 6 and 7 are impractical because two programs are not needed to accomplish what we are doing here. These are merely provided as examples of how to use the PASSDATA and RTNDATA clauses in a PERFORM statement.
Example 8
PERFORM "SSELECT CUST WITH PAST-DUE BY LAST-NAME" PERFORM SORT CUST BY DUE-DATE NAME DUE-DATE PAST-DUE (P"
In this example, a pending list is created by the first statement and passed to the second.
Example 9
PERFORM 'DSM':@AM:'SP-LAB':@AM:'6':@AM:'Label printer':@AM:'FI':@AM
Performs DSM and creates a new despooler named SP-LAB, with the description 'Label printer'.