OpenChannel

Description

Opens a channel to a DDE server application.

Syntax

OpenChannel ( applname, topicname {, windowhandle } )

Argument

Description

applname

A string specifying the DDE name of the DDE server application.

topicname

A string identifying the data or the instance of the application you want to use (for example, in Microsoft Excel, the topic name could be System or the name of an open spreadsheet).

windowhandle (optional)

The handle of the window that you want to act as the DDE client. Specify this parameter to control which window is acting as the DDE client when you have more than one open window.


Return value

Long.

Returns the handle to the channel (a positive integer) if it succeeds. If an error occurs, OpenChannel returns a negative integer. Values are:

-1 -- Open failed

-9 -- Handle is null

Usage

Use OpenChannel to open a channel to a DDE server application and leave it open so you can efficiently execute more than one DDE request. This type of DDE conversation is called a warm link. Because you open a channel, the operating system does not have to poll all open applications every time you send or ask for data.

The following is an outline of a warm-link conversation:

  • Open a DDE channel with OpenChannel and check that it returns a valid channel handle (a positive value).

  • Execute several DDE functions. You can use the following functions:

    ExecRemote ( command, handle, <windowhandle> )

    GetRemote ( location, target, handle, <windowhandle> )

    SetRemote ( location, value, handle, <windowhandle> )

  • Close the DDE channel with CloseChannel.

If you only need to use a remote DDE function once, you can call ExecRemote, GetRemote, or SetRemote without opening a channel. This is called a cold link. Without an open channel, the operating system polls all running applications to find the specified server application each time you call a DDE function.

Your PowerBuilder application can also be a DDE server.

For more information, see StartServerDDE.

About server applications

Each application decides how it supports DDE. You must check each potential server application's documentation to find out its DDE name, what its valid topics are, and how it expects locations to be specified.

Examples

These statements open a channel to the active spreadsheet REGION.XLS in Microsoft Excel and set handle to the handle to the channel:

long handle
handle = OpenChannel("Excel", "REGION.XLS")

The following example opens a DDE channel to Excel and requests data from three spreadsheet cells. In the PowerBuilder application, the data is stored in the string array s_regiondata. The client window for the DDE conversation is w_ddewin:

long handle
string s_regiondata[3]
handle = OpenChannel("Excel", "REGION.XLS", &
      Handle(w_ddewin))
GetRemote("R1C2", s_regiondata[1], handle, &
      Handle(w_ddewin))
GetRemote("R1C3", s_regiondata[2], handle, &
      Handle(w_ddewin))
GetRemote("R1C4", s_regiondata[3], handle, &
      Handle(w_ddewin))
CloseChannel(handle, Handle(w_ddewin))

See also

CloseChannel

ExecRemote

GetRemote

SetRemote