DPL 9 Help

Initiate Function (DPL Code)

Initiate Function (DPL Code)

The initiate function is used to open a communications channel to a DDE server application. Its syntax is

initiate(application,topic[,[command][,CommandLine[,WindowSize]]])

application - A named or literal string constant identifying the application to which a channel is to be opened.

topic - A named or literal string constant identifying the topic for the conversation.

command - A named or literal string constant to be sent to the application as a command in the event the initiate fails (see description).

CommandLine - A named or literal string constant to be used to start the application in the event the initiate and command strings fail (see description). The command line should include path information (if necessary), the name of the application, and any arguments to be passed to the application.

WindowSize - Describes the size of the window in which to start the application. A 0 indicates that the application should be started in a minimized window, a 1 indicates that the application should be started in a normal window, and a 2 indicates that the application should be started in a maximized window (see description). If this argument is omitted, the application will be started in a minimized window.

The initiate function returns a number identifying the channel Windows has assigned to this conversation. This number must be used with all subsequent request, request_multiple, execute, poke, or terminate commands that will use the channel. A maximum of 16 channels can be open at one time. This function may not be coded in the decision tree. (You must define a value node for it or code it in the definition section of a program.)

The initiate function is always executed when a program is compiled.

The function works as follows:

1. An initiate is attempted with the application and topic names. If the attempt is successful, the function returns the channel number; otherwise it proceeds to the next step.

2. If the command argument is not present, the function proceeds to the next step; otherwise an initiate is attempted with the application and System topic names. If the attempt is unsuccessful, the function proceeds to the next step. If the attempt is successful, the command argument is sent to the application for execution and the channel is terminated. If the command is executed successfully, the function proceeds to Step 5; otherwise it proceeds to the next step.

3. If the CommandLine argument is not present, the function returns with error; otherwise, the CommandLine and WindowSize arguments are used to start the application. If the WindowSize argument is not present, the application will be started in a minimized window. If the attempt is unsuccessful, the function terminates with error; otherwise it proceeds to the next step.

4. If the command argument is not present, the function proceeds to the next step; otherwise, an initiate is attempted with the application and System topic names. If the attempt is unsuccessful, it proceeds to the next step. If the attempt is successful, the command argument is sent to the application for execution and the channel is terminated. The function proceeds to the next step.

5. An initiate is attempted with the application and topic names. If the attempt is successful, the function returns the channel number; otherwise, the function returns with error.

Examples:

initiate("excel", "analysis.xls")

initiate("excel", "test.xls", "[OPEN(\"text.xls\")]",

excel,1)

If the file name includes path information, you must double the backward slash marks.

initiate("excel", "c:\\DPL\\analysis.xls")

Versions: DPL Professional, DPL Enterprise, DPL Portfolio

See Also