SetRemote

Asks a DDE server application to accept data and store it in the specified location. There are two ways of calling SetRemote, depending on the type of DDE connection you have established.

To

Use

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

Syntax 1

Make a DDE request of a server application when you have established a warm link by opening a channel

Syntax 2


Syntax 1: For single DDE requests

Description

Asks a DDE server application to accept data to be stored in the specified location without requiring an open channel. This syntax is appropriate when you will make only one or two requests of the server.

Syntax

SetRemote ( location, value, applname, topicname {, bAnsi} )

Argument

Description

location

A string whose value is the location of the data in the server application that will accept the data. The format of location depends on the application that will receive the request.

value

A string whose value you want to send to the remote application.

applname

A string whose value is the DDE name of the server application.

topicname

A string identifying the data or the instance of the application that will accept the data (for example, in Microsoft Excel, the topic name could be the name of an open spreadsheet).

bAnsi

(optional)

A boolean identifying whether the string to send to the DDE server is in ANSI format. If bAnsi is NULL, false, or empty, PowerBuilder will first try to send the data in a UNICODE formatted string. If bAnsi is true, PowerBuilder will try to send the data in 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, SetRemote 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 ExecRemote function.

Examples

This statement asks Microsoft Excel to set the value of the data in row 5, column 7 of a worksheet called SALES.XLS to 4500:

SetRemote("R5C7", "4500", "Excel", "SALES.XLS")

See also

ExecRemote

GetRemote

OpenChannel

Syntax 2: For DDE requests via an open channel

Description

Asks a DDE server application to accept data to be stored in the specified location 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

SetRemote ( location, value, handle {, windowhandle } {, bAnsi})

Argument

Description

location

A string whose value is the location of the data in the server application that will accept the data. The format of location depends on the application that will receive the request.

value

A string whose value you want to send to the remote application.

handle

A long that identifies the channel to the DDE server application. Handle is the value returned by OpenChannel, which you call to open a DDE channel.

windowhandle (optional)

The handle to the window that is acting as the DDE client.

bAnsi

(optional)

A boolean identifying whether the string to send to the DDE server is in ANSI format. If bAnsi is NULL, false, or empty, PowerBuilder will first try to send the data in a UNICODE formatted string. If bAnsi is true, PowerBuilder will try to send the data in 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 a client window other than the active window with the windowhandle argument.

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

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

Examples

This example opens a channel to a Microsoft Excel worksheet and asks it to set the value of the data in row 5 column 7 to 4500:

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

See also

ExecRemote

GetRemote

OpenChannel