Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

DDE Statements

Return to Main Page


DDEAdvise

Description

Requests a DDE server to advise the application when the data associated with a requested topic changes.

Syntax

 FUNCTION DDEAdvise(VAL whdl, whdlPartner: WINDOW,
                    VAL topic:STRING,VAL Flag: INTEGER)
                    : INTEGER;

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
whdlPartner The handle of a window from the partner application in the conversation. This is the window that the DDE function addresses. Typically this is the $DDEWindow pseudo parameter that is part of all DDE messages.
topic The data item addressed in the partner application by the DDE function. Both applications engaging in a DDE conversation must agree on the topics of conversation and the actions available for a given topic. If the topic string is empty, all available topics are assumed.
Flag A flag that indicates the type of advisement requested. Possible values are:
  • $DDEack - Request an acknowledgement from partner
  • $DDENoData - Advise when data has changed (by DDE Data Message) but do not pass the data.

Notes

DDEAdvise requests a DDE server to post a $MsgDDEData to the window handle whenever the data associated with the topic changes. Data messages sent in such a manner do not have the DDEResponse bit set in their status flags. A DDEAdvise message may be canceled by a DDEUnAdvise.

Example

For an example about the use of DDE commands in TSD Script to communicate with other applications, see the files, ddetcli.kb and ddetsrv.kb in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit was installed.

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.

See Also

For more information see the TSD Script Messages page.


DDEData

Description

Sends data via DDE to a requesting application.

Syntax

 FUNCTION DDEData(VAL whdl, whdlPartner: WINDOW,
 VAL topic,data: STRING,
 VAL Flag: INTEGER): INTEGER;

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
whdlPartner The window handle from the partner application window in the conversation. This is the window that the DDE function addresses. Typically this is the $DDEWindow pseudo parameter that is part of all DDE messages.
topic The data item addressed in the partner application by the DDE function. Both applications engaging in a DDE conversation must agree on the topics of conversation and the actions available for a given topic. If the topic string is empty, all available topics are assumed.
data The data to be sent to the partner application.
Flag A flag that indicates the type of advisement requested. Possible values are:
  • $DDEack - Request an acknowledgement from partner
  • $DDENoData - Advise when the data has changed (by DDE Data Message) but do not pass the data.

Notes

DDEData sends data in response to a $MsgDDERequest. It may also send data that an application has requested. DDEPoke is used to send unsolicited data to an application.

Example

 TYPES
 DDEREC IS RECORD
 partners: LIST OF DDEPARTNERREC;
 whdlPartner: WINDOW;
 END;
 .
 .
 .
EVENT DDEWindow( REF DDEDataRec: DDEREC ) IS
 ...
ACTIONS
 WHEN $Event IS $MsgCreate THEN
 ...
 ELSWHEN $MsgDDERequest THEN
 WHEN $EventParm(2,STRING) IS 'TOPICS' THEN
 DDEData( $Handle, $DDEWindow, $DDETopic, 'TEST');
 ...
END;

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.

See Also

See the TSD Script Messages page for more information.

For additional examples about the use of DDE commands in TSD Script to communicate with other applications, see the files, ddetcli.kb and ddetsrv.kb in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit was installed.


DDEExecute

Description

Sends a command string for execution by a DDE partner.

Syntax

 FUNCTION DDEExecute(VAL whdl, whdlPartner: WINDOW,
                     VAL topic, cmdString: STRING)
                     : INTEGER;

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
whdlPartner The window handle from the partner application window in the conversation. This is the window that the DDE function addresses. Typically this is the $DDEWindow pseudo parameter that is part of all DDE messages.
topic The data item addressed in the partner application by the DDE function. Both applications engaging in a DDE conversation must agree on the topics of conversation and the actions available for a given topic. If the topic string is empty, all available topics are assumed.
cmdString A string command for the DDE partner. The content and format of the command string must be agreed upon by the applications engaged in the DDE conversation.

