五、DDE客户函数

五、DDE客户函数

1、CloseChannel()

功  能：关闭先前用OpenChannel()函数打开的DDE服务器的通道。

语  法：CloseChannel ( handle {, windowhandle } )

参  数：handle：long类型，通道句柄，指明要关闭的DDE通道；

windowhandle：long类型，可选项，指明用做DDE客户的PowerBuilder窗口的窗口句柄。

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-2 -- 通道不能被关闭；

-3 -- 不能确认服务器；

-9 -- Handle参数的值为NULL。

用  法：使用CloseChannel()函数关闭用OpenChannel()函数打开的、连接DDE服务器应用程序的通道。虽然我们可以只指定通道句柄来关闭通道，但最好同时指定与通道相关联的句柄。如果指定了窗口句柄参数（windowhandle），CloseChannel()函数将关闭窗口句柄指定窗口的指定通道。如果未指定了窗口句柄参数（windowhandle），那么只有当指定的通道句柄与当前活动窗口关联时，CloseChannel()函数才会关闭该通道。使用Handle()函数可以得到窗口的句柄。

示  例：These statements open and close the channel identified by handle. The channel is associated with the window w_sheet: long handle

handle = OpenChannel("Excel", "REGION.XLS", &

    Handle(w_sheet) )

... // Some processing

CloseChannel(handle, Handle(w_sheet))

 

2、ExecRemote()

功  能：请求DDE服务器应用程序执行命令。该函数有两种语法格式：语法一、直接向DDE服务器应用发送一条命令（冷连接方式）；语法二、应用程序打开某个通道后向DDE服务器应用发送命令（热连接方式）。下面分别予以介绍。

语法一、直接向DDE服务器应用发送一条命令（冷连接方式）；

语  法：ExecRemote ( command, applname, topicname )

参  数：command：string类型，其值为希望DDE服务器应用执行的命令，命令格式和语法需要参看DDE服务器应用的文档；

applname：string类型，指定服务器应用的DDE名称；

topicname：string类型，指定命令中要使用的DDE应用的数据或实例。

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-1 -- 未启动连接；

-2 -- 请求被拒绝；

-3 -- 不能终止服务器。

如果任何参数的值为NULL，ExecRemote()函数返回NULL。

示  例：This statement asks Microsoft Excel to save the active spreadsheet as file REGION.XLS. A channel is not open, so the function arguments specify the application and topic (the name of the spreadsheet):

ExecRemote("[Save()]", "Excel", "REGION.XLS")

语法二、应用程序打开某个通道后向DDE服务器应用发送命令（热连接方式）

语  法：ExecRemote ( command, handle {, windowhandle } )

参  数：command：string类型，其值为希望DDE服务器应用执行的命令，命令格式和语法需要参看DDE服务器应用的文档；

handle：long类型，指定使用的DDE通道句柄；

windowhandle：long类型，可选项，指明用做DDE客户的PowerBuilder窗口的窗口句柄。省略该参数时，当前应用中的活动窗口用做DDE客户。

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-1 -- 未启动连接；

-2 -- 请求被拒绝；

-9 -- handle参数的值为NULL

示  例：This excerpt from a script asks the DDE channel to Microsoft Excel to save the active spreadsheet as file REGION.XLS. The OpenChannel function names the server application and the topic, so ExecRemote only needs to specify the channel handle. The script is associated with a button on a window, whose handle is specified as the last argument of OpenChannel:

long handle

handle = OpenChannel("Excel", "REGION.XLS", &

Handle(Parent))

. . . // Some processing

ExecRemote("[Save]", handle)

CloseChannel(handle, Handle(Parent))

3、GetDataDDE()

功  能：从热连接服务器应用中获取数据，并将其保存到指定的字符串变量中。

语  法：GetDataDDE ( string )

参  数：string：string类型变量，用于保存接收到的数据。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。如果任何参数的值为NULL，GetDataDDE()函数返回NULL。

示  例：Assuming that your PowerBuilder DDE client application has established a hot link with row 7, column 15 of an Excel spreadsheet, and that the value in that row and column address has changed from red to green (which triggers the HotLinkAlarm event in your application), this script for the HotLinkAlarm event calls GetDataDDE to store the new value in the variable Str20:

// In the script for a HotLinkAlarm event

string Str20

