GetRemote

Asks a DDE server application to provide data and stores that data in the specified variable. There are two ways of calling GetRemote, depending on the type of DDE connection you have established.

To

Use

Make a single request of a DDE server application (called a cold link)

Syntax 1

Request data from a DDE server application after you have opened a channel (called a warm link)

Syntax 2


Syntax 1: For single DDE requests

Description

Asks a DDE server application to provide data and stores that data in the specified variable without requiring an open channel. This syntax is appropriate when you will make only one or two requests of the server.

Syntax

GetRemote ( location, target, applname, topicname {, bAnsi} )

Argument

Description

location

A string whose value is the location of the data you want returned from the DDE server application. The format of  location depends on the particular DDE server application that will receive the message.

target

A string variable into which the returned data will be placed.

applname

A string whose value is the DDE name of the DDE server application. If another PowerBuilder application is the DDE server, this is the application name specified in its StartServerDDE function call.

topicname

A string identifying the data or the instance of the application you want to use with the command (for example, in Microsoft Excel, the topic name could be system or the name of an open spreadsheet). If another PowerBuilder application is the DDE server, this is the topic specified in its StartServerDDE function call.

bAnsi

(optional)

A boolean identifying whether the string to get from the DDE server is in ANSI format. If bAnsi is NULL, false, or empty, PowerBuilder will first try to get the DDE data as a UNICODE formatted string. If bAnsi is true, PowerBuilder will try to get the DDE data as an ANSI formatted string.


Return value

Integer.

Returns 1 if it succeeds and a negative integer if an error occurs. Values are:

-1 -- Link was not started

-2 -- Request denied

If any argument's value is null, GetRemote returns null.

Usage

When using DDE, your PowerBuilder application must have an open window, which will be the client window. For this syntax, the active window is the DDE client window.

For more information about DDE channels and warm and cold links, see the two syntaxes of the ExecRemote function.

Examples

These statements ask Microsoft Excel to get the data in row 1 column 2 of a worksheet called PROFIT.XLS and put it in a PowerBuilder string called ls_ProfData. The single GetRemote call establishes a cold link, gets the data, and ends the link:

string ls_ProfData
GetRemote("R1C2", ls_ProfData, &
   "Excel", "PROFIT.XLS")

See also

ExecRemote

SetRemote

Syntax 2: For DDE requests via an open channel

Description

Asks a DDE server application to provide data and stores that data in the specified variable when you have already established a warm link by opening a channel to the server. A warm link, with an open channel, is more efficient when you intend to make several DDE requests.

Syntax

GetRemote ( location, target, handle {, windowhandle} {, bAnsi})

Argument

Description

location

A string whose value is the location of the data you want returned. The format of the location depends on the DDE application that will receive the request.

target

A PowerBuilder string variable into which the returned data will be placed.

handle

A long that identifies the channel to the DDE server application. The OpenChannel function returns handle when you call it to open a DDE channel.

windowhandle (optional)

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

bAnsi 

(optional)

A boolean identifying whether the string to get from the DDE server is in ANSI format. If bAnsi is NULL, false, or empty, PowerBuilder will first try to get the DDE data as a UNICODE formatted string. If bAnsi is true, PowerBuilder will try to get the DDE data as an ANSI formatted string.


Return value

Integer.

Returns 1 if it succeeds and a negative integer if an error occurs. Values are:

-1 -- Link was not started

-2 -- Request denied

-9 -- Handle is null

Usage

When using DDE, your PowerBuilder application must have an open window, which will be the client window. For this syntax, you can specify the client window with the windowhandle argument.

Before using this syntax, call OpenChannel to establish a DDE channel.

For more information about DDE channels and warm and cold links, see the ExecRemote function.

Examples

These statements ask the channel identified by handle (a Microsoft Excel worksheet) to get the data in row 1 column 2 and save it in a PowerBuilder string called ls_ProfData. GetRemote utilizes the warm link established by the OpenChannel function:

String ls_ProfData
long handle

handle = OpenChannel("Excel", "REGION.XLS")
...
GetRemote("R1C2", ls_ProfData, handle)
...
CloseChannel(handle)

The following example is similar to the previous one. However, it specifically associates the DDE channel with the window w_rpt:

String ls_ProfData
long handle

handle = OpenChannel("Excel", "REGION.XLS", &
   Handle(w_rpt))
...
GetRemote("R1C2", ls_ProfData, &
   handle, Handle(w_rpt))
...
CloseChannel(handle, Handle(w_rpt))

See also

CloseChannel

ExecRemote

OpenChannel

SetRemote