Example

 VARIABLES
 rc: INTEGER;
 partner_whdl: WINDOW;
 partner_topic: STRING;
ACTIONS
 .
 . (* Assuming a DDE session has been initiated, topic is
 set. *)
 .
 rc := DDEExecute ( $Handle, partner_whdl, partner_topic,
                    "del *.*" );
 IF (rc <> 1) THEN
 (* DDEExecute failed *)
 ELSE
 (* DDEExecute succeeded *)
END;
 .
 .
 .
END;

Return Codes

Return Code Description
1 Successful completion.
-2 Unknown value.
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.

See Also

For information see the TSD Script Messages page.

For additional examples about the use of DDE commands in TSD Script to communicate with other applications, see the ddetcli.kb and ddetsrv.kb files in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit was installed.


DDEInitiate

Description

Initiates a DDE conversation with one or more partners.

Syntax

 FUNCTION DDEInitiate(VAL whdl: WINDOW, VAL topic,
                      appName: STRING): INTEGER;

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
topic The data item addressed in the partner application by the DDE function. Both applications engaging in a DDE conversation must agree on the topics of conversation and the actions available for a given topic. If the topic string is empty, all available topics are assumed.
appName The name of an application with which this application wishes to converse. If appName is an empty string or $Unknown, all applications that support the requested topic are expected to respond.

Notes

DDEInitiate broadcasts an initiate message to all child windows of the desktop. The initiate message is platform-specific.

If an appName is specified, any application with the matching appName should respond. The matching application should send a $MsgDDEInitAcknowledge to the initiating window. If appName is an empty string, any application can respond.

If the topic has a zero-length string, all matching applications should report all available topics. For example, calling DDEInitiate with an empty appName and an empty topic string requests all topics from applications that are DDE servers.

Example

 VARIABLES
 rc: INTEGER;
 partner_whdl: WINDOW;
 partner_topic: STRING;
 partner_app: STRING;
ACTIONS

(* Assuming partner variables have been set. *)

 rc := DDEInitiate ( $Handle, partner_topic, partner_app );
 IF (rc <> 1) THEN
 (* DDEInitiate failed *)
 ELSE
 (* DDEInitiate succeeded *)
 END;
END;

Return Codes

Return Code Description
1 Successful completion.
-2 Unknown value.
-10 A request for an operating system service (required to complete the function) failed. Likely causes are invalid values as arguments to the statement or system resource limitations.

See Also

For information see the TSD Script Messages page.

For additional examples on using DDE commands in TSD Script to communicate with other applications, see the files, ddetcli.kb and ddetsrv.kb in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit resides.

For more information about the DDE interface, see your vendor documentation.


DDEPoke

Description

Sends unsolicited data to a DDE partner.

Syntax

 FUNCTION DDEPoke(VAL whdl, whdlPartner: WINDOW, VAL topic,
                  data: STRING): INTEGER;

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
whdlPartner The window handle from the partner application window in the conversation. This is the window that the DDE function addresses. Typically this is the $DDEWindow pseudo parameter that is part of all DDE messages.
topic The data item addressed in the partner application by the DDE function. Both applications engaging in a DDE conversation must agree on the topics of conversation and the actions available for a given topic. If the topic string is empty, all available topics are assumed.
data Unsolicited data sent to a DDE partner. The receiving application must know how to accept data on the specified topic.

Example

 VARIABLES
 rc: INTEGER;
 partner_whdl: WINDOW;
 partner_topic: STRING;
 partner_data: STRING;

ACTIONS

(* Assuming session Initiated, partner variables have
 been set. *)

 rc := DDEPoke ($Handle, partner_whdl, partner_topic,
                partner_data );
 IF (rc < 1) THEN
 (* DDEPoke failed *)
 ELSE
 (* DDEPoke succeeded *)
 END;
 ...
END;

Return Codes

Return Code Description
1 Successful completion.
-2 Unknown value.
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.

See Also

DDEData

For information see the TSD Script Messages page.

For additional examples about the use of DDE commands in TSD Script to communicate with other applications, see the ddetcli.kb and ddetsrv.kb files in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit was installed.


DDERequest

Description

Requests data from a DDE partner.

Syntax

 FUNCTION DDERequest(VAL whdl, whdlPartner: WINDOW,
 VAL topic: STRING): INTEGER;

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
whdlPartner The window handle from the partner application window in the conversation. This is the window that the DDE function addresses. Typically this is the $DDEWindow pseudo parameter that is part of all DDE messages.
topic The data item addressed in the partner application by the DDE function. Both applications engaging in a DDE conversation must agree on the topics of conversation and the actions available for a given topic. If the topic string is empty, all available topics are assumed.

Notes

The partner application may respond by sending the requested data or by sending a negative acknowledgment ($MsgDDEAcknowledge).

Example

 VARIABLES
 rc: INTEGER;
 partner_whdl: WINDOW;
 partner_topic: STRING;
 partner_data: STRING;
ACTIONS
(* Assuming session Initiated, partner variables have
 been set. *)
 DDERequest ( $Handle, partner_whdl, partner_topic );

 (* The DDE Partner will respond with Data or Acknowledge *)

EVENT DDEWindow( REF DDEDataRec: DDEREC ) IS
 ...
ACTIONS
 WHEN $Event IS $MsgCreate THEN
 ...
 ELSWHEN $MsgDDEAcknowledge THEN
 (* Look in $DDETopic, $DDEData and $DDEStatus for
 information. *)
 ...
 ELSWHEN $MsgDDEData THEN
 (* Look in $DDETopic and $DDEData for information. *)
 ...
 END;
END;

Return Codes

Return Code Description
1 Successful completion.
-2 Unknown value.
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.

See Also

For information see the TSD Script Messages page.

For additional examples about the use of DDE commands in TSD Script to communicate with other applications, see the files, ddetcli.kb and ddetsrv.kb in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit was installed.


DDERespond

Description

Sends a response to a $MsgDDEInitiate message.

Syntax

 FUNCTION DDERespond(VAL whdl, whdlPartner: WINDOW,
                     VAL topic, VAL appName: STRING): INTEGER;

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
whdlPartner The window handle from the partner application window in the conversation. This is the window that the DDE function addresses. Typically this is the $DDEWindow pseudo parameter that is part of all DDE messages.
topic The data item addressed in the partner application by the DDE function. Both applications engaging in a DDE conversation must agree on the topics of conversation and the actions available for a given topic. If the topic string is empty, all available topics are assumed.
appName The name of the calling application. This name identifies the application to potential DDE clients. It is recommended that Tivoli Service Desk Developer's Toolkit applications use the name of the main knowledgebase.

Notes

DDERespond is used in response to a $MsgDDEInitate. It identifies the application as a DDE server to potential DDE clients (initiators). $MsgDDEInitiate contains a requested application name in $DDEData, and a requested topic in $DDETopic. For every application or topic match, a server is expected to call DDERespond with the following:

Empty or $Unknown strings are assumed to match any appName or topic.

Example

 VARIABLES
 rc: INTEGER;
 partner_whdl: WINDOW;
 partner_topic: STRING;
 partner_data: STRING;

EVENT DDEWindow( REF DDEDataRec: DDEREC ) IS
 ...
ACTIONS
 WHEN $Event IS $MsgCreate THEN
 ...
 ELSWHEN $MsgDDEInitiate THEN
 (* Look in $DDETopic, $DDEData and $DDEWindow for
 information. *)
 WHEN $DDETopic IS '' THEN
 (* Indicate all topics to which this app will respond *)
 DDERespond($Handle, $DDEWindow, 'TOPIC1',
 thisAppName);
 DDERespond($Handle, $DDEWindow, 'TOPIC2',
 thisAppName);
 ELSWHEN 'TOPIC1' THEN
 DDERespond($Handle, $DDEWindow, 'TOPIC1',
 thisAppName);
 ELSWHEN 'TOPIC2' THEN
 DDERespond($Handle, $DDEWindow, 'TOPIC2',
 thisAppName);
 END;
 ...
 END;
