Chain Command

Obsolete

This command is replaced by the Runprogram command.

Chain was used frequently in character-mode versions of DataFlex. The use of Chain is discouraged in favor of Runprogram in DataFlex.

Purpose

Calls one DataFlex program from another.

Syntax

Chain [Wait] {command-line} [Export_Files | Export_Only] [Seq_Export]

where {command-line} is an argument string that contains the name of the chained program and any parameters passed. If the name of the chained program or any of the parameters contain spaces, those arguments must be enclosed in quotation marks.

What It Does

Chain allows execution of an application to continue in another DataFlex program. Chain is typically used to link together separate DataFlex programs that belong to the same project. To call programs that are not DataFlex applications, use the Runprogram command.

The chained program receives the command line passed. The format of the command line is a list of delimited parameters whose first element is the name of the DataFlex program to execute. All parameters on the command line are separated by spaces, so if the parameters themselves have spaces, you will need to enclose these parameters in quotation marks, and the entire command line should be single-quoted.

Valid Windows file names may contain spaces, so the program that you are calling may need to be double-quoted. Here is an example that invokes a program named "New Prog" (note the space between the words), passing two parameters "parameter 1" and param2.

Chain Wait
'"New Prog" "parameter 1" param2'

Here is an example that shows how the parameters are extracted from the command line (using the Cmdline command):

String gsCommandLineParameter
Showln "In chained program."
Cmdline gsCommandLineParameter
Showln "Parameter 1: " gsCommandLineParameter
Cmdline gsCommandLineParameter
Showln "Parameter 2: " gsCommandLineParameter

Chain works in two different modes. Used by itself, Chain terminates execution of the current DataFlex program and immediately begins executing the new DataFlex program. Used with the Wait option, Chain executes the new program, leaving the calling program suspended. The user may interact with the chained program. When the chained program finishes, the calling program becomes active again. Execution will continue in the original program at the command line that follows the Chain Wait.

The Export_Files option keeps the files of the calling program open after the chain. This allows file buffers to be shared across chained programs. All files will remain open when execution returns to the original program, including files originally opened in the chained program. To use the Export_Files option, the file needs to be opened in both programs.

Regardless of whether the Export_Files option is used or not, all record buffers active at the time of the chain remain active, with record data in them, while the secondary program is executing. When the chained program finishes, file processing can continue in the calling program. If the chained program deletes the calling program's active record, errors can occur when the calling program regains control.

The Export_Only option works similarly to the Export_Files option. The one difference is that files first opened by the chained program are closed automatically when execution returns to the original program. Files opened in the chained program that were open in the caller are not closed.

If Seq_Export is used, all sequential files opened by the original program remain open (and can be appended) by the chained-to program. If Seq_Export is not used, a sequential file written by the chained program will overwrite a file of the same name created by the original program.

Notes

Chain passes all global integer variables to the chained program. Global integers are created in a common area within the chained program and accessed in the order they are declared. Therefore, the first global integer variable in the caller is the same as the first global integer variable in the chained program. The second global integer variable in the caller is the same as the second integer variable in the chained program, and so forth. However, if the Wait option is used, and execution returns to the old program, no values of global integer variables are passed back to the old program. The following example shows how the calling program can share an integer variable with the chained program.
```
Use windows.pkg
// COMMON INTEGER
Integer giParameterCount  // Global integers reside in common area.
// END OF COMMON AREA
Object oTest Is A Button
Procedure OnClick
    Move 2 To giParameterCount
    Chain Wait
    '"New Prog" "parameter 1" param2'
End_Procedure
End_Object  // oTest
Send OnClick Of oTest
Send Stop_Box "End of calling program reached!"
```

Here is a simple chained program that shows how the parameters are extracted from the command line (using the Cmdline command) using the shared integer.

Use windows.pkg
// COMMON INTEGER
Integer giNoParams  // This is giParameterCount in the calling program.
// END OF COMMON AREA
Object oTest Is A Button
Procedure OnClick
    Integer iCounter
    String sCommandLineParameter
    Showln "In chained program."
    For giCounter From 1 To giNoParams
        Cmdline sCommandLineParameter
        Showln "Parameter " giCounter ": " sCommandLineParameter
    Loop
End_Procedure
End_Object
Send OnClick Of oTest
Send Stop_Box "End of chained program reached!" "Exiting"

If the system cannot find the program to chain to, DataFlex Error 31 (Program file not found) will be declared and the program will terminate.
From a program executed by Chain Wait, you may chain wait to another program, and from that to another. The only limit on this process is the amount of memory in your computer to hold all the programs and their associated database files. If you use Export_Files with each Chain Wait, all database files opened by secondary (and tertiary, etc.) programs will remain open too. If a program chained with the wait option ends with a Runprogram command, execution will still return to the calling program, to resolve the wait.
If a chained program executed with Export_Files opens database files, those files will remain open even after execution has returned to the calling program. To cause such files to close when execution leaves the program that opened them, use Export_Only.
Global integer variables that are declared for common use should be explicitly documented. The opportunity for error is very high when using global variables for any purpose, especially when the variables are global between programs.