Application Development

Prolifics supports Windows Dynamic Data Exchange (DDE), which lets applications share data through client/server links. Prolifics supports both client and server links with other applications. As a DDE server, a Prolifics application exports data from a field. As a DDE client, it imports data from another application into a field.

Prolifics as a DDE Server

As a DDE server, Prolifics can export data from a named field to a client application. The client application specifies a DDE service, topic and item. In Prolifics, these correspond to the application name, screen name and field name, respectively.

For example, an Excel spreadsheet can request a link between one of its cells and a Prolifics field. The request must include the name of the Prolifics server name, the screen name, and the field name. If the request succeeds, a DDE connection is created between that spreadsheet window and the Prolifics screen; this connection initially consists of the requested link, and can also accommodate other links that the client might request later.

Enabling Connections

Before a client application can request links to a Prolifics application, two conditions must be true:

• The Prolifics application must be running.

• The application must be enabled as a DDE server.

To enable Prolifics as a server, call sm_dde_server_on or include this setting in the initialization file prol5w32.ini:

DDEServer=on

Clients can create links to a Prolifics screen either through the clipboard or by explicitly issuing a request.

Paste Links

You can use the Windows clipboard data to create a link to a Prolifics application:

1. Copy data from a Prolifics field to the clipboard. The clipboard data includes the link information required by DDE: service, topic, and item.
2. Paste link the clipboard data into the client application. The link information that is embedded in the pasted data initiates a link request from this client to the originating Prolifics screen.

You can also create links to a Prolifics screen through explicit requests in the client application's DDE syntax. Refer to your client application's documentation for details on its DDE syntax.

Notes: Prefix the topic name with ampersands (& or &&) if you want the Prolifics screen to open as a stacked or sibling window.

The following examples show DDE syntax for several widely used Windows applications:

Quattro Pro for Windows

It is the client application's responsibility to connect with a Prolifics screen and create links to the required fields. Most client applications automatically establish a connection when they request a link.

When DDE gets a link request that is intended for a Prolifics application, it processes it as follows:

1. Finds a match between the specified service and a Prolifics application that is already running.
2. Checks whether the Prolifics application is enabled as a DDE server.
3. Matches the specified topic to a screen and checks whether a connection already exists.
4. Opens the screen, if necessary, and matches the specified item to a field.
5. Creates a link between the client and the field.

Links remain in effect until they are explicitly closed by the client or the Prolifics application exits. Prolifics maintains links for a screen that is inactive or closed, and resumes data updates when the screen reopens. The client's connection to a Prolifics screen remains active until all links to the current screen are destroyed.

Prolifics destroys links only at the request of the client or when the Prolifics application terminates. When the client destroys its last link to a screen, its connection to that screen is broken.

Updating Client Data

A client can create three kinds of links to Prolifics fields:

Hot Links

Prolifics automatically updates the client with new data as soon as linked field data changes. Hot links are maintained only for fields on the active screen.

Warm Links

Prolifics notifies the client when linked field data changes. The client must then request the data. Notice is sent only for fields on the active screen. Requests for data succeed only if the linked field is on an active screen or in the LDB.

Cold Links

Prolifics updates the client with new field data only when the client requests it. Requests for data succeed only if the linked field is on an active screen or in the LDB.

Array Data

If the linked field is an array, Prolifics supplies all occurrences in the array. Occurrences are separated by carriage returns () and newlines (). Leading blanks in right-justified fields and trailing blanks in left-justified fields are omitted.

Data Conversion

Prolifics supplies text data to client applications. It is the client's responsibility to perform any necessary data conversion such as string to numeric. For example, if the client is a Microsoft Excel spreadsheet, the spreadsheet cell should wrap the formula for the DDE reference in a value function call as below; this converts the link text data into a number:

=value(JAM|screen.jam!textdata)

Other methods are specific to each client application.

Disabling Prolifics as a DDE Server

You can disable Prolifics as a server at runtime through sm_dde_server_off. Prolifics continues to maintain all previous links to clients; however, it ignores all client requests that are made after this call.

Prolifics as a DDE Client

When a Prolifics application acts as a DDE client, it imports data into fields from an external server application. Prolifics can request hot, warm, and cold links.

DDE can maintain multiple connections between the Prolifics application and server application; only one connection is allowed between a Prolifics screen and a given server window. Each connection can maintain multiple links.

For example, a Prolifics screen can request a hot link between one of its fields and a cell in an Excel spreadsheet. The request must include the name of the Excel program, the spreadsheet's filename, and the cell identifier. If the request succeeds, a DDE connection is created between the Prolifics screen and the specified spreadsheet; this connection initially consists of the requested link, and can also accommodate other links that the client might request later. Subsequent changes in the server cell data are reported to Prolifics and automatically are written to its linked field.

Enabling Connections

Before Prolifics can connect to a server application, it must be enabled as a DDE client. To enable Prolifics as a client, call sm_dde_client_on or include this setting in the initialization file prol5w32.ini:

DDEClient=on

As a DDE client, Prolifics can request hot, warm, and cold links. For more on link types, refer to page . You can create links in three ways:

• Call one of Prolifics's paste link functions, which get server data from the clipboard.

