Application Development

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

Panther as a DDE Server

As a DDE server, Panther can export data from a named field to a client application. The client application specifies a DDE service, topic and item. In Panther, 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 Panther field. The request must include the name of the Panther server name, the screen name, and the field name. If the request succeeds, a DDE connection is created between that spreadsheet window and the Panther 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 Panther application, two conditions must be true:

• The Panther application must be running.

• The application must be enabled as a DDE server.

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

DDEServer=on

Clients can create links to a Panther 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 Panther application:

1. Copy data from a Panther 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 Panther screen.

You can also create links to a Panther 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 Panther screen to open as a stacked or sibling window.

The following examples show DDE syntax for two applications:

Microsoft Word

It is the client application's responsibility to connect with a Panther 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 Panther application, it processes it as follows:

1. Finds a match between the specified service and a Panther application that is already running.
2. Checks whether the Panther 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 Panther application exits. Panther maintains links for a screen that is inactive or closed, and resumes data updates when the screen reopens. The client's connection to a Panther screen remains active until all links to the current screen are destroyed.

Panther destroys links only at the request of the client or when the Panther 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 Panther fields:

Hot Links

Panther 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

Panther 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

Panther 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, Panther 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

Panther 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 Panther as a DDE Server

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

Panther as a DDE Client

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

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

For example, a Panther 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 Panther 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 Panther and automatically are written to its linked field.

Enabling Connections

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

DDEClient=on

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

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

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

• Specify server data in the initialization file.

Paste Links

You can paste server data from the Windows clipboard into a Panther field on the active screen with one of these Panther 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. Panther 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

Panther 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 Panther 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 Panther client and an Excel spreadsheet:

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

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 Panther contains a Panther 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 Panther 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 Panther 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 Panther 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—Panther posts an error message.

Updating Data from the Server

Panther 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 Panther that new data is available from the server. Panther 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 Panther client of any changes in cold link data.

Notes: Because sm_dde_client_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

Panther tries to update all occurrences in the array with server data. Data flows into the array starting with the first occurrence. When Panther reaches the end of the occurrence or encounters a tab, carriage return, or newline in the server data, it skips to the next occurrence. Panther 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, Panther 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

Panther 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, Panther breaks the connection.

Execute Transactions

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

As a DDE client, Panther 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, Panther can receive a command issued by a client. For example, a Quattro Pro spreadsheet might contain this EXECUTE statement:

{EXECUTE B1, "^updateData.jpl"}

Panther 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, Panther can initiate poke transactions on a server application; as a server, Panther can be the recipient of commands issued by a client.

As a DDE client, Panther 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, Panther 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.