Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference
Return to Main Page
Requests a DDE server to advise the application when the data associated with a requested topic changes.
FUNCTION DDEAdvise(VAL whdl, whdlPartner: WINDOW, VAL topic:STRING,VAL Flag: INTEGER) : INTEGER;
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:
|
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.
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 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. |
For more information see the TSD Script Messages page.
Sends data via DDE to a requesting application.
FUNCTION DDEData(VAL whdl, whdlPartner: WINDOW, VAL topic,data: STRING, VAL Flag: INTEGER): INTEGER;
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:
|
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.
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 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 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.
Sends a command string for execution by a DDE partner.
FUNCTION DDEExecute(VAL whdl, whdlPartner: WINDOW, VAL topic, cmdString: STRING) : INTEGER;
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. |
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 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. |
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.
Initiates a DDE conversation with one or more partners.
FUNCTION DDEInitiate(VAL whdl: WINDOW, VAL topic, appName: STRING): INTEGER;
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. |
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.
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 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. |
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.
Sends unsolicited data to a DDE partner.
FUNCTION DDEPoke(VAL whdl, whdlPartner: WINDOW, VAL topic, data: STRING): INTEGER;
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. |
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 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. |
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.
Requests data from a DDE partner.
FUNCTION DDERequest(VAL whdl, whdlPartner: WINDOW, VAL topic: STRING): INTEGER;
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. |
The partner application may respond by sending the requested data or by sending a negative acknowledgment ($MsgDDEAcknowledge).
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 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. |
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.
Sends a response to a $MsgDDEInitiate message.
FUNCTION DDERespond(VAL whdl, whdlPartner: WINDOW, VAL topic, VAL appName: STRING): INTEGER;
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. |
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.
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 Code | Description |
1 | Successful completion. |
-2 | Unknown value. |
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.
Terminates a DDE conversation.
FUNCTION DDETerminate(VAL whdl, VAL whdlPartner: WINDOW):INTEGER;
Caution: Improperly terminated DDE conversations may cause the program to pause processing.
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. |
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); ...
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 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. |
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.
Cancels a DDEAdvise request.
FUNCTION DDEUnAdvise(VAL whdl, whdlPartner: WINDOW, VAL topic: STRING): INTEGER;
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. |
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.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 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. |
Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference