1-2-3 for OS/2 Support for Presentation Manager Dynamic Data Exchange (DDE)

Lotus Development Corp.

March 1990

This document is a complete description of DDE support in 1-2-3/G for first
customer ship.  Included are a details of how 1-2-3/G attempts to access other
applications, how other applications may access 1-2-3/G data, a description of
the Lotus DDE extensions, and a description of the data formats
supported by 1-2-3/G.

Introduction

This document describes the support included in the first customer ship version
of 1-2-3/G for Presentation Manager Dynamic Data Exchange (DDE).  Included are a
discussion of 1-2-3/G as a DDE Server and as a DDE client.  There are also
sections describing support for the DDE "System Topic", and a detailed
description of the data formats used by 1-2-3/G.

DDE Client Support

Both Worksheet and Graph Tools can serve as DDE Clients.  The user creates a
link using one of two commands:  /EditLinkCreate  or /EditLinkPaste-link.  These
commands are described in detail in the 1-2-3/G Reference.

Worksheet

As a DDE Client, the Worksheet attempts to create links in TEXT Format.

Graph Tool

Most any data that is displayed in a Graph Tool window (e.g. Data Series, Graph
Titles, Legends, etc.) may have its source as a DDE link.  The graph tool
requests links in TEXT Format.

DDE Server Support

The 1-2-3/G DDE Server Application name is Lotus.  The Lotus application
supports the System Topic, as well as a topic for each open Worksheet or Graph
window on the desktop.  The topic name of each window is the name displayed in
the titlebar for that window.

Technical Note: There has been some confusion in the DDE world about the meaning
of multiple ADVISE messages, and of mixed ADVISE and REQUEST messages on a
single DDE conversation.  At FCS, 1-2-3/G supports only one ADVISE or REQUEST
per conversation.  Each ADVISE for a new itemname or format cancels the previous
one.  To support multiple advises of 1-2-3/G, open one conversation per advise.

A poke to 1-2-3/G as a DDE server may be in a different format as an advise on
the same conversation, but the itemname must be the same, or the ADVISE will be
cancelled.

Worksheet

Formats

As a DDE Server, the Worksheet accepts links (renders data) in Rich Text Format,
TEXT Format, or METAFILE Format.  The Worksheet accepts POKE'd data only in TEXT
format.

Item Names

The Worksheet accepts any valid range name or range reference (e.g. A:A1..A:B3).


ADVISE support (hot links)

When "advised" on an item by the client, the worksheet will send updated data
when available (or a NULL data block if the client specified the DDE_FNODATA
flag on the ADVISE).

The Worksheet sends a notification for changes only when recalc is completed.
Thus, Clients of Manual-Recalc sheets will not be notified of value changes
until a recalc is requested by the user.

REQUEST support (warm links)

A Client may request data at any time.  If an "advise" is active, the request
must be on the same itemname as the "advise" or else the advise is cancelled.

POKE support

A DDE Client may "poke" data into a Worksheet.  The Poke may specify any item
name.  If a single cell is specified as the item, and the data contains several
rows and/or columns, then the specified cell will be the upper-left corner of
the table.  TEXT format is supported for POKE.

EXECUTE support

A DDE Client may cause a 1-2-3/G Worksheet to execute a macro by passing the
macro text as the EXECUTE command.

Graph Tool



As a DDE Server, the Graph tool has a single item named 'Graph'.  It is a
picture of the Graph which is available in METAFILE format.

Formats

As a DDE Server, the Graph Tool accepts links in METAFILE Format.  Another
format, Lotus Metafile Size format, is accepted for POKE's into the graph tool
(See: ).

Item Names

The Graph Tool accepts a single itemname, Graph.

ADVISE support (hot links)

When "advised" on an item by the client, the Graph Tool will send updated data
when available (or a NULL data block if the client specified the DDE_FNODATA
flag on the ADVISE).

Note: Since the creation of METAFILE data is time-consuming, we recommend that
Client's not use ADVISE, or use ADVISE with the DDE_FNODATA flag.  In this way
the Client can indicate to the user that the picture has changed, allowing the
user to Refresh the data at his/her convenience.

REQUEST support (warm links)

A Client may request data at any time.

POKE support

A DDE Client may "poke" data into a Graph Tool.  The Poke must specify itemname
Graph, and format Lotus Metafile Size.  The data poked in this way specifies the
size of the rectangle into which the picture should be rendered.  Use of this
feature allows the Client to request that the Graph Tool's automatic layout
algorithm be applied to the data.

EXECUTE support

There are no applicable DDE EXECUTE commands for the 1-2-3/G Graph Tool.

System Topic

Formats

As a DDE Server, the System Topic accepts links in TEXT Format.

Item Names

1-2-3/G supports the recommended itemnames for the System topic.

