DDE Interface

Overview
Calling Creo Elements/Direct Modeling commands from external applications
Calling external applications from Creo Elements/Direct Modeling
API reference

Overview

Creo Elements/Direct Modeling and other applications can communicate using DDE (Dynamic Data Exchange). DDE is a standard Windows method for interprocess communication. It allows applications implementing macro languages to call each other's macro commands. DDE calls can be implemented in various programming languages like Visual Basic or C++.

Creo Elements/Direct Modeling Lisp commands can be executed easily from any DDE client application by passing the Lisp command with a DDE call. Vice versa, Creo Elements/Direct Modeling can call any other application (which implements a DDE server) by using built-in Lisp commands.

The following sections describe the communication in either direction by using example code. The actual function names used to implement a DDE connection are heavily language dependent. The examples in this document use the Visual Basic command syntax because it is easy to understand and not covered with too much overhead. The MSDN article "Implementing DDE Using C++ Classes" provides examples on how to implement a DDE client in C++.

Calling Creo Elements/Direct Modeling commands from external Applications

Creo Elements/Direct Modeling implements a DDE server that allows the caller to connect to Creo Elements/Direct Modeling and execute any Lisp command as if it had been entered in Creo Elements/Direct Modeling's user input line.

To connect to a DDE server, the client needs two keys: the service name and the topic name. The service name identifies the DDE server. For Creo Elements/Direct Modeling, the service name is "PESD"; for Creo Elements/Direct 3D Access, the name is "SD_ACCESS". The topic name is an application-specific string and must be understood by the DDE Server. Creo Elements/Direct Modeling understands one topic name by default which lets the client execute commands in Creo Elements/Direct Modeling. This topic name is "GENERAL".

Both the service name and topic name must be supplied when establishing a DDE connection to Creo Elements/Direct Modeling. This is done by:

    nChannelNumber = DDEInitiate("PESD", "GENERAL")

DDEInitiate returns a channel number which has to be used in further calls to Creo Elements/Direct Modeling. These calls are done using the DDEExecute command.

The following example loads a 3D model into Creo Elements/Direct Modeling:

    bSuccess = DDEExecute(nChannelNumber, "(load_package ""d:/users/SDUser/Model.pkg"")")

The command string (second parameter) is an arbitrary Lisp command understood by Creo Elements/Direct Modeling. The additional double quotes in the example are only used to mask the quotes. The actual command executed in Creo Elements/Direct Modeling is:

    (load_package "d:/users/SDUser/Model.pkg")

It is also possible to request variable values from Creo Elements/Direct Modeling using DDE. This is done using the DDERequest command.

Let's assume the variable myVariable has been set to a string as follows:

    DDEExecute(nChannelNumber, "(setf myLispVariable ""My Value"")")

Here's how an external program could inquire the variable value from MODELING_NAME:

    myVariable = DDERequest(nChannelNumber, "myLispVariable")

MyVariable will hold the value "My Value" after this call.

DDEInitiate, DDEExecute and DDERequest are the most frequently-used DDE commands needed for Creo Elements/Direct Modeling communication.

The client has to ensure that resources are returned to the system when the connection is no longer needed by explicitly terminating the connection:

    DDETerminate(nChannelNumber, "PESD")

Calling external applications from Creo Elements/Direct Modeling

All necessary DDE commands needed to call an external DDE server are available as IKIT APIs.

The application called from Creo Elements/Direct Modeling must implement a DDE server and should be able to interpret and handle command strings passed by DDEExecute. The usual design approach is that the commands are written in a macro language which is interpreted by the external application.

A detailed description of all Creo Elements/Direct Modeling DDE-specific Lisp functions follows.

String handling

Starting with CoCreate OneSpace Modeling 2007, Creo Elements/Direct Modeling registers as a Unicode DDE server and client. This can have subtle implications for old non-Unicode DDE clients which made assumptions about the encoding used for strings sent in DDE messages.

Any data sent to other applications via DDE are encoded in UTF-16. If the other application registers as a non-Unicode DDE server or client, the operating system will perform an automatic string conversion from UTF-16 encoding to the encoding which corresponds to the system's codepage. The default system codepage for Western European or US systems is CP1252, which is a variant of ISO8859-1; when running on a Japanese version of Windows, the system defaults to codepage CP932, which is a variant of Shift-JIS encoding.

DDE integrations with versions of Creo Elements/Direct Modeling preceding CoCreate OneSpace Modeling 2007 may need to be reviewed for proper handling of encodings, in particular if umlauts or accented characters are sent over the DDE communication mechanism.

API reference

SD-DDE-ENABLE [function]

(sd-dde-enable on-off)

Description:

If on-off is set to :on, Creo Elements/Direct Modeling will act as a DDE server with the service name "PESD", Creo Elements/Direct 3D Access with the service name "SD_ACCESS".
If :off is specified, then Creo Elements/Direct Modeling (Creo Elements/Direct 3D Access) no longer acts as a DDE server.

Parameters:

on-off {KEYWORD} - :on or :off

Return Value:

t - success
nil - failure

Example:

(sd-dde-enable :on)

SD-DDE-INITIATE [function]

(sd-dde-initiate servicename topicname)

Description:

Creo Elements/Direct Modeling will act as a DDE client when this command is invoked, attempting to connect to a DDE server with the service name and topic name provided as parameters to this function. Upon success, a DDE conversation handle is returned. This handle must then be specified in any subsequent commands used to communicate to the DDE server application.
It is possible for a client application to have more than one conversation handle in existence at a time, with the same DDE server application.

Parameters:

servicename {STRING} - service name of the DDE server
topicname {STRING} - topic name of the DDE server

Return Value:

handle {STRUCTURE} - conversation handle
:error - failure

Example:

(setq handle (sd-dde-initiate "Server1" "Topic1"))

SD-DDE-EXECUTE [function]

(sd-dde-execute handle command)

Description:

This command sends the string specified in the command parameter to the DDE connection specified in handle as a command string.

Parameters:

handle {STRING} - handle of DDE connection
command {STRING} - command to be executed on DDE server

Return Value:

:no_error - success
:busy - DDE server busy right now
:error - failure

Example:

(setq result (sd-dde-execute handle "DoIt"))

SD-DDE-POKE [function]

(sd-dde-poke handle item data)

Description:

Using the DDE connection identified by handle, this command writes the string specified in the data parameter into a DDE item.

Parameters:

handle {STRING} - handle of DDE connection
item {STRING} - item in application to be modified
data {STRING} - data to be written

Return Value:

:no_error - success
:busy - DDE server busy right now
:error - failure

Example:

(setq result (sd-dde-poke handle "R1C1" "42"))

SD-DDE-REQUEST [function]

(sd-dde-request handle item)

Description:

This function returns the string value of the item from the application relevant to the handle parameter.

Parameters:

handle {STRING} - handle of DDE connection
item {STRING} - item in application to inquire

Return Value:

item-value - value of item as string
:busy - DDE server busy right now
:error - failure

Example:

(setq status (sd-dde-request handle "StatusVar"))

SD-DDE-ADVISE [function]

(sd-dde-advise handle item on-off handlerfunction)

Description:

This function starts or stop a DDE advise loop for the conversation handle and the item item. While the advise loop is active, changes in item in the external DDE server will be reported back as calls to handlerfunction.

Parameters:

handle {STRING} - handle of DDE connection
item {STRING} - item in application to inquire
on-off {KEYWORD} - :on to start DDE advise loop, :off to stop it
handlerfunction {FUNCTION} - a function which is called when item changes

Return Value:

:no_error - success
:busy - DDE server busy right now
:error - failure

Example:

(setf ddehandle (sd-dde-initiate "Excel" "[Book1]Sheet1"))

(defun ddeadvisehandler(args)
  (let ((item (second args))
        (hconv (first args)))
    (when (and (string= item "r1c1") (equal ddehandle hconv))
      (format t "Item ~S was updated - new value is ~S~%"
                 item (third args)))))
                
(sd-dde-advise ddehandle "r1c1" :on 'advisehandler)
...
(sd-dde-advise ddehandle "r1c1" :off 'advisehandler)

SD-DDE-ADD-TOPIC [function]

(sd-dde-add-topic topic-name)

Description:

This function allows you to add a new topic name to Creo Elements/Direct Modeling or Creo Elements/Direct 3D Access.

Parameters:

topic-name {STRING} - name of new topic

Return Value:

t - success
nil - failure

Example:

(setq result (sd-dde-add-topic "New Topic"))

SD-DDE-REMOVE-TOPIC [function]

(sd-dde-remove-topic topic-name)

Description:

This function allows you to remove a previously added topic name again from Creo Elements/Direct Modeling or Creo Elements/Direct 3D Access.

Parameters:

topic-name {STRING} - name of topic to remove

Return Value:

t - success
nil - failure

Example:

(setq result (sd-dde-remove-topic "New Topic"))

SD-DDE-CLOSE [function]

(sd-dde-close handle)

Description:

This function closes the DDE connection specified by handle.

Parameters:

handle {STRING} - handle of DDE connection

Return Value:

t - success
nil - failure

Example:

(sd-dde-close handle)

SD-DDE-REQUEST-TIMEOUT [function]

(sd-dde-request-timeout timeout)

Description:

The parameter timeout specifies the timeout in milliseconds which should be allowed on all future sd-dde-request function calls.
The default value is five minutes.

Parameters:

timeout {FIXNUM} - timeout in milliseconds

Return Value:

t - success
nil - failure

SD-DDE-EXECUTE-TIMEOUT [function]

(sd-dde-execute-timeout timeout)

Description:

The parameter timeout specifies the timeout in milliseconds which should be allowed on all future sd-dde-execute function calls.
The default value is five minutes.

Parameters:

timeout {FIXNUM} - timeout in milliseconds

Return Value:

t - success
nil - failure