GetDataDDE(Str20)

 

4、GetDataDDEOrigin()

功  能：确定来自热连接DDE服务器应用的数据源，成功时将应用的DDE标识保存在参数指定的变量中。

语  法：GetDataDDEOrigin ( applstring, topicstring, itemstring )

参  数：applstring：string类型变量，用于保存服务器应用的名称；

topicstring：string类型变量，用于保存主题（比如，在Excel中，主题可以是REGION.XLS）；

itemstring：string类型变量，用于保存数据项标识（比如，在Excel中，数据项标识可以是R1C2）；

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。如果任何参数的值为NULL，GetDataDDEOrigin()函数返回NULL。

示  例：This example illustrates how to call GetDataDDEOrigin:

string WhichAppl, WhatTopic, WhatLoc

GetDataDDEOrigin(WhichAppl, WhatTopic, WhatLoc)

 

5、GetRemote()

功  能：请求服务器应用传送数据，该函数有两种格式：语法一、请求DDE服务器应用提供数据并将数据保存在变量中，该格式不要求事先打开通道，适用于仅发出少数几个请求的情况；语法二、请求DDE服务器应用提供数据并将数据保存在变量中，该格式适用于热连接的情况，即应用程序已经与服务器建立通道。下面分别予以介绍。

语法一、请求DDE服务器应用提供数据并将数据保存在变量中，该格式不要求事先打开通道，适用于仅发出少数几个请求的情况。

语  法：GetRemote ( location, target, applname, topicname )

参  数：location：string类型，指明要从DDE服务器的哪个位置返回数据。位置的表达方式由具体的DDE服务器决定；

target：string类型变量，用于保存返回的数据；

applname：string类型，指定DDE服务器应用的DDE名称；

topicname：string类型，指定命令中要使用的DDE应用的数据或实例。

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-1 -- 未启动连接；

-2 -- 请求被拒绝。

如果任何参数的值为NULL，GetRemote()函数返回NULL。

示  例：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")

语法二、请求DDE服务器应用提供数据并将数据保存在变量中，该格式适用于热连接的情况，即应用程序已经与服务器建立通道。

语  法：GetRemote ( location, target, handle {, windowhandle } )

参  数：location：string类型，指明要从DDE服务器的哪个位置返回数据。位置的表达方式由具体的DDE服务器决定；

target：string类型变量，用于保存返回的数据；

handle：long类型，指定使用的DDE通道句柄；

windowhandle：long类型，可选项，指明用做DDE客户的PowerBuilder窗口的窗口句柄。省略该参数时，当前应用中的活动窗口用做DDE客户。使用handle()函数可以得到窗口句柄。

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-1 -- 未启动连接；

-2 -- 请求被拒绝；

-9 -- Handle参数的值为NULL。

    示  例：1、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)

2、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))

 

6、OpenChannel()

功  能：打开连接DDE服务器的通道。

语  法：OpenChannel ( applname, topicname {, windowhandle } )

参  数：applname：string类型，指定DDE服务器应用的DDE名称；

topicname：string类型，指定命令中要使用的DDE应用的数据或实例；

windowhandle：long类型，可选项，指明用做DDE客户的PowerBuilder窗口的窗口句柄。省略该参数时，当前应用中的活动窗口用做DDE客户。

返回值：Long。函数执行成功时返回一个正数作为已打开通道的句柄，发生错误时返回下述值之一：

-1 -- 打开失败；

-9 -- 句柄为NULL。

    示  例：1、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")

2、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))

 

7、RespondRemote()

功  能：发送一条DDE消息，指示是否接受来自远程DDE应用的命令或数据。

语  法：RespondRemote ( boolean )

参  数：boolean：其值为boolean量的逻辑表达式，TRUE表示接收先前收到的命令或数据，FALSE表示不接收先前收到的命令或数据。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。如果boolean参数的值为NULL，RespondRemote()函数返回NULL。

示  例：In a script for the HotLinkAlarm event, these statements tell a remote application named Gateway that its data was successfully received:

String Applname, Topic, Item, Value

GetDataDDEOrigin(Applname, Topic, Item)

IF Applname = "Gateway" THEN

    IF GetDataDDE(Value) = 1 THEN

      RespondRemote(TRUE)

    END IF

END IF

 

8、SetRemote()