Sysitems

Returns "SysitemsTopicsFormatsSelection"

Topics

Returns a  separated list of names of each Worksheet and Graph Tool window on
the desktop (as displayed in the titlebar).

Formats

Returns a a  separated list of the formats supported by 1-2-3/G.  The current
text is:
"TEXTMETAFILELinkRich Text FormatLotus Metafile Size"

Selection

Returns the name and current selection of the active tool window in the form
Name!Selection (e.g. SHEET1.WG1!A:A1..A:B5).  This string may be used directly
in the /EditLinkCreate command to establish a link to that selection.

ADVISE support (hot links)

For completeness, DDE ADVISE is accepted by the System Topic; however, the
Client will never receive a notification.  The Client should use DDE REQUEST to
get System topic data.

REQUEST support (warm links)

A Client may request data at any time.  If an "advise" is active, the request
must be on the same itemname as the "advise" or else the advise is cancelled.

POKE support

DDE POKE is not supported by the System Topic.

EXECUTE support

DDE EXECUTE is not supported by the System Topic.

DDE Late Server Support

Late Server support is an extension to DDE developed by Lotus and WordPerfect to
provide tight integration between applications on the Presentation Manager
desktop.  Its purpose is to allow links to be re-established automatically when
the server of the data becomes available (opens on the P/M desktop).

For example, a user is working on a WordPerfect document which includes a hot
link of tabular data from a range on a 1-2-3/G Worksheet.  The user then saves
their work and shuts down.  At a later time, the WordPerfect document is opened
and the user begins to work on it, but 1-2-3/G is not available (or at least the
desired Worksheet is not open), so the hot-link cannot be established.

In this case, it is desirable (if not expected) that if the user opened 1-2-3/G
with the desired worksheet, then the link would automatically be re-established
without any further work on the user's part.  Our Late Server protocol extends
DDE to allow for this kind of tight inter-application integration.

Server Requirements

A Server must let all other applications know whenever a new Topic becomes
available.  This is done using DdeInitiate, where the "Application" name is
CLIENT, and the Topic name is the "App|Topic" string that can be used to link to
the new topic.

For example, when 1-2-3/G opens a Worksheet window named "SHEET.WG1", it
"requests" an Initiate from
Application: CLIENT
on
Topic: Lotus|SHEET.WG1

Client Requirements

The DDE client must save the link information (Application, Topic, Item, and
Format) for each link in its document file, so that when the client document is
re-opened, it can attempt to re-establish the link.  If the link cannot be
re-established, then the client must respond to a DdeInitiate request for an
application named CLIENT.  When it receives an Initiate request on an
application named CLIENT, it should interpret the "topic" name as the
Application/Topic combination that is newly availble as a DDE Server.

The DDE Client may then attempt to Initiate a DDE conversation with the new
server (in the example above, Application = Lotus, Topic = SHEET.WG1).



DDE Formats

This section contains technical information about the DDE formats supported by
1-2-3/G.

TEXT Format

1-2-3/G supports TEXT Format for both incoming and outgoing tabular data.  Text
may describe tabular data by separating columns with a  and separating rows by a
sequence.  The last row of a table need only be  terminated.

The maximum size TEXT block that is handled by 1-2-3/G is 65000 bytes.

Link Format

This is actually a data format used on the Clipboard which is used during the
processing of /EditPasteLink.  The data consists of three consecutive
null-terminated strings, (application, topic, and itemname) which describe the
data that was copied to the clipboard. For example, a copy from a1..b4 of
SHEET.WG1 would result in a Link format block as follows:

"LotusSHEET.WG1A:A1..A:B4"

METAFILE Format

A Metafile is a Presentation Manager internal data structure than cannot be
directly transferred between processes via DDE (although it can via the
Clipboard).

In order to get around this limitation, metafiles are transferred via DDE by
copying the Metafile data from the internal Metafile handle (HMF) into a DDE
data block (using GpiQueryMetafileBits).  The data may exceed 64Kb, in which
case a "huge" allocation is used.

On receipt of data in METAFILE format, the data may be written to disk, and then
loaded using GpiLoadMetafile.

Lotus Metafile Size Format

This format is used to indicate to the Graph Tool the size of the rectangle into
which a Metafile should be rendered.  The form of the data is:

typedef struct {
USHORT ID;    /* id number, must be zero for now */
SIZEL  PageSize;  /* size of page */
ULONG  Units;   /* units of page */
} LINKSIZE;

The ID specifies the revision level of this structure.  Only level 0 is
supported (ID must be zero).  The SIZEL structure, PageSize, consists of two
ULONG values Xsize and Ysize specifying the size of the rectangle into which the
Metafile is to be rendered.  Units indicates the unit of measurement for the
PageSize values (e.g., PU_PELS, PU_TWIPS).