END;

Return Codes

Return Code Description
1 Successful completion.
-2 Unknown value.

See Also

For information see the TSD Script Messages page.

For additional examples about the use of DDE commands in TSD Script to communicate with other applications, see the files, ddetcli.kb and ddetsrv.kb in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit was installed.


DDETerminate

Description

Terminates a DDE conversation.

Syntax

 FUNCTION DDETerminate(VAL whdl, VAL whdlPartner: WINDOW):INTEGER;

Caution: Improperly terminated DDE conversations may cause the program to pause processing.

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
whdlPartner The window handle from the partner application window in the conversation. This is the window that the DDE function addresses.

Notes

After a DDE whdlPartner connection is established, the value of the partner application window should be stored in a local variable of type WINDOW (DDEPartnerWindow, for example). The value of the partner application can be found in the $DDEWindow pseudo parameter immediately after the DDE connection is established.

For example:

 ...
VARIABLES&;DDEPartnerWindow : WINDOW;
...
ELSWHEN $MsgInitiate THEN
...
DDEPartnerWindow := $DDEWindow;
...

When the program terminates, and while the program is handling the $MsgDestroy event, call DDETerminate with parameters $Handle and the window handle of the remote partner application (DDEPartnerWindow) to avoid memory leaks.

For example:

 ELSWHEN $MsgDestroy THEN
...
DDETerminate ($Handle, DDEPartnerWindow);
...

Example

 TYPES
 DDEPARTNERREC IS RECORD
 whdl: WINDOW;
 topic: STRING;
 appName: STRING;
 data: STRING;
 END;

 DDEREC IS RECORD
 partners: LIST OF DDEPARTNERREC;
 whdlPartner: WINDOW;
 END;

EVENT DDEWindow( REF DDEDataRec: DDEREC ) IS
 ...
ACTIONS
 WHEN $Event IS $MsgCreate THEN
 ...
 ELSWHEN $MsgDestroy THEN

 (* Must terminate the sessions for all
 initiated partners. *)

 FOR ddeDataRec.partners DO
 DDETerminate ( $Handle, ddeDataRec.partners
 [$CURRENT].whdl );
 END;
 END;
 ...
END; ...

Return Codes

Return Code Description
1 Successful completion.
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.

See Also

For additional examples about the use of DDE commands in TSD Script to communicate with other applications, see the files, ddetcli.kb and ddetsrv.kb in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit was installed.


DDEUnAdvise

Description

Cancels a DDEAdvise request.

Syntax

 FUNCTION DDEUnAdvise(VAL whdl, whdlPartner: WINDOW,
                      VAL topic: STRING): INTEGER;

Argument Notes

Argument Name Description
whdl The window handle of the application window that receives response messages from a DDE partner. Generally, this window is a child of the desktop and is the application's main window. When the DDE function responds to a DDE message, this parameter is the $Handle pseudo parameter.
whdlPartner The window handle from the partner application window in the conversation. This is the window that the DDE function addresses. Typically this is the $DDEWindow pseudo parameter that is part of all DDE messages.
topic The data item addressed in the partner application by the DDE function. Both applications engaging in a DDE conversation must agree on the topics of conversation and the actions available for a given topic. If the topic string is empty, all available topics are assumed.

Notes

DDEUnAdvise cancels a DDEAdvise for a given topic on a given server. If topic is a 0-length string, all advises are canceled on that server for the requesting client.

Example

For an example about the use of DDE commands in TSD Script to communicate with other applications, see the files, ddetcli.kb and ddetsrv.kb in the EXAMPLES/DDE directory where Tivoli Service Desk Developer's Toolkit was installed.

Return Codes

Return Code Description
1 Successful completion
-2 Unknown value
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.

See Also


Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Return to Main Page

Copyright