• Specify server data with one of Prolifics's connect functions.

• Specify server data in the initialization file.

Paste Links

You can paste server data from the Windows clipboard into a Prolifics field on the active screen with one of these Prolifics paste link functions:

• sm_dde_client_paste_link_hot

• sm_dde_client_paste_link_warm

• sm_dde_client_paste_link_cold

These functions take a single argument—the field to get server data. Prolifics gets the actual data and link information from the clipboard—server, topic, and item—and paste links the data into the specified field.

Explicit Links Through Library Functions

Prolifics also provides a set of library functions that explicitly specify the server data required:

• sm_dde_client_connect_hot

• sm_dde_client_connect_warm

• sm_dde_client_connect_cold

These functions take four arguments: the server, topic, item, and target Prolifics field. The format for server, topic, and item arguments is specific to each server application. Refer to the server application's documentation for this information. on page 46-7 shows the syntax used by three widely used Windows applications.

For example, the following JPL statement creates a cold link between a Prolifics client and an Excel spreadsheet:

retval = sm_dde_client_connect_cold \
>         ("Excel","C:\XL\SALES.XLS","R1C2","total")

Refer to Programming Guide for more information about these functions.

Links Specified in Initialization File

You can use the initialization file to create hot links. This lets you specify and edit links for an application without changing the screens themselves. Only hot links are supported from the initialization file.

The initialization file for Prolifics contains a Prolifics DDE section, where you can specify links to server applications as follows:

screenname !

For example, a link to a Quattro Pro spreadsheet might look like this:

salesScrn!totalSales=QPW|C:\MyAcct\Sales.wb1!$A:$A$10..$A$10

The format for server, topic, and item arguments is specific to each server application. Refer to the server application's documentation for this information. Table 46-1 shows the syntax used by three widely used Windows applications.

Processing Link Requests

A link request from a Prolifics application consists of these steps:

1. DDE checks whether the server application is running and the specified topic is open. Both conditions must be true; otherwise, the link request fails.
2. DDE checks whether a connection already exists between the server topic and the requesting Prolifics screen. If none exists, DDE attempts to create one.
3. After DDE verifies or establishes a connection, it creates the specified link—hot, warm, or cold—between the specified Prolifics field and the server item. It then updates the field data according to the link type.

If a link request fails for any reason—for example, because the server application is not running—Prolifics posts an error message.

Updating Data from the Server

Prolifics updates link data according to the link type:

• Hot link—Data is updated on the client whenever it changes on the server.

• Warm link—The server notifies the client of a change in data, but sends new data only at the client's request.

• Cold link—Data is updated only at the client's request. The server does not notify the client of data changes.

If a field has warm or cold link data, the application must explicitly request updates from the server by calling sm_dde_client_request. This function can be called only for fields on the active screen.

When warm link data changes, DDE notifies Prolifics that new data is available from the server. Prolifics then calls a callback function—either its own or one installed by the developer—and passes it the screen name and field name of the link. For information about writing callback routines, refer to sm_dde_install_notify.

DDE does not notify the Prolifics client of any changes in cold link data.

Notes: Because sm_dde_request can be called only for widgets on the active screen, an application that uses warm links should queue notices for data on inactive screens.

Array Data

Prolifics tries to update all occurrences in the array with server data. Data flows into the array starting with the first occurrence. When Prolifics reaches the end of the occurrence or encounters a tab, carriage return, or newline in the server data, it skips to the next occurrence. Prolifics eliminates leading white space—tabs, carriage returns, and new lines—before writing the data. The process ends when there is no more data or the end of the array is reached.

Destroying Links to a DDE Server

When a screen closes, Prolifics destroys all links on that screen. You can also explicitly destroy links on the active screen with sm_dde_client_disconnect.

Disconnecting from a DDE Server

Prolifics maintains its connection to a server application as long as an open screen contains a link to that application. When the last screen containing a link to a server closes, Prolifics breaks the connection.

Execute Transactions

The execute transaction lets a client execute a command on a server. As a client, Prolifics can initiate execute transactions on a server application; as a server, Prolifics can be the recipient of commands issued by a client.

As a DDE client, Prolifics can execute a command on a server with which it already has a connection by calling sm_dde_execute:

sm_dde_execute(server,topic,command);

The server decides whether to execute or ignore the command. You can check the function's return value to determine the outcome of the call.

As a server, Prolifics can receive a command issued by a client. For example, a Quattro Pro spreadsheet might contain this EXECUTE statement:

{EXECUTE B1, "^updateData.jpl"}

Prolifics executes the command string like any control string.

For information about specifying execute transactions from client applications, refer to that application's documentation.

Poke Transactions

A poke transaction lets a client send data to a server. As a client, Prolifics can initiate poke transactions on a server application; as a server, Prolifics can be the recipient of commands issued by a client.

As a DDE client, Prolifics can poke data into a server with which it already has a connection by calling sm_dde_poke:

sm_dde_poke(server,topic,item,data);

The server decides whether to execute or ignore the command. You can check the function's return value to determine the outcome of the call.

As a server, Prolifics can be the target of a poke transaction issued by a client. For information about executing poke transactions from client applications, refer to that application's documentation.