Executes a TCL command from DataBasic. Data (including lists) can be passed between the command and the program.
PERFORM command
{ PASSLIST
{inputListVar} }
{ RTNLIST
{outputListVar} }
{ CAPTURING capture-var }
{[ SETTING || RETURNING ]
setting-var }
{ PASSDATA passdata-expr }
{ RTNDATA rtndata-var }
Note: PERFORM clauses can be used in any order.
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 preceding DATA statements.
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 capture-var
Specifies an alternative destination for text that would otherwise be displayed on the
terminal. Each line of output becomes one attribute in capture-var. Output
directed to the printer is unaffected.
If required, capture-var 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 setting-var
RETURNING setting-var
Specifies that error message numbers and their parameters are assigned to the variable
PASSDATA passdata-expr
Passes the data specified by passdata-expr to the called program, to be retrieved by a
COLLECTDATA statement in that program.
passdata-expr is any valid DataBasic expression.
RTNDATA rtndata-var
Assigns data returned by a
RTNDATA statement in the called program
to the variable
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 active 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.
For a discussion of important related efficiency considerations, refer to Programming in DataBasic.
When you use the SETTING (or RETURNING) clause each attribute in setting-var 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 capture-var), whether or not the SETTING clause is used.
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.
The DATA statement is used to stack arguments that are to be passed to a command executed with PERFORM. The arguments are specified as an ordered list, separated by commas. Individual arguments 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
Do not stack data to be used in a PERFORM statement and then stack further data to be used before the PERFORM is executed. TCL processes (or attempts to process) every data string in the data stack. The stack is empty when you return to the DataBasic program from a PERFORM statement.
The DATA statement cannot be used to pass data to a Proc or to the SYS command.
While the PERFORM statement can be used to execute a Proc, the DATA statement cannot be used to pass data to the Proc. Although stacked data appears to the Proc as data in the secondary output buffer, Proc input commands ignore stacked data.
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.
The LOGTO command cannot be used within a PERFORM statement.
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.
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.
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.
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.
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.
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.
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.
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'.
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.
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.