功  能：请求服务器应用把指定项设置为指定值。该函数有两种语法格式：语法一、请求DDE服务器应用接收保存在指定位置的数据，该格式不要求事先打开通道，适用于仅发出少数几个请求的情况；语法二、请求DDE服务器应用接收保存在指定位置的数据，该格式适用于热连接的情况，即应用程序已经与服务器建立通道。下面分别予以介绍。 

语法一、请求DDE服务器应用接收保存在指定位置的数据，该格式不要求事先打开通道，适用于仅发出少数几个请求的情况。

语  法：SetRemote ( location, value, applname, topicname )

参  数：location：string类型，指明要DDE服务器的哪一部分接收数据。位置的表达方式由具体的DDE服务器决定；

value：string类型变量，指定发送给DDE服务器的数据；

applname：string类型，指定DDE服务器应用的DDE名称；

topicname：string类型，指定要接收数据的DDE应用的数据或实例。

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-1 -- 未启动连接；

-2 -- 请求被拒绝。

如果任何参数的值为NULL，SetRemote()函数返回NULL。

示  例：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")

语法二、请求DDE服务器应用接收保存在指定位置的数据，该格式适用于热连接的情况，即应用程序已经与服务器建立通道。

语  法：SetRemote ( location, value, handle {, windowhandle } )

参  数：location：string类型，指明要DDE服务器的哪一部分接收数据。位置的表达方式由具体的DDE服务器决定；

value：string类型变量，指定发送给DDE服务器的数据；

handle：long类型，指定使用的DDE通道句柄；

windowhandle：long类型，可选项，指明用做DDE客户的PowerBuilder窗口的窗口句柄。省略该参数时，当前应用中的活动窗口用做DDE客户；

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-1 -- 未启动连接；

-2 -- 请求被拒绝；

-9 -- Handle参数的值为NULL。

示  例：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)

 

9、StartHotLink()

功  能：建立与DDE服务器应用的热连接，热连接建立之后，DDE服务器端相关数据的变化会立即触发PowerBuilder应用相关窗口的HotLinkAlarm事件。

语  法：StartHotLink ( location, applname, topic )

参  数：location：string类型，指明DDE服务器哪一部分数据变化时触发窗口的HotLinkAlarm事件。位置的表达方式由具体的DDE服务器决定；

applname：string类型，指定DDE服务器应用的DDE名称；

topicname：string类型，指定数据改变将触发窗口的HotLinkAlarm事件的DDE应用的数据或实例。

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-1 -- 无指定服务器；

-2 -- 请求被拒绝。

如果任何参数的值为NULL，StartHotLink()函数返回NULL。

示  例：1、In this example, another PowerBuilder application has called the StartServerDDE function and identified itself as MyPBApp. This statement in your application establishes a hot link to data in   MyPBApp. The values you specify for location and topic depend on conventions established by MyPBApp:

StartHotLink("Any", "MyPBApp", "Any")

2、This statement establishes a hot link with Microsoft Excel, which notifies the PowerBuilder window when the data at row 1 column 2 of REGION.XLS changes:

StartHotLink("R1C2", "Excel", "Region.XLS")

    10、StopHotLink()

功  能：关闭与DDE服务器应用的热连接。

语  法：StopHotLink ( location, applname, topic )

参  数：location：string类型，指明要终止DDE服务器哪一部分的热连接。位置的表达方式由具体的DDE服务器决定；

applname：string类型，指定DDE服务器应用的DDE名称；

topicname：string类型，指定要终止热连接的DDE应用的数据或实例。

返回值：Integer。函数执行成功时返回1，发生错误时返回下述值之一：

-1 -- 连接未曾启动；

-2 -- 请求被拒绝；

-3 -- 不能终止服务器。

如果任何参数的值为NULL，StopHotLink()函数返回NULL。

示  例：If another PowerBuilder application called StartServerDDE to establish itself as a server using the name MyPBApp, then your application can act as a DDE client and call StartHotLink to establish a hot link with MyPBApp. The following statement ends that hot link. The values you specify for location and

topic depend on conventions established by MyPBApp:

StopHotLink("Any", "MyPBApp", "Any")

This statement stops the hot link with Microsoft Excel for row 1 column 2 in the spreadsheet REGION.XLS:

StopHotLink("R1C2", "Excel", "Region.XLS")