Copyright: Copyright © ICFM Software
Citation: Copyright of ICFM Software


Contents
Django

Comprehensive DDEML functionality for DELPHI

in a simple to use component

Introduction

Installing Django

Registering your use of Django

Copyright notice

Technical support

Demonstration applications

Adding DDEML client functionality to an application

Adding DDEML server functionality to an application

Adding both DDEML client and server functionality to an application

TDDEMLManager class reference

Special DDEML debugging within Django

Design Limitatations

Version History


Methods grouped by category
TDDEMLManager Class

Methods grouped by category

Applies To

TDDEMLManager

The public methods have been grouped by main category to provide a quick method for accessing the required functionality. In addition the tables below indicate whether a method can be used by a DDEML client or DDEML server application

CONSTRUCTORS / DESTRUCTORS
	Client?	Server?
Create	Yes	Yes
Destroy	Yes	Yes
LINKING TO THE UNDERLYING DDEML API
	Client?	Server?
InitDDEML	Yes	Yes
TerminateDDEML	Yes	Yes
EnableCallBack	Yes	Yes
IsCallbackActive	Yes	Yes
SERVICE DEFINITION
	Client?	Server?
AddService	No	Yes
EnableService	No	Yes
HasService	No	Yes
IsServiceBusy	No	Yes
RegisterService	No	Yes
RemoveService	No	Yes
ServiceCount	No	Yes
ServiceConvCount	No	Yes
ServiceTopicCount	No	Yes
SetServiceStatus	No	Yes
COMMAND DEFINITION
	Client?	Server?
AddCmd	No	Yes
EnableCmd	No	Yes
GetCmdParamCount	No	Yes
GetCmdParamType	No	Yes
RemoveAllCmds	No	Yes
RemoveCmd	No	Yes
ExcludeCmdFromService	No	Yes
RemoveServiceCmdExclusion	No	Yes
RemoveAllServiceCmdExclusions	No	Yes
SERVER INFORMATION
	Client?	Server?
AvailableServerCount	Yes	No
ClearAvailableServerList;	Yes	No
ClearServerFormatList	Yes	No
ClearServerHelpList	Yes	No
ClearServerTopicList	Yes	No
ClearServerSysItemList	Yes	No
FirstAvailableServer	Yes	No
FirstServerFormat	Yes	No
FirstServerTopic	Yes	No
FirstServerTopicFormat	Yes	No
FirstServerTopicItem	Yes	No
FirstServerSysItem	Yes	No
NextAvailableServer	Yes	No
NextServerFormat	Yes	No
NextServerTopic	Yes	No
NextServerSysItem	Yes	No
NextServerTopicItem	Yes	No
NextServerTopicFormat	Yes	No
ServerBusy	Yes	No
ServerExists	Yes	No
ServerFormatCount	Yes	No
ServerHelpMsg	Yes	No
ServerReady	Yes	No
ServerSysItemCount	Yes	No
ServerTopicCount	Yes	No
ServerTopicItemCount	Yes	No
ServerTopicFormatCount	Yes	No
SERVICE SUPPORT
	Client?	Server?
AddToSupportedFormatList	No	Yes
AddToSupportedTopicList	No	Yes
AddWildConnectEntry	No	Yes
AddWildConnectSystemTopics;	No	Yes
ClearSupportedFormatList	No	Yes
ClearSupportedTopicList	No	Yes
IsSystemTopic	Yes	Yes
SetServiceHelpMsg	No	Yes
SERVICE TOPIC SUPPORT
	Client?	Server?
AddToSupportedItemList	No	Yes
ClearSupportedItemList	No	Yes
TopicConvCount	No	Yes
SERVICE ITEM DATA
	Client?	Server?
AppendServiceItemText	No	Yes
ClearServiceItemData	No	Yes
GetServiceItemBitmap	No	Yes
GetServiceItemData	No	Yes
GetServiceItemDataFormat	No	Yes
GetServiceItemDataLen	No	Yes
GetServiceItemInt	No	Yes
GetServiceItemMetaFile	No	Yes
GetServiceItemNumber	No	Yes
GetServiceItemText	No	Yes
ServiceItemHasAdviseLink	No	Yes
ServiceItemHasBinaryData	No	Yes
ServiceItemHasData	No	Yes
ServiceItemHasTextData	No	Yes
RemoveServiceItem	No	Yes
SetServiceItemBitmap	No	Yes
SetServiceItemData	No	Yes
SetServiceItemInt	No	Yes
SetServiceItemMetaFile	No	Yes
SetServiceItemNumber	No	Yes
SetServiceItemStrId	No	Yes
SetServiceItemText	No	Yes
SetServiceItemValue	No	Yes
STARTING/STOPPING CONVERSATIONS
	Client?	Server?
StartConv	Yes	No
StartConvWithAny	Yes	No
EndAllConvs;	Yes	Yes
EndConv	Yes	Yes
CONVERSATION LEVEL
	Client?	Server?
ConvCount	Yes	Yes
ConvHandleToNames	Yes	No
ConvHandleToDDEId	Yes	No
ConvNamesToHandle	Yes	No
ConvNamesToDDEId	Yes	No
EnableConvCallback	Yes	Yes
HasConv	Yes	No
GetConvTimeOut	Yes	No
GetConvComm	Yes	No
HasConvUserHandle	Yes	No
IsConvCallbackActive	Yes	No
RestartConv	Yes	No
SetConvFormat	Yes	No
SetConvTimeOut	Yes	No
SetConvComm	Yes	No
SetConvUserHandle	Yes	No
CLIPBOARD
	Client?	Server?
CopyLinkToClipboard	No	Yes
ClipboardHasPasteLink	Yes	No
StartClipboardPasteLinkConv	Yes	No
TRANSACTION LEVEL
	Client?	Server?
AbandonTrans	Yes	No
Execute	Yes	No
Poke	Yes	No
PokeBitmap	Yes	No
PokeData	Yes	No
PostAdvise	No	Yes
Request	Yes	No
StartAdvise	Yes	No
StopAdvise	Yes	No
TransCount	Yes	No
TransHandle	Yes	No
REQUEST DATA RESULTS
	Client?	Server?
GetClientBitmap	Yes	No
GetClientItemData	Yes	No
GetClientInt	Yes	No
GetClientMetaFile	Yes	No
GetClientNumber	Yes	No
GetClientText	Yes	No


TDDEMLManager Component

Properties	Methods in alphabetical order	Methods grouped by category	Events

Unit

DJANGO

Description

This is a 'one-stop' solution that provides both DDEML client and server functionality in the same single component instance.

There are a number of key design time parameters that need to be set. First set the AutoInit property to TRUE. This automatically connects your application to the underlying DDEML process. Then set the range of DDEML functions that your applications wishes to support by setting the Scope property. For server applications set up the type of exec commands required by editing the ExecCmds property.

Client applications can start a DDEML conversdation using the StartConv method. Once connected a client can push data into a server using the Poke method; or request data from a client using the Request method. Or it can run a server based process  by calling the Execute method.  Warm or hot data advise loops can be established using the StartAdvise method.  A conversation is ended by calling the EndConv method. Multiple wild connect conversations can started by using the StartConvWithAny method.   Individual conversation level parameters can be set for communication type, time out interval and data format.

Client applications are able to query the SYSTEM topic of any server by using a series of high level Django methods. A list of system items supported by the server topic can be retrieved using the FirstServerSysItem/NextServerSysItem methods. The range of topics supported by a server can be retrieved using the FirstServerTopic/NextServerTopic combination.  Similarly a list of items supported by a topic can be retrieved using the FirstServerTopicItem/NextServerTopicItem methods.

Server applications respond to events received from client applications. Django includes a wide range of events to capture and process this messages.  When a client application seeks to start a conversation the server application usse the OnConnectReceived event to control its response. Similarly it uses the OnWildConnectReceived event to respond to any wild connect calls.  Its uses the OnRequestReceived event to trap incoming requests, the OnPokeReceived method for pokes and OnExecuteReceived for execute commands.  It uses a series of events to control system topic requests.  For example when a client application asks the server for its system topic help message the server can use the OnSysHelpReceived event to respond. Alternatively when a client asks for a list of supported topics the server application can  use the OnTopicReceived event to send back a list of topics.

See also

Adding DDEML client functions to an application

Adding DDEML server functions to an application


TDDEMLManager_Properties
TDDEMLManager Properties

Applies To

TDDEMLManager

Properties

About

AllowNullService

AllowNullTopic

AutoInit

CmdFirstCh

CmdLastCh

CmdParamFirstCh

CmdParamLastCh

CmdParamSep

ConvServerNames

ConvTopicNames

DebugFileName

DebugState

DebugStayOnTop

DefaultClipFmt

DefaultComm

DefaultTimeOut

ExecCmds

ExeNameAsService

FailOptions

Inst

InstActive

OneConvPerTopic

Scope

ServiceNames

Services

SkipOptions

WildConnectCount

WildConnectServiceNames

WildConnectTopicNames


About  Property

Applies To

TDDEMLManager

Declaration

PROPERTY About : TAboutInfo READ FAbout;

Description

A design time only property used to show the Django version number


AllowNullService Property

Applies To

TDDEMLManager

Declaration

PROPERTY AllowNullService : BOOLEAN

Description

Used by server applications, this property helps shape how the server responds to Wild connect requests.  If set to TRUE then the server application will process wild connect calls that include a null service name. If set to FALSE the server will automatically reject wild connect calls that include a null service name.


AllowNullTopic Property

Applies To

TDDEMLManager

Declaration

PROPERTY AllowNullTopic : BOOLEAN

Description

Used by server applications, this property helps shape how the server responds to Wild connect requests.  If set to TRUE then the server application will process wild connect calls that include a null topic name. If set to FALSE the server will automatically reject wild connect calls that include a null topic name.  If both AllowNullService’ and ‘AllowNullTopic’ are set to FALSE then the Django component will not respond to any wild connect calls.


AutoInit Property

Applies To

TDDEMLManager

Declaration

PROPERTY AutoInit : BOOLEAN

Description

If set to TRUE the Django component will automatically initialise itself with the underlying DDEML API layer. If this property is set to FALSE, then no DDEML functionality will work until an ‘InitDDEML’ method call is made.


CmdFirstCh Property

Applies To

TDDEMLManager

Declaration

PROPERTY CmdFirstCh : CHAR READ GetCmdFirstCh WRITE SetCmdFirstCh;

Description

Used by server applications, this property defines the starting character of a command string. It is used in conjunction with the ‘CmdLastCh’ property to identify the text range of a command. Normally the start and end characters are set to ‘[‘ and ‘]’. Thus a command string sent by a client application in the form ‘[CLEAR]’ will extracted and processed as the ‘CLEAR’ command.


CmdLastCh Property

Applies To

TDDEMLManager

Declaration

PROPERTY CmdLastCh : CHAR READ GetCmdLastCh WRITE SetCmdLastCh;

Description

Used by server applications, this property defines the last character of a command string. It is used in conjunction with the ‘CmdFirstCh’ property to identify the text range of a command. Normally the start and end characters are set to ‘[‘ and ‘]’. Thus a command string sent by a client application in the form ‘[CLEAR]’ will extracted and processed as the ‘CLEAR’ command.


CmdParamFirstCh Property

Applies To

TDDEMLManager

Declaration

PROPERTY CmdParamFirstCh : CHAR READ GetCmdParamFirstCh WRITE SetCmdParamFirstCh;

Description

Used by server applications, this property defines the first character of a command parameter string. It is used in conjunction with the ‘CmdParamLastCh’ property to identify the text range of a command parameter set. Normally the start and end parameter characters are set to ‘(‘ and ‘)’. Thus a command and parameter string sent by a client application in the form ‘[CLEAR(10,8)]’ will extracted and processed with a parameter set of ‘10,8’.


CmdParamLastCh Property

Applies To

TDDEMLManager

Declaration

PROPERTY CmdParamLastCh : CHAR READ GetCmdParamLastCh WRITE SetCmdParamLastCh;

Description

Used by server applications, this property defines the last character of a command parameter string. It is used in conjunction with the ‘CmdParamFirstCh’ property to identify the text range of a command parameter set. Normally the start and end parameter characters are set to ‘(‘ and ‘)’. Thus a command and parameter string sent by a client application in the form ‘[CLEAR(10,8)]’ will extracted and processed with a parameter set of ‘10,8’.


CmdParamSep Property

Applies To

TDDEMLManager

Declaration

PROPERTY CmdParamSep : CHAR READ GetCmdParamSep WRITE SetCmdParamSep;

Description

Used by server applications, this property defines the delimiter character used to separate parameters in a command parameter string. It is used in conjunction with the ‘CmdParamFirstCh’ and ‘CmdParamLastCh’ properties to identify individual parameters. Normally the parameter delimiter is set a ‘,’ comma character. Thus a command and parameter string sent by a client application in the form ‘[CLEAR(10,8)]’ will extracted and processed as two parameters of ‘10’ and ‘8’.


ConvServerNames Property

Applies To

TDDEMLManager

Declaration

PROPERTY ConvServerNames[Idx : INTEGER] : STRING

Description

Used by client applications, this property is an array of the server names that relate to the current conversation list. The array address is zero based.


ConvTopicNames Property

Example

Applies To

TDDEMLManager

Declaration

PROPERTY ConvTopicNames[Idx : INTEGER] : STRING

Description

Used by client applications, this property is an array of the topic names that relate to the current conversation list. The array address is zero based.


DebugFileName Property

Applies To

TDDEMLManager

Declaration

PROPERTY DebugFileName : STRING

Description

Where the ‘DebugState’ property is set to ‘dbFile’ all debug output to the file name stored in this property.  At the start of each session the process checks to see if a file of the same name already exists. If it does then the existing file is renamed using an new extension of ‘001’. If a file of that extension already exists, then the next available extension number is used.


DebugState Property

Applies To

TDDEMLManager

Declaration

PROPERTY DebugState : TDDEMLDebugState

Description

Django provides a special debug facility to help trace procedural issues within DDEML. This property holds the state of that debug facility. There are three settings :

•	dbNone. No Django procedural debug output is created.

•	dbForm. All Django debug output is sent to a special on screen form used by Django to display the running debug information.

•	dbFile All Django debug output is output to the file name specified in the ‘DebugFile’ property.


DebugStayOnTop Property

Applies To

TDDEMLManager

Declaration

PROPERTY DebugStayOnTop : BOOLEAN

Description

If the Debugstate property is set to ‘dbForm’ , and this property is set to TRUE then the debug form will be assigned on a ‘stay on top’ form behaviour.


DefaultClipFmt Property

Applies To

TDDEMLManager

Declaration

PROPERTY DefaultClipFmt : TDDEMLClipFmtType

Description

This property holds the default data format that is applied to all new conversations.


DefaultComm Property

Applies To

TDDEMLManager

Declaration

PROPERTY DefaultComm : TDDEMLCommType

Description

This property holds the default data communication type (synchronous or asynchronous) that is applied to all new conversations.


DefaultTimeOut Property

Applies To

TDDEMLManager

Declaration

PROPERTY DefaultTimeOut : DOUBLE

Description

This property holds the default time out period in seconds that is applied to all new conversations.


ExecCmds Property

Applies To

TDDEMLManager

Declaration

PROPERTY ExecCmds : TDDEMLCmdsList

Description

Used by server applications, this is a design time only property used to store a server’s exec command strings.

See also:

Editing the exec command list at design time


FailOptions Property

Applies To

TDDEMLManager

Declaration

PROPERTY FailOptions : TDDEMLFailTypeSet

Description

This property represents a set of low level flags that determine the range of options that the underlying DDEML layer will inform the application about, or restrict the application from performing.

•	cbf_Fail_SelfConnections.  If set to TRUE this will prevent the application from starting a conversation with itself.

•	cbf_Fail_Connections.  If set to TRUE stops the application from receiving any connect or wild connect messages.

•	cbf_Fail_Advises.  If set to TRUE this stops the application from receiving any advise loop type transactions.

•	cbf_Fail_Executes.  If set to TRUE this stops the application from receiving any execute command type transactions.

•	cbf_Fail_Pokes. If set to TRUE this stops the application from receiving any poke type transactions.

•	cbf_Fail_Requests. If set to TRUE this stops the application from receiving any request type transactions.

•	cbf_Fail_AllSvrXActions. If set to TRUE this stops the application from receiving any transactions sent by a server.

This property must be set at design time. Any run time changes will have no impact upon the application


Inst Property

Applies To

TDDEMLManager

Declaration

PROPERTY Inst : LONGINT READ FInst;

Description

The instance handle returned by the DDEML API that identifies the application’s own hook into the underlying DDEML API. This handle is set when the application and Django initialises its use of the underlying DDEML layer. This handle should only be used if an application requires direct access to a DDEML API function.


InstActive Property

Applies To

TDDEMLManager

Declaration

PROPERTY InstActive : BOOLEAN

Description

Returns TRUE if the application Inst handle has been initialised.


Scope Property

Applies To

TDDEMLManager

Declaration

PROPERTY Scope : TDDEMLScopeType

Description

Sets the type of DDEML functionality that the component will support. The options are ..

ddeNone	No DDEML functions will be active or work

ddeClientOnly	Provide DDEML client only functionality

DdeServerOnly	Provide DDEML server only functionality

ddeClientAndServer	Provide DDEML client and server functionality

This property must be set at design time. It cannot be changed once the application is running.


ServiceNames Property

Applies To

TDDEMLManager

Declaration

PROPERTY ServiceNames[Idx : INTEGER] : STRING

Description

Used by server applications, to return the names of defined services.


Services Property

Applies To

TDDEMLManager

Declaration

PROPERTY Services : TDDEMLServicesList

Description

This is a design time property used for defining the range and scope of services supported by a server application. It cannot be changed at run time.

See also:

Editing the Services Property list at design time


SkipOptions Property

Applies To

TDDEMLManager

Declaration

PROPERTY SkipOptions : TDDEMLSkipTypeSet

Description

This property represents a set of low level flags that determine the range of options that the underlying DDEML layer will not inform the application about.

•	cbf_Skip_Connect_Confirms.  If TRUE server applications will not receive connect confirm messages for conversations that are about to commence.

•	cbf_Skip_Registrations.  If TRUE the application will not receive a notification when another application registers a new service to the DDEML environment.

•	cbf_Skip_Unregistrations. If TRUE the application will not receive a notification when another application un-registers a service from the DDEML environment.

•	cbf_Skip_Disconnects. If TRUE the application will not receive any disconnect type messages.

•	cbf_Skip_AllNotifications. If set to TRUE this is equivalent to having all of the other flags noted above set to TRUE.

This property must be set at design time. Any run time changes will have no impact upon the application


WildConnectCount Property

Applies To

TDDEMLManager

Declaration

PROPERTY WildConnectCount : INTEGER READ GetWildConnectCount;

Description

Used by server applications, to return the number of entries on its wild connect response list.


WildConnectServiceNames Property

Applies To

TDDEMLManager

Declaration

PROPERTY WildConnectServiceNames[Idx : INTEGER] : STRING

Description

Used by server applications, to return the service name of the ‘Idx’ entry (base 0) on its wild connect response list.


WildConnectTopicNames Property

Applies To

TDDEMLManager

Declaration

PROPERTY WildConnectTopicNames[Idx : INTEGER] : STRING

Description

Used by server applications, to return the topic name of the ‘Idx’ entry (base 0) on its wild connect response list.


TDDEMLManager_Methods
TDDEMLManager Methods

Applies To

TDDEMLManager

Methods in Alphabetical order

AbandonTrans

AddCmd

AddService

AddToSupportedFormatList

AddToSupportedItemList

AddToSupportedTopicList

AddWildConnectEntry

AddWildConnectSystemTopics

AppendServiceItemText

AvailableServerCount

ClearAvailableServerList

ClearServerFormatList

ClearServerHelpList

ClearServerSysItemList

ClearServerTopicList

ClearServiceItemData

ClearSupportedFormatList

ClearSupportedItemList

ClearSupportedTopicList

ClipboardHasPasteLink

ConvCount

ConvHandleToDDEId

ConvHandleToNames

ConvNamesToDDEId

ConvNamesToHandle

CopyLinkToClipboard

Create

Destroy

EnableCallBack

EnableCmd

EnableConvCallback

EnableService

EndAllConvs

EndConv

ExcludeCmdFromService

Execute

FirstAvailableServer

FirstServerFormat

FirstServerSysItem

FirstServerTopic

FirstServerTopicFormat

FirstServerTopicItem

GetClientBitmap

GetClientData

GetClientInt

GetClientMetaFile

GetClientNumber

GetClientText

GetCmdParamCount

GetCmdParamType

GetConvComm

GetConvTimeOut

GetServiceItemBitmap

GetServiceItemData

GetServiceItemDataFormat

GetServiceItemDataLen

GetServiceItemInt

GetServiceItemMetaFile

GetServiceItemNumber

GetServiceItemText

HasConv

HasConvUserHandle

HasService

InitDDEML

IsCallbackActive

IsConvCallbackActive

IsServiceBusy

IsSystemTopic

NextAvailableServer

NextServerFormat

NextServerSysItem

NextServerTopic

NextServerTopicItem

NextServerTopicFormat

Poke

PokeBitmap

PokeData

PostAdvise

RegisterService

RemoveAllCmds

RemoveAllServiceCmdExclusions

RemoveCmd

RemoveService

RemoveServiceCmdExclusion

RemoveServiceItem

Request

RestartConv

ServerBusy

ServerExists

ServerFormatCount

ServerHelpMsg

ServerReady

ServerSysItemCount

ServerTopicCount

ServerTopicFormatCount

ServerTopicItemCount

ServiceCount

ServiceConvCount

ServiceItemHasAdviseLink

ServiceItemHasBinaryData

ServiceItemHasData

ServiceItemHasTextData

ServiceTopicCount

SetConvComm

SetConvFormat

SetConvTimeOut

SetConvUserHandle

SetServiceHelpMsg

SetServiceItemBitmap

SetServiceItemData

SetServiceItemInt

SetServiceItemMetaFile

SetServiceItemNumber

SetServiceItemStrId

SetServiceItemText

SetServiceItemValue

SetServiceStatus

StartAdvise

StartClipboardPasteLinkConv

StartConv

StartConvWithAny

StopAdvise

TerminateDDEML

TopicConvCount

TransCount

TransHandle


Destroy

Applies To

TDDEMLManager

Declaration

DESTRUCTOR Destroy; OVERRIDE;

Description

The standard destructor method. It first calls the protected method ‘DisposeDataMembers’ then the inherited Destroy method.


Create
Create method

Applies To

TDDEMLManager

Declaration

CONSTRUCTOR Create(AOwner : TComponent); OVERRIDE;

Description

The standard constructor method. It calls the inherited Create method and then calls the protected method ‘InitDataMembers’.


AbandonTrans Method

Applies To

TDDEMLManager

Declaration

FUNCTION AbandonTrans(CONST AConvArgs : ARRAY OF CONST; CONST AnItemName : STRING; ATransHandle : LONGINT) : BOOLEAN;

Description

Used by client applications, this method is used to abort an active asynchronous transaction. Both the item name and transaction handle have to be supplied for the process is start. The function returns TRUE if the transaction exists and it is successfully aborted.


AddCmd Method

Applies To

TDDEMLManager

Declaration

PROCEDURE AddCmd(CONST ACmdTitle,ACmdParams : STRING; ACmdEnabled : BOOLEAN);

Description

For server applications this adds a new execute command to the list of predefined commands. The ‘ACmdTitle’ should be a unique text string.

The ‘ACmdParams’ parameter is a text entry that indicators the range and type of parameters expected   Each parameter is represented by a single character.

S	An upper case ‘S’ indicates a mandatory string type parameter

s	A lower case ‘s’ indicates an optional string type parameter

I	An upper case ‘I’ indicates a mandatory integer type parameter

i	A lower case ‘i’ indicates an optional integer type parameter

N	An upper case ‘N’ indicates a mandatory number (decimal) type parameter

n	A lower case ‘n’ indicates an optional number (decimal) type parameter

Lower case parameter types should not appear before uppercase type parameters.

For example an entry of ‘SSI’ would indicate the need for three parameters, the first two of which are text strings, with the third being an INTEGER type. Django uses this parameter list definition to automatically verify any incoming exec command transactions. It rejects any that do not have the required parameter format.

The ‘ACmdEnabled’ parameter indicates whether this command should start as being enabled. A disabled command is not available for client applications.


AddService Method

Applies To

TDDEMLManager

Declaration

PROCEDURE AddService(CONST AService : STRING);

Description

For server applications only. It adds a new service name to the list supported by the Django component. Note that the service is added but not enabled until such time that an ‘EnableService’ method is called.


AddToSupportedFormatList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE AddToSupportedFormatList(CONST AServiceName,ATopicName : STRING;AFormat : TDDEMLClipFmtType);

Description

Used by server applications, this method is part of the processing expected from ‘OnFormatListRequest’ and ‘OnTopicFormatListRequest’ events. The server application should call this method for each data format supported by that server/topic combination.


AddToSupportedItemList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE AddToSupportedItemList(CONST AServiceName,ATopicName,AnItemName : STRING);

Description

Used by server applications, this method is part of the processing expected from the ‘OnItemListRequest’  and ‘OnSysItemListRequest’ events. The server application should call this method for each item supported by that server/topic.


AddToSupportedTopicList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE AddToSupportedTopicList(CONST AServiceName,ATopicName : STRING);

Description

Used by server applications, this method is part of the processing expected from the ‘OnTopicListRequest’ event. The server application should call this method for each topic supported by that server


AddWildConnectEntry Method

Applies To

TDDEMLManager

Declaration

PROCEDURE AddWildConnectEntry(CONST AServiceName,ATopicName : STRING);

Description

Used by server applications, this method is part of the processing expected from the ‘OnWildConnectRequest’ event. The server application should call this method for each server/topic combination that its wants respond with.


AddWildConnectSystemTopics Method

Applies To

TDDEMLManager

Declaration

PROCEDURE AddWildConnectSystemTopics;

Description

Used by server applications, this method is part of the processing expected from the ‘OnWildConnectRequest’ event. This will create a wild connect entry for each service using the SYSTEM topic.


AppendServiceItemText Method

Applies To

TDDEMLManager

Declaration

PROCEDURE AppendServiceItemText(CONST AServiceName,ATopicName,AnItemName,AValue : STRING);

Description

Used by server applications, this method appends text to an existing item entry in the Django internal data buffer.


AvailableServerCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION AvailableServerCount : INTEGER;

Description

Used by client applications to return the number of servers available.


ClearAvailableServerList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearAvailableServerList;

Description

For client applications each time the AvailableServerCount or FirstAvailableServer methods are called Django maintains the results in an internal list. This method clears that list.


ClearServerFormatList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearServerFormatList(CONST AServerName : STRING);

Description

Used by client applications, this clears any previous record the client application might have had of a servers supported data format list.


ClearServerHelpList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearServerHelpList(CONST AServerName : STRING);

Description

Used by client applications, this clears any previous record the client application might have had of a servers SYSTEM topic help message


ClearServerSysItemList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearServerSysItemList(CONST AServerName : STRING);

Description

Used by client applications, this clears any previous record the client application might have had of a servers SYSTEM topic available items list.


ClearServerTopicList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearServerTopicList(CONST AServerName : STRING);

Description

Used by client applications, this clears any previous record the client application might have had of a servers available topic list


ClearServiceItemData Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearServiceItemData(CONST AServiceName,ATopicName,AnItemName : STRING);

Description

Used by server applications, this method clears any data stored against an item from the Django internal data buffer.


ClearSupportedFormatList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearSupportedFormatList(CONST AServiceName,ATopicName : STRING);

Description

Used by server applications, this method is part of the processing expected from ‘OnFormatListRequest’ and ‘OnTopicFormatListRequest’ events. This method will clear down any existing list of format entries. It should be used prior to making the first call to the related ‘AddToSupportedFormatList’ method.


ClearSupportedItemList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearSupportedItemList(CONST AServiceName,ATopicName : STRING);

Description

Used by server applications, this method is part of the processing expected from the ‘OnItemListRequest’  and ‘OnSysItemListRequest’ events. It will clear down any existing list of items. It should be used prior to making the first call to the related ‘AddToSupportedItemList’ method.


ClearSupportedTopicList Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ClearSupportedTopicList(CONST AServiceName : STRING);

Description

Used by server applications, this method is part of the processing expected from the ‘OnTopicListRequest’ event. It should be used prior to making the first call to the related ‘AddToSupportedTopicList’ method.


ClipboardHasPasteLink Method

Applies To

TDDEMLManager

Declaration

FUNCTION ClipboardHasPasteLink(VAR AServerName,ATopicName,AnItemName : STRING) : BOOLEAN;

Description

Used by client applications, this method returns TRUE if the clipboard contains a ‘link’ type clipboard entry. Link type entries are placed by DDEML servers. They contain information on the server and topic that created the clipboard entry. If TRUE the method sets the server name, topic name and item name into the output parameters.


ConvCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ConvCount : INTEGER;

Description

Returns the number of active conversations.


ConvHandleToDDEId Method

Applies To

TDDEMLManager

Declaration

FUNCTION ConvHandleToDDEId(AHandle : INTEGER; VAR ADDEConvId : WORD) : BOOLEAN;

Description

Used by client applications, this coverts a Django conversation handle into the equivalent DDEML API conversation handle. The function returns TRUE if the Django conversation handle is valid.


ConvHandleToNames Method

Applies To

TDDEMLManager

Declaration

FUNCTION ConvHandleToNames(AHandle : INTEGER; VAR AServerName,ATopicName : STRING) : BOOLEAN;

Description

Used by client applications, this coverts a Django conversation handle into the equivalent server/topic names. The function returns TRUE if the Django conversation handle is valid.


ConvNamesToDDEId Method

Applies To

TDDEMLManager

Declaration

FUNCTION ConvNamesToDDEId(CONST AServerName,ATopicName : STRING; VAR ADDEConvId : WORD) : BOOLEAN;

Description

Used by client applications, this takes the pair of server/topic names and returns the equivalent DDEML API conversation handle. The function returns TRUE if a conversation exists with the designated server/topic names. This method may be unreliable if multiple conversations exist to the same target server/topic combination.


ConvNamesToHandle Method

Applies To

TDDEMLManager

Declaration

FUNCTION ConvNamesToHandle(CONST AServerName,ATopicName : STRING; VAR AHandle : INTEGER) : BOOLEAN;

Description

Used by client applications, this takes the pair of server/topic names and returns the equivalent Django conversation handle. The function returns TRUE if a conversation exists with the designated server/topic names. This method may be unreliable if multiple conversations exist to the same target server/topic combination.


CopyLinkToClipboard Method

Applies To

TDDEMLManager

Declaration

FUNCTION CopyLinkToClipboard(CONST AServiceName,ATopicName,AnItemName : STRING;PushData : BOOLEAN) : BOOLEAN;

Description

Used by server applications, this creates a special custom ‘link’ clipboard data format entry on the clipboard. This link format allows other client applications to read the data and have sufficient information to start a DDEML conversation. If ‘PushData’ parameter is set to TRUE then the data related the server/topic/item is also pushed onto the clipboard.


EnableCallBack Method

Applies To

TDDEMLManager

Declaration

PROCEDURE EnableCallBack(OnOff : BOOLEAN);

Description

All underlying DDEML operations use a call back procedure to capture DDEML messages. By default and with the ‘AutoInit’ property set to TRUE Django will automatically establish this callback. In certain situations this callback can be de-activated. This method allows the call back to be set on or off. If set to off the application will not receive any DDEML messages until such time that it re-enabled.


EnableCmd Method

Applies To

TDDEMLManager

Declaration

PROCEDURE EnableCmd(CONST ACmdTitle : STRING; ACmdEnabled : BOOLEAN);

Description

This updates the active status of a designated command. A disabled command cannot be called by client applications


EnableConvCallback Method

Applies To

TDDEMLManager

Declaration

PROCEDURE EnableConvCallback(CONST AConvArgs : ARRAY OF CONST; OnOff : BOOLEAN);

Description

Used by both client and server applications, this method will either enable or disable the call back for a designated conversation. If a conversation’s call back is disabled it will not receive or be able to send any messages to other applications.  In certain extreme situations this method provides a mechanism for server application’s to ignore any client activity.


EnableService Method

Applies To

TDDEMLManager

Declaration

PROCEDURE EnableService(CONST AService : STRING; OnOff : BOOLEAN);

Description

This method allows a pre-defined service to be enabled or disabled.  Django DDEML services can start as inactive. Inactive services are not registered and are thus not visible to client applications.


EndAllConvs Method

Applies To

TDDEMLManager

Declaration

PROCEDURE EndAllConvs;

Description

This will terminate all open conversations.


EndConv Method

Applies To

TDDEMLManager

Declaration

FUNCTION EndConv(CONST AConvArgs : ARRAY OF CONST) : BOOLEAN;

Description

This will terminate a conversation. It will return TRUE if the ‘AConvArgs’ parameter set is valid and that a conversation was terminated.


ExcludeCmdFromService Method

Applies To

TDDEMLManager

Declaration

PROCEDURE ExcludeCmdFromService(CONST AServiceName,ACmdName : STRING);

Description

Sets the command ‘ACmdName’ into the list of commands which the service ‘AServiceName’ does not support.


Execute Method

Applies To

TDDEMLManager

Declaration

FUNCTION Execute(CONST AConvArgs : ARRAY OF CONST;CONST AnExeCmd : STRING) : BOOLEAN;

Description

Used by client applications, this method is used to send a one or more execute commands to the designated server. The methods returns TRUE if all commands were completed successfully.


FirstAvailableServer Method

Applies To

TDDEMLManager

Declaration

FUNCTION FirstAvailableServer(VAR AServerName : STRING) : BOOLEAN;

Description

Used by client applications, this method is part of a ‘First’/Next’ method process for retrieving a list of available servers. The function returns FALSE if no servers are available. It returns TRUE if at least one server is available. The server name is returned in the output parameter ‘AServerName’. To minimise repeat processing Django buffers these First/Next method calls internally. To ensure a fresh search for servers the client application should first call the related method ‘ClearServerAvailableList’.


FirstServerFormat Method

Applies To

TDDEMLManager

Declaration

FUNCTION FirstServerFormat(CONST AnExeName,AServerName : STRING;VAR AFormatName : STRING) : BOOLEAN;

Description

Used by client applications, this method is part of a ‘First’/Next’ method process for retrieving a list of data formats supported by a specific server. The function returns FALSE if no servers are available.

The ‘AnExeName’ parameter is used to hold the DOS path address of the related server application.  The method will review the list of running tasks to see if the task is already running. If it is not found the process will attempt to start the application. This parameter can be set a ‘’ nil string.

The method returns the format name as a text variable. The text variable equates to the TDDEMLClipFmtType type with the ‘cf’ prefix removed. Thus, ‘cfText’ is returned as ‘TEXT’.

The general function ‘TextToClipFormat’ can be used to translate a text entry back to a TDDEMLClipFmtType variable.

To minimise repeat processing Django buffers these First/Next method calls internally. To ensure a fresh search the client application should first call the related method ‘ClearServerFormatList’.


FirstServerSysItem Method

Applies To

TDDEMLManager

Declaration

FUNCTION FirstServerSysItem(CONST AnExeName,AServerName : STRING;VAR AnItemName : STRING) : BOOLEAN;

Description

Used by client applications, this method returns the first item name of items supported by the server’s SYSTEM topic. The function will return TRUE if at least one item is supported. The function returns FALSE if :

•	no servers are available, or

•	the server was not found and the ‘AnExeName’ application could not be launched, or

•	The server does not support this type of enquiry.

This method is used in association with the ‘NextServerSysItem’ method.


FirstServerTopic Method

Applies To

TDDEMLManager

Declaration

FUNCTION FirstServerTopic(CONST AnExeName,AServerName : STRING;VAR ATopicName : STRING) : BOOLEAN;

Description

Used by client applications, this method is part of a ‘First’/Next’ method process for retrieving a list of topics supported by a specific server. The function returns FALSE if

•	no servers are available, or

•	no topics are available, or

•	the server was not found and the ‘AnExeName’ application could not be launched.

The ‘AnExeName’ parameter is used to hold the DOS path address of the related server application.  The method will review the list of running tasks to see if the task is already running. If it is not found the process will attempt to start the application. This parameter can be set a ‘’ nil string.

If found the method returns the first topic name in the output parameter ‘ATopicName’

To minimise repeat processing Django buffers these First/Next method calls internally. To ensure a fresh search the client application should first call the related method ‘ClearServerTopicList’.


FirstServerTopicFormat Method

Applies To

TDDEMLManager

Declaration

FUNCTION FirstServerTopicFormat(CONST AnExeName,AServerName,ATopicName : STRING;VAR AFormatName : STRING) : BOOLEAN;

Description

Used by client applications, this method is similar to ‘FirstServerFormat’, except that it returns the first supported data format for a specified server/topic.


FirstServerTopicItem Method

Applies To

TDDEMLManager

Declaration

FUNCTION FirstServerTopicItem(CONST AnExeName,AServerName,ATopicName : STRING;VAR AnItemName : STRING) : BOOLEAN;

Description

Used by client applications, this method returns the first item name of items supported by the server/topic name combination. The function will return TRUE if at least one item is supported. The function returns FALSE if :

•	no servers are available, or

•	the server was not found and the ‘AnExeName’ application could not be launched, or

•	The ‘ATopicName’ was invalid, or

•	The server does not support this type of enquiry.

This method is used in association with the ‘NextServerTopicItem’ method.


GetClientBitmap Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetClientBitmap(CONST AConvArgs : ARRAY OF CONST;AnItemName : STRING;ATransH : LONGINT;ABitmap : Graphics.TBitmap) : BOOLEAN;

Description

Retrieves into the the bitmap class ‘ABItmap’ the data requested from the conversation identified by the ‘AConvArgs’ parameter. This function is used within the ‘OnRequestResponse’ event handler to retrieve data expected from arequest transaction sent to a server.


GetClientData Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetClientData(CONST AConvArgs : ARRAY OF CONST;AnItemName : STRING;ATransH : LONGINT;ABuffer : POINTER; ALen : LONGINT) : LONGINT;

Description

Retrieves into the the buffer ‘ABuffer’ the data requested from the conversation identified by the ‘AConvArgs’ parameter. This function is used within the ‘OnRequestResponse’ event handler to retrieve data expected from arequest transaction sent to a server. The target buffer used must be instantiated before this method is called.


GetClientInt Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetClientInt(CONST AConvArgs : ARRAY OF CONST;CONST AnItemName : STRING;ATransH          : LONGINT) : INTEGER;

Description

Returns the integer data requested from the conversation identified by the ‘AConvArgs’ parameter. This function is used within the ‘OnRequestResponse’ event handler to retrieve data expected from a request transaction sent to a server.


GetClientMetaFile Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetClientMetaFile(CONST AConvArgs : ARRAY OF CONST;AnItemName : STRING;ATransH : LONGINT;AMetaFile : Graphics.TMetaFile) : BOOLEAN;

Description

Retrieves into the the metafile class ‘AMetafile’ the data requested from the conversation identified by the ‘AConvArgs’ parameter. This function is used within the ‘OnRequestResponse’ event handler to retrieve data expected from arequest transaction sent to a server.


GetClientNumber Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetClientNumber(CONST AConvArgs  : ARRAY OF CONST;CONST AnItemName : STRING;ATransH          : LONGINT) : DOUBLE;

Description

Returns the double data requested from the conversation identified by the ‘AConvArgs’ parameter. This function is used within the ‘OnRequestResponse’ event handler to retrieve data expected from a request transaction sent to a server.


GetClientText Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetClientText(CONST AConvArgs  : ARRAY OF CONST;CONST AnItemName : STRING;ATransH          : LONGINT) : STRING;

Description

Returns the text string data requested from the conversation identified by the ‘AConvArgs’ parameter. This function is used within the ‘OnRequestResponse’ event handler to retrieve data expected from a request transaction sent to a server.  Care should be taken in using this method against long text strings. The ‘OnRequestReponse’ event includes a ‘ADataLen’ parameter that indicates the length of the data in bytes. If this exceeds 255 then use a PChar to store the data, retrieving it with the ‘GetClientData’ method.


GetCmdParamCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetCmdParamCount(CONST ACmdName : STRING) : INTEGER;

Description

Returns the number of parameters (including optional) associated with the command.


GetCmdParamType Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetCmdParamType(CONST ACmdName : STRING; Idx : INTEGER) : INTEGER;

Description

Returns the type of variable associated with the ‘Idx’ th parameter (base 0) of the nominated command.   The value returned equates to one of the ‘vt_XXX’ tytpe parameters defined in the DELPHI ‘system’ unit

    vtInteger  = 0;

    vtBoolean  = 1;

    vtChar     = 2;

    vtExtended = 3;

    vtString   = 4;

    vtPointer  = 5;

    vtPChar    = 6;

    vtObject   = 7;

    vtClass    = 8;

The function returns a value of ‘-1’ if the Idx value is outside the range of valid parameters.


GetConvComm Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetConvComm(CONST AConvArgs : ARRAY OF CONST) : TDDEMLCommType;

Description

Returns the default transaction communication type (either synchronous or asynchronous) for the designated conversation.


GetConvTimeOut Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetConvTimeOut(CONST AConvArgs : ARRAY OF CONST) : DOUBLE;

Description

Returns the default transaction time out period (in seconds) for the designated conversation.


GetServiceItemBitmap Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetServiceItemBitmap(CONST AServiceName,ATopicName,AnItemName : STRING;ABitmap : Graphics.TBitmap) : BOOLEAN;

Description

Used by server applications this method is used to return the bitmap data associated with a particular service/topic/item into the parameter ‘ABitmap’.  The latter must be a valid instance of Tbitmap created prior to calling this method. The function will return TRUE if the item has data and its is of a bitmap format.

For server applications a Poke transaction will have the data associated with that poke set into an internal buffer used by Django. This method can be used to access that buffer.


GetServiceItemData Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetServiceItemData(CONST AServiceName,ATopicName,AnItemName : STRING;ABuffer : POINTER; ALen : LONGINT) : LONGINT;

Description

Used by server applications this method is used to return a designated data type into an open buffer declared in the variable ‘ABuffer’ .  This buffer must be created prior to calling this method. The process will copy up to the number of bytes specified in the parameter ‘ALen’. The function returns the actual number of bytes copied - zero if the item does not exist.

For server applications a Poke transaction will have the data associated with that poke set into an internal buffer used by Django. This method can be used to access that buffer.


GetServiceItemDataFormat Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetServiceItemDataFormat(CONST AServiceName,ATopicName,AnItemName : STRING) : TDDEMLClipFmtType;

Description

Used by server applications, this method returns the data format of the data stored for a designated item.


GetServiceItemDataLen Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetServiceItemDataLen(CONST AServiceName,ATopicName,AnItemName : STRING) : LONGINT;

Description

Used by server applications, this method returns the length in bytes of any data stored against a designated item (or zero if the item does not exist or has no data).


GetServiceItemInt Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetServiceItemInt(CONST AServiceName,ATopicName,AnItemName : STRING) : INTEGER;

Description

Used by both client and server applications, this method returns the designated item’s data as an integer result.


GetServiceItemMetaFile Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetServiceItemMetaFile(CONST AServiceName,ATopicName,AnItemName : STRING;AMetaFile : Graphics.TMetaFile) : BOOLEAN;

Description

Used by both client and server applications, this method moves the designated item’s data into a Meta data class instance. The parameter ‘AMetaFile’ must be a valid instance of TMetaFile created prior to calling this method. The function will return TRUE if the item has data and its is of a meta file format.


GetServiceItemNumber Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetServiceItemNumber(CONST AServiceName,ATopicName,AnItemName : STRING) : DOUBLE;

Description

Used by both client and server applications, this method returns the designated item’s data as an DOUBLE type result.


GetServiceItemText Method

Applies To

TDDEMLManager

Declaration

FUNCTION GetServiceItemText(CONST AServiceName,ATopicName,AnItemName : STRING) : STRING;

Description

Used by both client and server applications, this method returns the designated item’s data as an STRING type result. (or as an NIL ‘’ string if the item does not exist or the data is not of a text type).


HasConv Method

Applies To

TDDEMLManager

Declaration

FUNCTION HasConv(CONST AConvArgs : ARRAY OF CONST) : BOOLEAN;

Description

Returns TRUE if a conversation using the ‘AConvArgs’ identifiers exists.


HasConvUserHandle Method

Applies To

TDDEMLManager

Declaration

FUNCTION HasConvUserHandle(CONST AConvArgs : ARRAY OF CONST; VAR AValue : LONGINT) : BOOLEAN;

Description

Returns TRUE if the designated conversation has a user defined data handle.


HasService Method

Applies To

TDDEMLManager

Declaration

FUNCTION HasService(CONST AServiceName : STRING) : BOOLEAN;

Description

Used by server applications, it returns TRUE if the Django component includes a service of that name.


InitDDEML Method

Applies To

TDDEMLManager

Declaration

FUNCTION InitDDEML : BOOLEAN;

Description

This initiates the application’s use of the underlying DDEML API.  If the ‘AutoInit’ property is set to TRUE then Django will automatically run this method for the application.  If ‘AutoInit’ is set to FALSE then this method must be called specially by the application.

If a Django component has no pre-defined service names it will use by default the name part of the owning application (e.g. from MYAPP.EXE it would use ‘MYAPP’).


IsCallbackActive Method

Applies To

TDDEMLManager

Declaration

FUNCTION IsCallbackActive : BOOLEAN;

Description

Returns TRUE of the underlying DDEML call back is currently active.


IsConvCallbackActive Method

Applies To

TDDEMLManager

Declaration

FUNCTION IsConvCallbackActive(CONST AConvArgs : ARRAY OF CONST) : BOOLEAN;

Description

Returns TRUE if the designated conversation call back is enabled.


IsServiceBusy Method

Applies To

TDDEMLManager

Declaration

FUNCTION IsServiceBusy(CONST AServiceName : STRING) : BOOLEAN;

Description

Used by client applications to test whether a server application service is busy. A busy server is one which is unlikely to be able to respond immediately to a new client initiated transaction.


IsSystemTopic Method

Applies To

TDDEMLManager

Declaration

FUNCTION IsSystemTopic(CONST ATopicName : STRING) : BOOLEAN;

Description

Returns TRUE of the ‘ATopicName’ name is the same as the ‘SYSTEM’ topic.


NextAvailableServer Method

Applies To

TDDEMLManager

Declaration

FUNCTION NextAvailableServer(VAR AServerName : STRING) : BOOLEAN;

Description

Used by client applications, this method is used in association with ‘FirstAvailableServer’ to return a list of available servers. It will return FALSE if the list of available servers has been exhausted.


NextServerFormat Method

Applies To

TDDEMLManager

Declaration

FUNCTION NextServerFormat(CONST AServerName : STRING;VAR AFormatName : STRING) : BOOLEAN;

Description

Used by client applications, this method is used in association with ‘FirstServerFormat’ to return a list of data formats supported by a nominated server. It will return FALSE if the list of formats  has been exhausted.


NextServerSysItem Method

Applies To

TDDEMLManager

Declaration

FUNCTION NextServerSysItem(CONST AServerName : STRING;VAR AnItemName : STRING) : BOOLEAN;

Description

Used by client applications, this method is used in association with ‘FirstServerSysItem’ to return a list of SYSTEM topic items supported by a nominated server. It will return FALSE if the list of items has been exhausted.


NextServerTopic Method

Applies To

TDDEMLManager

Declaration

FUNCTION NextServerTopic(CONST AServerName : STRING;VAR ATopicName : STRING) : BOOLEAN;

Description

Used by client applications, this method is used in association with ‘FirstServerTopic’ to return a list of topics supported by a nominated server. It will return FALSE if the list of topics has been exhausted.


NextServerTopicFormat Method

Applies To

TDDEMLManager

Declaration

FUNCTION NextServerTopicFormat(CONST AServerName,ATopicName : STRING;VAR AFormatName : STRING) : BOOLEAN;

Description

Used by client applications, this method is used in association with ‘FirstServerTopicItem’ to return a list of items supported by a nominated server/topic. It will return FALSE if the list of items has been exhausted.


NextServerTopicItem Method

Applies To

TDDEMLManager

Declaration

FUNCTION NextServerTopicItem(CONST AServerName,ATopicName : STRING;VAR AnItemName : STRING) : BOOLEAN;

Description

Used by client applications, this method is used in association with ‘FirstServerTopicFormat’ to return a list of data formats supported by a nominated server/topic. It will return FALSE if the list has been exhausted.


Poke Method

Applies To

TDDEMLManager

Declaration

FUNCTION Poke(CONST AConvArgs  : ARRAY OF CONST;CONST AnItemName : STRING;CONST ADataArgs  : ARRAY OF CONST) : BOOLEAN;

Description

Used by client applications, this method is used to poke text and numeric data into the server party to the conversation. The methods returns TRUE if poke is accepted by the server.


PokeBitmap Method

Applies To

TDDEMLManager

Declaration

FUNCTION PokeBitmap(CONST AConvArgs  : ARRAY OF CONST;CONST AnItemName : STRING;AFormat : TDDEMLClipFmtType;ABitmap : Graphics.TBitmap) : BOOLEAN;

Description

Used by client applications, this method is used to poke bitmap data into the server party to the conversation. The methods returns TRUE if poke is accepted by the server. The ‘AFormat’ parameter can be set to either ‘cfBitmap’, or’cfDIB’.


PokeData Method

Applies To

TDDEMLManager

Declaration

FUNCTION PokeData(CONST AConvArgs : ARRAY OF CONST;CONST AnItemName : STRING;AFormat : TDDEMLClipFmtType;AData : POINTER;ALen : LONGINT;OwnData : BOOLEAN) : BOOLEAN;

Description

Used by client applications, this method is used to poke data of a non-standard type into the server party to the conversation. The methods returns TRUE if poke is accepted by the server.  The ‘OwnData’ flag is used to indicate who assumes ownership of the ‘AData’ buffer. If set to TRUE Django will assume ownership and dispose the data buffer within its own processes.


PostAdvise Method

Applies To

TDDEMLManager

Declaration

FUNCTION PostAdvise(CONST AServiceName,ATopicName,AnItemName : STRING) : BOOLEAN;

Description

Used by server applications, this method notifies a client application that an item against which an advise loop is in place has a new data


RegisterService Method

Applies To

TDDEMLManager

Declaration

FUNCTION RegisterService(CONST AServiceName : STRING; OnOff : BOOLEAN) : BOOLEAN;

Description

Used by server applications to register a service. This will advise the underlying DDEML layer of the service and its name, making it available to other clients. When a service is enabled most other DDEML aware applications will receive a DDEML message notifying them of the event. Until this registration is made a Django service cannot be seen by other client applications.  If the ‘AutoInit’ property is set to TRUE then all pre-defined (enabled) services are automatically registered by Django.


RemoveAllCmds Method

Applies To

TDDEMLManager

Declaration

PROCEDURE RemoveAllCmds;

Description

Removes all command definitions.


RemoveAllServiceCmdExclusions Method

Applies To

TDDEMLManager

Declaration

PROCEDURE RemoveAllServiceCmdExclusions(CONST AServiceName : STRING);

Description

Removes all commands from the nominated services excluded list, thus making all defined commands available to that service.


RemoveCmd Method

Applies To

TDDEMLManager

Declaration

PROCEDURE RemoveCmd(CONST ACmdName : STRING);

Description

Removes the pre-defined command 'ACmdName' from the list of supported commands.


RemoveService Method

Applies To

TDDEMLManager

Declaration

PROCEDURE RemoveService(CONST AServiceName : STRING);

Description

Used by server applications, this removes a service from the list of services supported by that server.


RemoveServiceCmdExclusion Method

Applies To

TDDEMLManager

Declaration

PROCEDURE RemoveServiceCmdExclusion(CONST AServiceName,ACmdName : STRING);

Description

Removes the command ‘ACmdName’ from the list of commands not supported by the nominated service, making it available to that service.


RemoveServiceItem Method

Applies To

TDDEMLManager

Declaration

FUNCTION RemoveServiceItem(CONST AServiceName,ATopicName,AnItemName : STRING) : BOOLEAN;

Description

Used by both client and server applications, this method removes an item from the Django internal data buffers.


Request Method

Applies To

TDDEMLManager

Declaration

FUNCTION Request(CONST AConvArgs  : ARRAY OF CONST;CONST AnItemName : STRING) : BOOLEAN;

Description

Used by client applications, this method is used to request data from an item supported by the conversation’s target server/topic. The methods returns TRUE if request is accepted by the server.   The ‘OnRequestResponse’ event is used by the client application to pass back the results of the request transaction.


RestartConv Method

Applies To

TDDEMLManager

Declaration

FUNCTION RestartConv(CONST AServerName,ATopicName : STRING) : BOOLEAN;

Description

Used by client applications, this method attempts to restart a terminated conversation. It returns TRUE if the conversation has been re-established. Note: both the Django and DDEML API handles will be different for the restarted conversation.


ServerBusy Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerBusy(CONST AnExeName,AServerName : STRING) : BOOLEAN;

Description

Used by client applications to test whether a server is available and it is ready to accept transactions.


ServerExists Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerExists(CONST AnExeName,AServerName : STRING) : BOOLEAN;

Description

Used by client applications, this method tests to see if a nominated server exists. If not found it will attempt to launch the application specified in the parameter ‘AnExeName’  (this parameter can be set to a ‘’ NIL string).


ServerFormatCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerFormatCount(CONST AnExeName,AServerName : STRING) : INTEGER;

Description

Used by client applications, this method returns a count on the data formats supported by a particular server. If the server is not found this method will attempt to launch the application specified in the parameter ‘AnExeName’  (this parameter can be set to a ‘’ NIL string).


ServerHelpMsg Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerHelpMsg(CONST AnExeName,AServerName,ATopicName : STRING;ABuffer : PChar; ABufferLen : WORD) : WORD;

Description

Used by client applications, this method returns the topic help message for a designated server/topic. If ther ‘ATopicName’ parameter is set to a ‘’ NIL string the method will assume it be a request for the SYSTEM topic. The resulting help message is output into the Pchar buffer parameter ‘ABuffer’. This buffer must be set up in advance of calling this method. The ‘ABufferLen’  parameter indicates buffers size. A help message larger than this will be truncated. If the server is not found this method will attempt to launch the application specified in the parameter ‘AnExeName’  (this parameter can be set to a ‘’ NIL string). The function returns as its result the length of any message returned by the server. Not all DDEML servers support this type of enquiry.


ServerReady Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerReady(CONST AnExeName,AServerName : STRING) : BOOLEAN;

Description

Used by client applications, this method tests to see if a nominated server is currently ready to accept new transactions. If the server is not found this method will attempt to launch the application specified in the parameter ‘AnExeName’  (this parameter can be set to a ‘’ NIL string).


ServerSysItemCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerSysItemCount(CONST AnExeName,AServerName : STRING) : INTEGER;

Description

Used by client applications, this method returns a count of the number of items supported by the nominated server’s SYSTEM topic. If the server is not found this method will attempt to launch the application specified in the parameter ‘AnExeName’  (this parameter can be set to a ‘’ NIL string).


ServerTopicCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerTopicCount(CONST AnExeName,AServerName : STRING) : INTEGER;

Description

Used by client applications, this method returns a count of the number of topics supported by the nominated server. If the server is not found this method will attempt to launch the application specified in the parameter ‘AnExeName’  (this parameter can be set to a ‘’ NIL string).


ServerTopicFormatCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerTopicFormatCount(CONST AnExeName,AServerName,ATopicName : STRING) : INTEGER;

Description

Used by client applications, this method returns a count of the number of data formats supported by the nominated server/topic. If the server is not found this method will attempt to launch the application specified in the parameter ‘AnExeName’  (this parameter can be set to a ‘’ NIL string).


ServerTopicItemCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServerTopicItemCount(CONST AnExeName,AServerName,ATopicName : STRING) : INTEGER;

Description

Used by client applications, this method returns a count of the number of items supported by the nominated server/topic. If the server is not found this method will attempt to launch the application specified in the parameter ‘AnExeName’  (this parameter can be set to a ‘’ NIL string).


ServiceConvCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServiceConvCount(CONST AServiceName : STRING) : WORD;

Description

For server applications, this returns the number of active conversations for a specified service.


ServiceCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServiceCount : INTEGER;

Description

Used by server applications, this returns the number of pre-defined services.


ServiceItemHasAdviseLink Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServiceItemHasAdviseLink(CONST AServiceName,ATopicName,AnItemName : STRING) : BOOLEAN;

Description

Used by server applications, this returns TRUE if the item exists and the advise link type is either ‘warm’ or ‘hot’.


ServiceItemHasBinaryData Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServiceItemHasBinaryData(CONST AServiceName,ATopicName,AnItemName : STRING;VAR AFormat : TDDEMLClipFmtType) : BOOLEAN;

Description

Used by server applications, this method returns TRUE if the Django internal data buffers has data stored against the nominated item and that data is NOT text or numeric data. If TRUE the output parameter ‘AFormat’ is set with the actual data format of the item


ServiceItemHasData Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServiceItemHasData(CONST AServiceName,ATopicName,AnItemName : STRING;VAR AFormat : TDDEMLClipFmtType) : BOOLEAN;

Description

Used by server applications, this method returns TRUE if the Django internal data buffers has data stored against the nominated item. If TRUE the output parameter ‘AFormat’ is set with the actual data format of the item


ServiceItemHasTextData Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServiceItemHasTextData(CONST AServiceName,ATopicName,AnItemName : STRING) : BOOLEAN;

Description

Used by server applications, this method returns TRUE if the Django internal data buffers have data stored against the nominated item and that data is either in text or numeric data.


ServiceTopicCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION ServiceTopicCount(CONST AServiceName : STRING) : WORD;

Description

For server applications, this returns the number of topics in use for a specified service.


SetConvComm Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetConvComm(CONST AConvArgs : ARRAY OF CONST; AComm : TDDEMLCommType);

Description

Used by client applications, sets the communication type (synchronous/asynchonous) for all transactions initiated by the designated conversation.


SetConvFormat Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetConvFormat(CONST AConvArgs : ARRAY OF CONST; AFormat : TDDEMLClipFmtType);

Description

Used by client applications, sets the default data format for all transactions initiated by the designated conversation.


SetConvTimeOut Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetConvTimeOut(CONST AConvArgs : ARRAY OF CONST; ASec : DOUBLE);

Description

Used by client applications, sets the default time out period in seconds for all transactions initiated by the designated conversation.


SetConvUserHandle Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetConvUserHandle(CONST AConvArgs : ARRAY OF CONST; AValue : LONGINT);

Description

Used by client applications, sets a user defined data handle into the designated conversation.


SetServiceHelpMsg Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceHelpMsg(CONST AServiceName : STRING; CONST Args : ARRAY OF CONST);

Description

Used by server applications, this method sets the server’s SYSTEM topic help message into the Django component internal data buffer. It is normally used as part of the processing expected of the ‘OnSysHelpRequest’ event. It can alos be used separately in advance of any data request. The ‘Args’ parameter can be any set of data types. If the ‘Args’ parameter list includes only one entry and that entry is an INTEGER  type then the method assumes this to be a string resource Id, and will attempt to load the text from the application’s string table.


SetServiceItemBitmap Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceItemBitmap(CONST AServiceName,ATopicName,AnItemName : STRING;AFormat : TDDEMLClipFmtType;ABitMap : Graphics.TBitmap);

Description

Used by server applications, this method allows bitmap data to be set into the Django internal data buffers against the nominated server/topic/item. The ‘AFormat’ parameter can be either ‘cfBitmap’, or ‘cfDIB’.


SetServiceItemData Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceItemData(CONST AServiceName,ATopicName,AnItemName : STRING;AFormat : TDDEMLClipFmtType;ABuffer : POINTER;ALen : LONGINT;OwnData : BOOLEAN);

Description

Used by server applications, this method allows data of a non-standard type to be set into the Django internal data buffers against the nominated server/topic/item. The ‘OwnData’ parameter is used to deterjine which process takes ownership of the ‘ABuffer’ data pointer. If TRUE, Django will assume ownership of the data and dispose of it as part of its own internal data management process.


SetServiceItemInt Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceItemInt(CONST AServiceName,ATopicName,AnItemName : STRING;AValue : LONGINT);

Description

Used by server applications, this method allows a INTEGER type value to be set into the Django internal data buffers against the nominated server/topic/item.


SetServiceItemMetaFile Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceItemMetaFile(CONST AServiceName,ATopicName,AnItemName : STRING;AMetaFile : Graphics.TMetaFile);

Description

Used by server applications, this method allows metafile data to be set into the Django internal data buffers against the nominated server/topic/item.


SetServiceItemNumber Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceItemNumber(CONST AServiceName,ATopicName,AnItemName : STRING;AValue : DOUBLE);

Description

Used by server applications, this method allows a DOUBLE type value to be set into the Django internal data buffers against the nominated server/topic/item.


SetServiceItemStrId Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceItemStrId(CONST AServiceName,ATopicName,AnItemName : STRING; AStrId : INTEGER);

Description

Used by server applications, this method allows a string as specified by the identifier ‘AStrId’ to be read from the application’s string resource table and set into the Django internal data buffers against the nominated server/topic/item.


SetServiceItemText Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceItemText(CONST AServiceName,ATopicName,AnItemName,AValue : STRING);

Description

Used by server applications, this method allows a STRING type value to be set into the Django internal data buffers against the nominated server/topic/item.


SetServiceItemValue Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceItemValue(CONST AServiceName,ATopicName,AnItemName : STRING;CONST Args : ARRAY OF CONST);

Description

Used by server applications, this method allows an open ended array of data types to be set into the Django internal data buffers against the nominated server/topic/item. The array of data types is converted and stored as a string.


SetServiceStatus Method

Applies To

TDDEMLManager

Declaration

PROCEDURE SetServiceStatus(CONST AServiceName : STRING; IsBusy : BOOLEAN);

Description

For server applications, this allows a server to be a service as being busy. If a server application expects a particular operation to take a protracted time it should before starting that operation call ‘SetServiceStatus’ as busy and then at the end of the operation reset the service status to FALSE.


StartAdvise Method

Applies To

TDDEMLManager

Declaration

FUNCTION StartAdvise(CONST AConvArgs  : ARRAY OF CONST;CONST AnItemName : STRING;AHotLink         : BOOLEAN;AcknowledgeReq   : BOOLEAN) : BOOLEAN;

Description

Used by client applications, this method is used to start an advise loop against an item supported by conversation’s target server/topic.  An advise loop sets up a call back process, where by if the server application’s data changes the client application receives a notification. If ‘AHotLink’ is set to TRUE a hot advise link to created, if set to FALSE a warm advise link is created. If ‘AcknowledgeReq’ is TRUE the server will wait until an ‘ack’ type transaction is received before  sending the next data change. Use of the ‘ack’ process stops the server from flooding the client with too many irrelevant data change notifications.


StartClipboardPasteLinkConv Method

Applies To

TDDEMLManager

Declaration

FUNCTION StartClipboardPasteLinkConv(VAR AServerName,ATopicName,AnItemName : STRING;VAR AHandle : INTEGER) : BOOLEAN;

Description

Used by client applications, this method returns TRUE if the clipboard contains a ‘link’ type clipboard entry and that a conversation has been established to the source of the link entry.

Link type entries are placed by DDEML servers. They contain information on the server,topic and item that created the clipboard entry.

If TRUE the method sets the server name, topic name and item name into the output parameters and sets the newly created conversation handle into the output parameter ‘AHandle’


StartConv Method

Applies To

TDDEMLManager

Declaration

FUNCTION StartConv(CONST AnExeName,AServerName,ATopicName : STRING;VAR AHandle : INTEGER) : BOOLEAN;

Description

Used by client applications to start a DDEML conversation with the ‘AServerName’ and ‘ATopicName’ combination. If the nominated server is not running, the method will attempt to launch the application specified in he parameter ‘AnExeName’ (this parameter can be a ‘’ NIL string). The function returns TRUE if the conversation was started. If TRUE it returns the Django conversation handle in the output parameter ‘AHandle’.


StartConvWithAny Method

Applies To

TDDEMLManager

Declaration

FUNCTION StartConvWithAny(ATopicName : STRING) : INTEGER;

Description

Used by client applications to start wild connect links to any available servers. The method will attempt to start conversations with all servers that support the declared ‘ATopicName’ topic name This last parameter can be a NIL ‘’ string,  in which case the wild connect process will attempt to connect to all servers and all there topics. How this process is received depends entirely on how a DDEML server is programmed to react. A lot of servers do not respond to wild connect calls, or at least only return a ‘SYSTEM’ topic connection.

The function will return the number of conversations started by this process.


StopAdvise Method

Applies To

TDDEMLManager

Declaration

FUNCTION StopAdvise(CONST AConvArgs  : ARRAY OF CONST;CONST AnItemName : STRING) : BOOLEAN;

Description

Used by client applications, this method cancels an active advise loop.


TerminateDDEML Method

Applies To

TDDEMLManager

Declaration

FUNCTION TerminateDDEML : BOOLEAN;

Description

This terminates an application’s use of the underlying DDEML API. It is automatically called by Django whenever a Django component is about to be disposed.


TopicConvCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION TopicConvCount(CONST AServiceName,ATopicName : STRING) : WORD;

Description

Used by server applications, this method returns a count of the number of active conversations associated with the nominated service/topic.


TransCount Method

Applies To

TDDEMLManager

Declaration

FUNCTION TransCount(CONST AConvArgs : ARRAY OF CONST; CONST AnItemName : STRING) : INTEGER;

Description

Used by client applications, this method returns the number of open transactions associated with a particular item against the designated conversation


TransHandle Method

Applies To

TDDEMLManager

Declaration

FUNCTION TransHandle(CONST AConvArgs : ARRAY OF CONST; CONST AnItemName : STRING; Idx : INTEGER) : LONGINT;

Description

Used by client applications, this method returns the transaction handle of the ‘Idx’  open transactions associated with a particular item against the designated conversation


TDDEMLManager_Events
TDDEMLManager Events

Applies To

TDDEMLManager

Events

OnAdviseStartReceived	OnFormatReceived	OnSysItemReceived

OnAdviseStopReceived	OnHotLinkResponse	OnTopicClosed

OnAsyncResponse	OnItemReceived	OnTopicFormatReceived

OnConnectReceived	OnPokeReceived	OnTopicOpened

OnDisconnecting	OnRequestReceived	OnTopicReceived

OneConvPerTopic	OnRequestResponse	OnWarmLinkResponse

OnError	OnServerDisconnecting	OnWildConnectReceived

OnExecuteReceived	OnSysHelpReceived


OnAdviseStartReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnAdviseStartReceived  : TDDEMLAdvStartEvent

Description

Used by server applications, this event is called whenever a server receives a request from a client application to set an advise loop against one of the server conversation’s items.

TDDEMLAdvStartEvent = PROCEDURE(Sender              : TObject;

                                                                CONST AServiceName,

                                                                ATopicName,

                                                                AnItemName          : STRING;

                                                                AFormat             : TDDEMLClipFmtType;

                                                                VAR Allow           : BOOLEAN) OF OBJECT;

The ‘AServiceName’, ‘ATopicName’ and ‘AnItemName’ parameters identify the target of the advise loop transaction.

The ‘AFormat’ parameter indicates the format of the data the client would want the advise loop to use when dispatching data back to the client.

If the server wishes to support this advise loop it should set the output parameter ‘Allow’ to TRUE. If not it should set the value to FALSE.


OnAdviseStopReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnAdviseStopReceived : TDDEMLSTIEvent

Description

Used by server applications, this event is called whenever a server receives a request from a client application to cancel an advise loop. Use of the event is optional, the advise loop will be cancelled irrespective of whether the event is employed.


OnAsyncResponse Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnAsyncResponse  : TDDEMLAsyncResponseEvent

Description

Used by client applications, this event is used to monitor the results of asynchronous transactions.

TDDEMLAsyncResponseEvent = PROCEDURE(Sender             : TObject;

                                                                                        CONST AServiceName,

                                                                           ATopicName,

                                                                           AnItemName         : STRING;

                                                                           ATransType         : TDDEMLTransType;

                                                                           ATransHandle       : LONGINT;

                                                                           Success            : BOOLEAN) OF OBJECT;

The ‘AServiceName’, ‘ATopicName’, ‘AnItemName’ , ‘ATransType’ and ‘ATransHandle’ parameters identify the target of the asynchronous result. If the parameter ‘Success’ is TRUE then the transaction was completed succesffully.


OnConnectReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnConnectReceived : TDDEMLConnectRequestEvent

Description

Used by server applications, this event is called each time a client application seeks to start a conversation with one of the server’s topics.

TDDEMLConnectReceivedEvent = PROCEDURE(Sender             : TObject;

                                                                            CONST AServiceName : STRING;

                                                                            CONST ATopicName   : STRING;

                                                                            VAR Allow          : BOOLEAN)

Inside the event handler the server application should set the output parameter ‘Allow’ to TRUE if the connect request is valid.

There are a number of useful methods available to help tests the validity of the incoming server/topic names …

•	HasService returns TRUE if the Django component has a service defined of that name

•	IsSystemTopic returns TRUE if the topic parameter is equivalent to ‘SYSTEM’.

•	HasConv can be used to test whether a conversation is already active for the given server/topic combination.

The code example shown below is taken from the SBMP16 demo application :

procedure TMainForm.TheMngrConnectReceived(Sender: TObject;

  const AServiceName, ATopicName: String; var Allow: Boolean);

begin

   Allow := FALSE;

   { allow a connect if the topic is either SYSTEM or PICTURE }

   IF TheMngr.HasService(AServiceName) THEN

      Allow := TheMngr.IsSystemTopic(AtopicName) OR

               (CompareText(ATopicName,'PICTURE') = 0);

end;

This event has to be implemented by the server application. Without it there is almost no way of being able to start conversations (outside of wild connects).


OnDisconnecting Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnDisconnecting : TDDEMLStEvent

Description

This event is called whenever an application receives a message that indicates that the other end of a conversation wishes to terminate the link.

TDDEMLSTEvent = PROCEDURE(Sender     : TObject;

                                                       CONST AServerName,

                                                       ATopicName : STRING) OF OBJECT;

In most situations disconnections are initiated by client applications. Thus, the disconnect event would be triggered within the server application.  To cater for situations where a server terminates a conversation there is a special ‘OnServerDisconnecting’ event available to client applications.


OneConvPerTopic Event
OneConvPerTopic Property

Applies To

TDDEMLManager

Declaration

PROPERTY OneConvPerTopic : BOOLEAN

Description

Used by server applications, this boolean property is used to test whether multiple conversations are allowed against the same server/topic pair. If set to TRUE only one conversation is permitted against a designated server/topic combination.


OnError Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnError : TDDEMLErrorEvent

Description

Any errors that arise within the DDEML processing can be reported back to the form owning the Django component.

TDDEMLErrorEvent = PROCEDURE(Sender     : TObject;

                                                          AMngrError : INTEGER;

                                                          CONST AMsg : STRING) OF OBJECT;

The ‘AMngrError’ number is available from a list of defined errors. The ‘AMsg’ string provides extra contextual information.


OnExecuteReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnExecuteReceived : TDDEMLExecuteEvent

Description

Used by server applications, this event is called each time a client application dispatches an execute command transaction to the server.

TDDEMLExecuteEvent = PROCEDURE(Sender         : TObject;

                                                              CONST AServerName,

                                                              ATopicName     : STRING;

                                                              CONST ACmdName : STRING;

                                                              CONST ACmdParams : ARRAY OF STRING;

                                                              AParamCount    : INTEGER;

                                                              VAR Succeed    : BOOLEAN) OF OBJECT;

The ‘AServerName’ and ‘ATopicName’ parameters identify the conversation.

The ‘ACmdName’ parameter holds the exec command text name.

If the command requires parameters theses are passed using the ‘ACmdParams’ parameter as an array of text strings. Irrepsective of the defined parameter type - string, number, integer - each parameter is passed as a string inside this array.

If the command associated with this event is valid and is processed without error then the application should set the ‘Succeed’ parameter to TRUE.

The code example shown below is taken from the SBMP16 demo application :

procedure TMainForm.TheMngrExecuteReceived(Sender: TObject;

  const AServerName, ATopicName, ACmdName: String;

  const ACmdParams: array of String; AParamCount: Integer;

  var Succeed: Boolean);

begin

   IF TheMngr.HasService(AServerName) THEN

   BEGIN

      IF CompareText(ATopicName,'PICTURE') = 0 THEN

      BEGIN

         IF CompareText(ACmdName,'CLEAR') = 0 THEN

         BEGIN

            Refresh;

            Succeed := TRUE;

         END

      END

   END

end;


OnFormatReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnFormatReceived : TDDEMLSEvent

Description

Used by server applications, this event is called each time a client application asks a server’s SYSTEM topic for a list of data formats supported by the server.

TDDEMLSEvent = PROCEDURE(Sender     : TObject;

                                                     CONST AServerName : STRING) OF OBJECT;

Inside the event handler the server application should call the ‘AddToSupportedFormatList’  method for each data format that it supports.

The code example shown below is taken from the SBMP16 demo application :

procedure TMainForm.TheMngrFormatReceived(Sender: TObject;

  const AServerName: String);

begin

   IF TheMngr.HasService(AServerName) THEN

   BEGIN

      TheMngr.ClearSupportedFormatList(AServerName,'');

      TheMngr.AddToSupportedFormatList(AServerName,'',cfText);

      TheMngr.AddToSupportedFormatList(AServerName,'',cfBitmap);

   END

end;

As this is part of the SYSTEM topic, it is recommended that all server applications support this event.


OnHotLinkResponse Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnHotLinkResponse : TDDEMLDataResponseEvent

Description

Used by client applications, this event is called each time a server sends back changed data  to support a ‘hot’ advise loop.

TDDEMLDataResponseEvent = PROCEDURE(Sender   : TObject;

                                                                         CONST AConvHandle : INTEGER;

                                                                         CONST AServerName,

                                                                         ATopicName,

                                                                         AnItemName : STRING;

                                                                         CONST ATransH  : LONGINT;

                                                                         CONST AFormat : TDDEMLClipFmtType;

                                                                         CONST ADataLen : LONGINT) OF OBJECT;

The ‘AServerName’, ‘ATopicName’, and ‘AnItemName’  parameters identify the hot link.

The code example shown below is taken from the CDEMO16 demo application :

procedure TClientForm1.TheDDEMLMngrHotLinkResponse(Sender: TObject;

  const AConvHandle: Integer; const AServerName, ATopicName,

  AnItemName: String; const ATransH: Longint;

  const AFormat: TDDEMLClipFmtType; const ADataLen: Longint);

begin

     WITH TheDDEMLManager DO

        TheCountLabel.Caption := GetClientText([AConvhandle],AnItemName,ATransH);

end;


OnItemReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnItemReceived : TDDEMLStEvent

Description

Used by server applications, this event is called each time a client application asks a server for a list of items supported by a particular topic.

TDDEMLSTEvent = PROCEDURE(Sender     : TObject;

                                                       CONST AServerName,

                                                       ATopicName : STRING) OF OBJECT;

Inside the event handler the server application should call the ‘AddToSupportedItemList’  method for each data item that it supports. The related ‘ClearSupportedItemList’ method should be used to clear down any existing entries first.

The code example shown below is taken from the SERVGRID demo application :

procedure TSGridForm.TheDDEMLManagerItemReceived(Sender: TObject;

  const AServerName, ATopicName: String);

VAR

   P,R : INTEGER;

   S : STRING;

begin

   { double check that the service is supported }

   IF TheDDEMLManager.HasService(AServerName) THEN

   BEGIN

      P := 1;

      { validate topic }

      WHILE (P <= 4) AND (CompareText('Page'+IntToStr(P),ATopicName) <> 0) DO

         INC(P);

      IF P <= 4 THEN

      BEGIN

         { clear django's list }

         TheDDEMLManager.ClearSupportedItemList(AServerName,ATopicName);

         { add 'Item1','Item2','Item3' etc to the list }

         FOR R := 1 TO 10 DO

         BEGIN

            { get row title }

            S := FGridArray[P].Rows[R].Strings[item_column];

            { add as a supported item }

            WITH TheDDEMLManager DO

               AddToSupportedItemList(AServerName,ATopicName,S);

         END

      END

   END

end;

As part of the SYSTEM topic support, it is suggested that all server applications implement this event.


OnPokeReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnPokeReceived : TDDEMLStiAEvent

Description

Used by server applications, this event is called each time a client application dispatches a poke transaction to the server.

TDDEMLSTIAEvent = PROCEDURE(Sender     : TObject;

                                                          CONST AServerName,

                                                          ATopicName,

                                                          AnItemName : STRING;

                                                          VAR Allow  : BOOLEAN) OF OBJECT;

The ‘AServerName’, ‘ATopicName’, and ‘AnItemName’  parameters identify the poke target.

Inside the event handler the server application can use one of the ‘GetItemXXXX’ methods to retrieve the data sent by the client.

If the  poke is valid the application should set the output parameter ‘Allow’ to TRUE.


OnRequestReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnRequestReceived : TDDEMLReqReceivedEvent

Description

Used by server applications, this event is called each time a client application dispatches a request transaction to the server.

TDDEMLReqReceivedEvent = PROCEDURE(Sender             : TObject;

                                                                       CONST AServiceName,

                                                                       ATopicName,

                                                                       AnItemName         : STRING;

                                                                       AFormat            : TDDEMLClipFmtType;

                                                                       VAR ValidItem      : BOOLEAN) OF OBJECT;

The ‘AServerName’, ‘ATopicName’, and ‘AnItemName’ parameters identify the request target.

Inside the event handler the server application should use one of the ‘SetItemXXXX’ methods to push application data into the Django component. This data is at a later stage dispatched to the client. If the request is valid the application should set the output parameter ‘ValidItem’ to TRUE.

The code example shown below is taken from the SERVGRID demo application :

procedure TSGridForm.TheDDEMLManagerRequestReceived(Sender: TObject;

  const AServiceName, ATopicName, AnItemName: String;

  AFormat: TDDEMLClipFmtType; var ValidItem: Boolean);

VAR

   S : STRING;

   AGrid : TStringGrid;

   R : INTEGER;

begin

   { find the grid from the topic name }

   AGrid := GridFromTopic(ATopicName);

   { valid topic name = assigned grid }

   IF ASSIGNED(AGrid) THEN

   BEGIN

      { convert the item name into a row number }

      R := RowFromItem(AGrid,AnItemName);

      IF R < 0 THEN

      BEGIN

         ValidItem := FALSE;

         TheDDEMLManager.RemoveServiceItem(AServiceName,ATopicName,AnItemName);

      END

      ELSE

      BEGIN

         { get the data value from the grid }

         S := AGrid.Rows[R].Strings[data_column];

         { push it into the Django buffer }

         TheDDEMLManager.SetServiceItemText(AServiceName,ATopicName,AnItemName,S);

      END

   END

end;


OnRequestResponse Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnRequestResponse : TDDEMLDataResponseEvent

Description

Used by client applications, this event is called by Django to notify the application of the data returned by a request transaction.

TDDEMLDataResponseEvent = PROCEDURE(Sender   : TObject;

                                                                         CONST AConvHandle : INTEGER;

                                                                         CONST AServerName,

                                                                         ATopicName,

                                                                         AnItemName : STRING;

                                                                         CONST ATransH  : LONGINT;

                                                                         CONST AFormat : TDDEMLClipFmtType;

                                                                         CONST ADataLen : LONGINT) OF OBJECT;

The ‘AServerName’, ‘ATopicName’, and ‘AnItemName’ parameters identify the request target. For an synchronous transaction the parameter ‘ATransH’ holds the transaction handle.

Inside the event handler the client application can access the data passed back by the server by using one of the ‘GetClientXXX’ data retrieval methods.

The code example shown below is taken from the CLTTEST demo application :

procedure TMainForm.TheDdeMngrRequestResponse(Sender: TObject;

  const AConvHandle: Integer; const AServerName, ATopicName,

  AnItemName: String; const ATransH: Longint;

  const AFormat: TDDEMLClipFmtType; const ADataLen: Longint);

VAR

   S : STRING;

   P : PChar;

begin

   IF ADataLen > 0 THEN

   BEGIN

      { check data format }

      IF AFormat <> cfText THEN

         ShowMessage('This application can only retrieve text data!')

      ELSE

      BEGIN

         { text too long for DELPHI 1 strings? }

         IF ADatalen > 255 THEN

         BEGIN

            { allocate pchat to hold data }

            P := StrAlloc(ADataLen+1);

            { pull data from Django's internal buffers }

            TheDdeMngr.GetClientData([AConvHandle],

                                     AnItemName,

                                     ATransH,P,ADataLen);

            { set into memo for display }

            TheReqResMemo.SetTextBuf(P);

            StrDispose(P);

         END

         ELSE  { no - retrieve as string type }

         BEGIN

            { pull data from Django's internal buffers }

            S := TheDdeMngr.GetClientText([AConvHandle],

                                          AnItemName,ATransH);

            { set into memo for display }

            TheReqResMemo.Lines.Add(S)

         END

      END

   END

   ELSE

      TheReqResMemo.Lines.Add('<NULL>')

end;


OnServerDisconnecting Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnServerDisconnecting : TDDEMLServerDisconnectingEvent

Description

Used by client applications, this event is called in the unusual situation where a server application terminates a conversation.

TDDEMLServerDisconnectingEvent = PROCEDURE(Sender      : TObject;

                                                                                  CONST AServerName,

                                                                                  ATopicName  : STRING;

                                                                                  VAR Restart : BOOLEAN) OF OBJECT;

The ‘AServerName’ and ‘ATopicName’ parameters identify the conversation.

If the client application does not wish the conversation to be terminated then it van attempt to restart the conversation by setting the output parameter ‘ReStart’ to TRUE.


OnSysHelpReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnSysHelpReceived : TDDEMLSEvent

Description

Used by server applications, this event is called each time a client application asks a server’s SYSTEM topic for its help message.

TDDEMLSEvent = PROCEDURE(Sender     : TObject;

                                                     CONST AServerName : STRING) OF OBJECT;

Inside the event handler the server application should call the ’SetServicehelpMsg’  method to place text data into the Django internal data buffers. Once the event has completed Django then moves that data back to the client application.

The code example shown below is taken from the SBMP16 demo application :

procedure TMainForm.TheMngrSysHelpReceived(Sender: TObject;

  const AServerName: String);

VAR

   S : STRING;

begin

   IF TheMngr.HasService(AServerName) THEN

   BEGIN

      S := 'Topics supported : SYSTEM and PICTURE'#13#10;

      S := S + 'Item supported :  IMAGE'#13#10;

      S := S + 'Commands supported : CLEAR';

      TheMngr.SetServiceHelpMsg(AServerName,[S]);

   END

end;

As this is part of the SYSTEM topic, it is recommended that all server applications support this event.


OnSysItemReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnSysItemReceived : TDDEMLSEvent

Description

Used by server applications, this event is called each time a client application asks a server’s SYSTEM topic for a list of the items it supports.

TDDEMLSEvent = PROCEDURE(Sender     : TObject;

                                                    CONST AServerName : STRING) OF OBJECT;

By default Django detects all of the standard system items which the server application has supported through pre-defined event handlers.  Unless the server application supports extra custom SYSTEM topic items there is no need for any response to this event to be defined.

As this is part of the SYSTEM topic, it is recommended that all server applications support this event.


OnTopicClosed Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnTopicClosed : TDDEMLStEvent

Description

Used by server applications, whenever a conversation terminates, and the topic of the just closed conversation has no other open conversations - this event is called.

TDDEMLSTEvent = PROCEDURE(Sender     : TObject;

                                                       CONST AServerName,

                                                       ATopicName : STRING) OF OBJECT;

Inside the event handler the server application can close any external data processes that were associated with the topic.


OnTopicFormatReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnTopicFormatReceived : TDDEMLSTEvent

Description

Used by server applications, this event is called each time a client application asks a server for a list of the data formats supported by a particular topic.

TDDEMLSTEvent = PROCEDURE(Sender     : TObject;

                                                       CONST AServerName,

                                                       ATopicName : STRING) OF OBJECT;

Inside the event handler the server application should call the ‘AddToSupportedFormatList’ method for each data format supported by the server/topic.

It is recommended that all server applications support this event.


OnTopicOpened Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnTopicOpened : TDDEMLStEvent

Description

Used by server applications, this event is called the first time a topic is used in a conversation, just after the conversation has been created.

TDDEMLSTEvent = PROCEDURE(Sender     : TObject;

                                                       CONST AServerName,

                                                       ATopicName : STRING) OF OBJECT;

This allows the server application to open or process some related data file needed to support data access on that topic. For example with MDI applications  the process would new MDI child windows to opened within this event handler.


OnTopicReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnTopicReceived : TDDEMLSEvent

Description

Used by server applications, this event is called each time a client application asks a server’s SYSTEM topic for a list of available topics.

TDDEMLSEvent = PROCEDURE(Sender     : TObject;

                                                     CONST AServerName : STRING) OF OBJECT;

Inside the event handler the server application should call the ‘AddToSupportedTopicList’ method for each topic supported by the server.

The code example shown below is taken from the SBMP16 demo application :

procedure TMainForm.TheMngrTopicReceived(Sender: TObject;

  const AServerName: String);

begin

   IF TheMngr.HasService(AServerName) THEN

   BEGIN

      TheMngr.ClearSupportedTopicList(AServerName);

      TheMngr.AddToSupportedTopicList(AServerName,'SYSTEM');

      TheMngr.AddToSupportedTopicList(AServerName,'PICTURE');

   END

end;

As this is part of the SYSTEM topic, it is recommended that all server applications support this event.


OnWarmLinkResponse Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnWarmLinkResponse : TDDEMLSTIEvent

Description

Used by client applications, this event is called each time a ‘warm’ advise loop notification is received back from the server.

TDDEMLSTIEvent = PROCEDURE(Sender     : TObject;

                                                        CONST AServerName,

                                                        ATopicName,

                                                        AnItemName : STRING) OF OBJECT;

Inside the event handler the client application can use a ‘Request’ method to retrieve the changed data from the server.


OnWildConnectReceived Event

Applies To

TDDEMLManager

Declaration

PROPERTY OnWildConnectReceived : TDDEMLStEvent

Description

Used by server applications, this event is called each time a client application sends out a wild connect call.

Inside the event handler the server application should call the ‘AddWildConnectEntry’ method for each set of service/topics that it wishes to respond to the wild connect call with. Alternatively the server can use the ‘AddWildConnectSystemTopics’ method which will add an entry using just the SYSTEM topic for each services.

The code example shown below is taken from the SBMP16 demo application :

procedure TMainForm.TheMngrWildConnectReceived(Sender: TObject;

  const AServerName, ATopicName: String);

begin

   TheMngr.AddWildConnectSystemTopics;

end;

How and when this event is called depends upon the ‘AllowNullService’ and ‘AllowNullTopic’ propereties are set. If both are set to FALSE a server application will never activate this event.


TDDEMLCommType Type

Unit

DJANGO

Declaration

TDDEMLCommType = (dcASync,dcSync);

Description

Denotes the type of return communication process used by a transaction. Asynchronous transactions are returned by a server at some unspecified future point in time. Synchronous transactions are returned as and when they area called.


TDDEMLScopeType Type

Unit

DJANGO

Declaration

TDDEMLScopeType = (ddeNone,ddeClientOnly,ddeServerOnly,ddeClientAndServer);

Description

Defines the range of DDEML functionality available to the application.


TDDEMLTransType Type

Unit

DJANGO

Declaration

TDDEMLTransType = (	xtypError,

xtypAdvData,

xtypAdvReq,

xtypAdvStart,

xtypAdvStop,

xtypExecute,

xtypConnect,

xtypConnectConfirm,

xtypXACTComplete,

xtypPoke,

xtypRegister,

xtypRequest,

xtypDisconnect,

xtypUnregister,

xtypWildConnect);

Description

Used to identify a transaction type when an aynschronous transaction result is returned to a client application.


Introduction

Django is a DELPHI software component from ICFM Software that offers fully configurable DDEML functionality.

As you have probably seen from the ‘System’ page of the Components toolbar, Borland does supply its own set of DDEML components. Unfortunately the scope and implementation of these components is very limited. It takes a disproportionate amount of work to set up and maintain multiple conversations and data transactions. Maintaining and evolving ongoing DDEML transactions is extremely difficult, and fraught with problems. When DELPHI 2 arrived we could not believe that Borland had carried forward the same poor DDEML components from DELPHI 1. That’s when we decided to offer you a better solution.

In contrast Django offers a ‘one stop’ solution for all your DDEML programming requirements.

Within this single ‘super’ component you get all of these features ….

•	A single component can support multiple DDEML conversations.

•	The component can be configured to act as a DDEML client, or server or both!

•	Individual DDEML conversations can be configured for message type, time outs, and data formats

•	It supports both synchronous and asynchronous DDEML transactions.

•	It uses a fully event based design for managing data movements and responses.

•	Includes support for multiple data formats.

•	Adds easy to use events for supporting the DDEML system ‘info’ functions.

This document acts as both a tutorial and reference manual. It covers the following main topics:

•	How to install Django

•	How to access technical support

•	An explanation of the demonstration programmes

•	How to employ the Django component

•	A tutorial on adding DDEML client functionality to your application.

•	A tutorial on adding DDEML server functionality to your application.

•	A detailed explanation of all public methods and properties

This document includes a wealth of information about how best to use Django. It is not  intended to be a beginners guide on how to use or programme DDEML. That’s just too big a task to tackle here.  However, the tutorial section does cover most of the key actions that an application is likely to require from DDEML.

Django works for both 16 bit DELPHI 1 and 32 bit DELPHI 2.

Note: the shareware version of Django only allows two simultaneous DDE conversations.


Installing Django

We would suggest keeping your Django installation in a separate directory.

Django is supplied via a self-installing EXE. (e.g. DJSW100.EXE). Select this file and run the application.

The setup process will prompt your for an installation directory. Django installs all of its files into this directory. No DLL’s or system files are installed elsewhere.

To add Django to your DELPHI 1 component toolbar perform the normal ‘Install Component’ process, that being …

•	Select the ‘Options/Install Component’ menu item.

•	From the ‘Install Components’ form select the ‘Add’ button.

•	From the ‘Add Module’ form select the Browse button.

•	From the ‘Find File’ form, select the DCU filter, and locate the directory where Django is installed and select the file ‘DJANGO.DCU’. Then select Ok.

•	Select ‘OK’ on the ‘Add Module’ and ‘Install Components’ forms.

By default the install process will install the Django component in the ‘SYSTEM’ page.  By moving the cursor over the Django toolbar icon (as shown above) it display the Django product component name of ‘DDEMLManager’.


Demonstration applications

Django is supplied with five test programs that demonstrate various aspects of the products functionality. The test programs are located in the ‘DEMO’ sub directory. There are five further sub directories  - one for each demo.

The demo programs are provided for both DELPI 1 and DELPHI 2.  All DELPHI 1 projects have a suffix of ‘??????16.DPR’.  All DELPHI 2 projects have a suffix of ‘????32.DPR’.

For shareware users please note that the Django shareware version is limited to supporting no more than two simultaneous DDEML conversations. Any attempt to start a third conversation will fail.

DEMO\CBMP\CBMP16.DPR  and DEMO\CBMP\CBMP32.DPR

CBMP is the DDEML client application that demonstrates how to receive and process bitmap type DDEML data.

It can work as the client end to any DDEML server that supports bitmap or DIB data transfers.

Select the ‘File/Start Conversation’ menu item to start a DDEML link with an available server.

CBMP is specifically designed to work with the SBMP demo. See the next section for further details.

DEMO\SBMP\SBMP16.DPR and DEMO\SBMP\SBMP32.DPR

SBMP16 is a DDEML server application that demonstrates the use of bitmap based server processing.  The application runs as a very simple scribble pad. Move the mouse over the application window area, hold the left key down and drag the mouse around. Lines will appear just like on a scribble pad. This is a very simple pad, it uses a parallel bitmap to retain the drawn image between repainting. To clear an image use the ‘File/Clear’ menu item.

SBMP uses a DDEML server name equivalent to the application name (e.g. SBMP16’ for the 16 bit version. It supports two topics ‘SYSTEM’ and ‘PICTURE’.  The ‘PICTURE’ topic has one item: ‘IMAGE’.   It also supports one execute command ‘CLEAR’ for wiping the scribble pad clean.

The CBMP and SBMP test applications can be used together to demonstrate bitmap related DDEML conversations. This is demonstrated by following the sequence of events:

•	Start the SBMP application

•	Start the CBMP application (by default all the demos are positioned so that client test applications appear on the left side of the screen with all server test applications positioned on the right side).

•	From CBMP select ‘File/Start Conversation’.  Enter a server name of ‘SBMP16’ and a topic name of ‘PICTURE’. (Alternatively you may select the ‘Server’ button and the test app will fill the server combo box with a list of available DDEML servers. Similarly, once you have entered a server name you can select the ‘Topic’ button to retrieve a list of available topics for that server). Select OK to start the link.

•	Within CBMP a new MDI window will open to represent the just started DDEML conversation.

•	Now in SBMP scribble an image in its window

•	From CBMP select ‘Transaction/Request. A dialog appears prompting you to select an item and a format. Enter ‘IMAGE’ into the item combo box and select a ‘bitmap’ format.  On selecting OK, the SBMP image should now appear within the CBMP MDI child window.

•	Return to SBMP and clear the image using ‘File/Clear’. Create some new scribbles.

•	From CBMP select the ‘Transaction/Repeat last Transaction’ menu item and the new image will appear in the CBMP window.

•	To finish close down both apps

A similar link between the two test applications can be auto-started by using SBMP’s ‘Edit/Copy’ menu item and then selecting CBMP’s ‘Edit/Paste’ menu item.  This is an example of a ‘hot’ advise link.  As you add new scribbles to SMP the same image automatically appears within CBMP.

DEMO\CLTTEST\CLTTST16.DPR and DEMO\CLTTEST\CLTTST32.DPR

The ‘CLTTST??.DPR’ project is a comprehensive example of DDEML client functionality. It can be linked to almost any DDEML server. It has functions that allow you to run practically all aspects of DDEML

To connect to a specific DDEML server move to the ‘Servers’ page and enter names into the ‘Server’ and ‘Topic’ combo boxes. Then select the ‘Connect’ button to start the conversation. If the conversation is successfully started it will appear as an entry in the ‘Conversation’ combo list. A warning message box will appear if it failed to start.

The ‘Server’ button can be used to return a list of the available DDEML servers. A message box will appear notifying you of how servers where detected. The server combo box will be populated with those entries. You can select a server by selecting a combo box item.  By choosing the ‘Topic’ button the same type of retrieval will be run for the currently selected server.

CLTTEST also supports wild connects. This is a DDEML process that scatter guns connect requests to all available servers (not all DDEML servers support wild connects, so just because its out there you cannot automatically assume that wild connect will work!). The scope of the wild connect request can be set by selecting one of the four radio buttons on the servers page. Then select the ‘Wild Connect’ button. A message box will appear indicating the number of conversations started, with each conversation appearing an entry in the ‘Conversation’ combo box.

To select an active conversation, choose an item from the conversation combo box on any of the three tabbed pages.

The second tabbed page - System Info - has a number of buttons that equate to the range of options supported by the DDEML System topic.

Most of the functions on this page only work against a SYSTEM topic. So either initiate or select a SYSTEM topic based conversation.

Select an active (system topic based) conversation and then click on each of the buttons in turn. The results of the system info request will appear in the memo box. Not all servers support these system info functions -although they are supposed to! (Quite a few MS products offend here - funny that?!?).  If the feature is not supported than a message box will appear to indicate this.

The third page - Transactions - allows individual pokes, requests, and executes to made against a running conversation.

Enter an item into the ‘Item’ combo box. Alternatively select the ‘Item’ button for the app to retrieve a list of available items (not all servers will support this!)

Now select any one of the item area tabbed pages and run Request, Poke, Execute and Advise transactions. The results of each transaction are displayed in the memo box on each page.

Select the ‘Close’ button at any time to terminate all conversations and exit.

Note: the shareware version of Django is limited to running no more than two simultaneous DDE conversations.

DEMO\SERVGRID\SVGRID16.DPR and DEMO\SERVGRID\SVGRID32.DPR

The SVGrid??.DPR’ project is a very simple DDEML server designed to illustrate facilities within the ‘CLTTTEST’ demo application.

The test application provides a four page interface with a 2 column by 10 data row grid on each page.

It uses a service name of ‘SERVGRID’ and supports five topics: ‘SYSTEM’, ‘PAGE’, ‘PAGE2’, ‘PAGE3’ and ‘PAGE4’.  Each of the ‘Page?’ topics supports ten data items from ‘ITEM1’ to ‘ITEM10’

It also supports three execute commands : ‘ClearGrid’, ‘SetGrid’ and ‘ResetAllGrids’, which are direct equivalents of the test applications own menu items.

Use the CLTTEST test application to connect to SERVGRID. ServGrid supports all of the system info functions.

For example the following sequence of events demonstrates a hot request link between CLTTEST and SERRVGRID:

•	Start CLTTEST

•	Start SERVGRID

•	From CLTTEST connect to SERVGRID using a server name of ‘SERVGRID’  and topic of ‘PAGE1’.

•	Move to the CLTTEST transactions page.  Enter an item name of ‘ITEM1’.

•	Select the ‘Advise’ sub page

•	Make the link type ‘Hot’ and the ‘Advise action ‘Start’. Select the ‘Run’ button. The equivalent data will now appear in the CLTEST memo box.

•	Move to the SERVGRID application. On the Page1 grid change the Item1 value. The new value should appear in the CLTTEST results memo box.

Select the ‘Close’ button on each application to end.

DEMO\MULTI\MCDEMO16.DPR and DEMO\MULTI\MCDEMO32.DPR

DEMO\MULTI\CDEMO16.DPR and DEMO\MULTI\CDEMO32.DPR

DEMO\MULTI\SDEMO16.DPR and DEMO\MULTI\SDEMO32.DPR

The last demo located in the ‘DEMO\MULTI’ sub directory is in fact three small test projects. It demonstrates Django’s ability to manage multiple conversations.

Separately load and compile the three projects: CDEMO16, SDEMO16 and MDDEMO16. Now run the test application ‘MCDEMO16.EXE’.

The MDDEMO16 project is a simple random number generator. The interval edit control determines the interval in seconds at which it generates a new random number from 1 to 5. It then updates the ‘Count’ grid column with the number of times each number has been found. The ‘%’ column shows the number of times each number has appeared in relation to all numbers.

Selecting the ‘Start’ button will initiate the random number generation.  It will also launch five instances of two other applications: 5 instances of CDEMO16.EXE, and 5 instances of ‘SDEMO16.EXE’ (for this to work all three applications must be located in the same directory).

As each CDEMO16.EXE instance is launched it starts a DDEML conversation with MCDEMO16.EXE, with CDEMO16.EXE as the client.  Each instance of CDEMO16.EXE has an instance number in its caption title. Once the conversation has started the client sets up a hot link to the equivalent grid cell number in MCDEMO16.  For example, the third instance of CDEMO16 starts a hot link to the third item in the MCDEMO grid. Each time the 3rd row in the MCDEMO grid is updated by a random number of ‘3’ a DDEML hot link transaction informs the third instance of CDEMO16 of this. CDEMO16 then updates its display to show the number of ‘3’ numbers found.

A similar process occurs for the SDEMO16 application, except that these are servers to MCDEMO16’s client. As each SDEMO16 instance is launched, the MCDEMO16 app starts a new conversation with that instance of SDEMO16. As each random number is generated, MCDEMO16 informs the appropriate instance of SDEMO16 by poking the new value into the server. The server responds by updating its display with the new total.

The upshot of all this is a demonstration where the MCDEMO16 application has Django supporting ten simultaneous DDEML conversations!

You can start and stop the process by using the MCDEMO16 command buttons.  Selecting the MCDEMO16 ‘Close’ button will close all applications

Note: the shareware version of Django is limited to running no more than two simultaneous DDE conversations.  This means that if you compile the demo projects noted above they not work as explained. To circumvent this the shareware package inlcudes three fully enabled EXE’s (CDEMO16.EXE, MCDEMO16.EXE and SDEMO16.EXE) that can be run to demonstrate the full 10 conversation demo. These EXE’s are located under the ‘DEMO’ sub directory.


Registering your use of Django

Django is made available as a shareware product. The shareware version does not include the full source code, though source code for the demo programs is included.  In addition certain features of the shareware version are disabled or limited. Nonetheless the shareware version will give you ample opportunity to judge the value of this product to your own projects.

To obtain the full source code you must first register your use of the product. Please use the Compuserve Shareware Registration service to register your use of this source code library.  Whilst using Compuserve 'GO SWREG' .

Django can be found by searching on the ID '13693'

Alternatively search on the keywords ‘DJANGO’, ‘DELPHI’ and ‘DDEML’.

Shareware registration costs US$195 per user and gains full access to all the source code used within this product. It also includes six months free updates.

For further details please contact ICFM Software via our Compuserve account : [100010,1415].

For details of multi-user/multi-site registration offers please contact ICFM Software.


Technical support

To raise questions, or report bugs and/or enhancement requests contact ....

ICFM Software

London,UK

Compuserve a/c [100010,1415]

Technical support is only available for registered users.

We check our Compuserve account at least twice a day, so in normal situations should receive a response on the same day. A solution to difficult problem may take longer, but at all times we will endeavour to keep you fully informed on progress.


Adding DDEML client functionality to an application

This section outlines the main steps required for adding DDEML client functionality to your project. There are more issues to set for a client as the nature of the client-server relationship is that the client is running a series of procedural actions.

The first task is to define a number of key design time properties.

Name

Set the Django component name to something meaningful.

Scope

The scope property determines the range of DDEML functionality that the component will support. For this example select the ‘ddeClientOnly’ value.

AutoInit

DDEML is a software layer which has to be initialised before any DDEML operations can be performed. This property determines whether this initialisation is performed automatically by the component. Setting ‘AutoInit’ to TRUE will force the component to initialise the DDEML layer shortly after its loaded as part of the main form. If this property is set to FALSE, then no Django functionality will work until the Django ‘InitDDEML’ method is called. For most situations this property should be set to TRUE.

DefaultTimeOut

Most DDEML transactions are governed by a time-out process which will kick in after a pre-declared interval irrespective of whether the transaction has completed.  ‘DefaultTimeOut’ is the value in seconds that will be used as the default time value for all Django initiated actions. By default this is set to 5 seconds.  You should increase this to a larger value if the server link is known to be slow. (This value is only a default. Only methods exist for setting custom values for individual conversations).

Events

Adding DDEML client functionality to your project means adding a number of new core processes to your project. These are based around two main areas …

•	Starting and stopping conversations

•	Sending ‘transactions’ to the server, for retrieving or pushing data to the server.

Django has an event to cover practically all types DDEML activity. Django uses events to capture server initiated tasks and to capture the results of any data requests.

The range of events you will have to establish depends the type of transactions you are sending to the server. The results from each of these transactions is notified to the client application through a series of ‘Response’ events. The table below shows the different events used for each transaction type:

Transaction Type	Related events
Requesting data from server	OnRequestResponse
Sending (poking) data to the server	-
Starting a warm data link	OnWarmLinkResponse OnAsyncResponse
Starting a hot data link	OnHotLinkResponse OnAsyncResponse
Sending a command to the server	-

Further to the table if you are you using asynchronous transaction types then for both POKE and EXECUTE transactions the ‘OnAsyncResponse’ event will be required.

Programming tasks

Most of the work in implementing client side DDEML functionality involves a variety of steps to start conversations, send transactions, and then stop transactions. Django has encapsulated all of this work in a set of high level methods. Added to that you can run multiple conversations all from the same one component.

Information functions

Django includes a range of information functions that allow a client to find out the range available of DDEML servers and topics

The ‘AvailableServerCount’ method returns the number of DDEML servers out there to which it could possible connect.  The two methods shown below can be used to retrieve a named list of those servers.

FUNCTION FirstAvailableServer(VAR AServerName : STRING) : BOOLEAN;

FUNCTION NextAvailableServer(VAR AServerName : STRING) : BOOLEAN;

The CLTTEST demo application includes the following main window procedure for retrieving the list of available servers …

procedure TMainForm.TheServersButtonClick(Sender: TObject);

VAR

   AServerName : STRING;

   Ct : INTEGER;

begin

   Ct := 0;

   WITH TheDdeMngr DO

   BEGIN

      IF FirstAvailableServer(AServerName) THEN

      BEGIN

         TheServerComboBox.ItemIndex := -1;

         TheServerComboBox.Items.Clear;

         REPEAT

            INC(Ct);

            TheServerComboBox.Items.Add(AServerName);

         UNTIL NOT NextAvailableServer(AServerName)

      END;

      IF Ct = 0 THEN

         ShowMessage('No servers found!')

      ELSE

         ShowMessage(IntToStr(Ct)+' servers found');

   END

Similar methods exist for retrieving the list of topics supported by a particular DDEML server

FUNCTION ServerTopicCount(CONST AnExeName,AServerName : STRING) : INTEGER;

FUNCTION FirstServerTopic(CONST AnExeName,AServerName : STRING;

                                              VAR ATopicName : STRING) : BOOLEAN;

FUNCTION NextServerTopic(CONST AServerName : STRING;

                                             VAR ATopicName : STRING) : BOOLEAN;

One of the standards laid down by DDEML is that all servers must support a ‘SYSTEM’. The system topic is used to allow client applications to query the server about its functionality. All of these system information facilities are supoorted by high level Django methods. For instance you can use the ‘ServerHelpMsg’ method to retrieve the help message which all DDEML servers are supposed to support (MS excluded of course!) , or the ‘ServerBusy’ function to tell whether the server is ready to process a transaction.

Starting a conversation

A Django based DDEML conversation can be started in one of three ways  ..

•	Starting a conversation with a specific named server/topic combination

•	Firing off a Wild Connect connection request, which will start conversations with all and sundry servers that support wild connects.

•	By using the Edit/Paste method to retrieve data posted into the clipboard by a DDEML server application.

To start a specific conversation use the ‘StartConv’ method. This requires at least one parameter a server name, though normally you would supply both a server and topic name (supplying just the server name is equivalent to sending a wild connect request).

FUNCTION StartConv(CONST AnExeName,

                                    AServerName,

                                    ATopicName : STRING;

                                    VAR AHandle : INTEGER) : BOOLEAN;

The ‘StartConv’ method returns TRUE if the conversation has commenced. It also returns an integer handle which can be used to identify a specific conversation. This handle is not the same as the hCONV handle used by low level DDEML functions. It is a handle used and maintained by Django.

As Django can support multiple simultaneous conversations something is required to identify a specific conversation. All conversation level methods use an open parameter type to allow you to choose the type of unique conversation parameter that you want to use. This can be either …

•	The integer handle returned by the StartConv method, or

•	The server and topic name conversation pair of strings.

Django includes a record structure for you to use to retain these values …

TYPE

   TConvParamRec = RECORD

      Server : STRING;

      Topic  : STRING;

      Handle : INTEGER;

   END;

Wild connections allow a client app to start up multiple conversations with any number of servers. Django manages this through the ‘StartConvWithAny’ method

FUNCTION StartConvWithAny(ATopicName : STRING) : INTEGER;

The method function returns the number of conversations started. The ‘ATopicName’ parameter is optional - a ‘’ nil string value is valid.  Not all DDEML servers react to wild connect calls in the same way. A DDEML server is not obliged to respond to a wild connect call.

Lastly Microsoft has introduced a custom clipboard format implemented in quite a few applications that allows an entry on the clipboard to act as the agent for a new DDEML conversation. This clipboard entry includes details about the source server and topic.  When a DDEML capable client application pastes this data into its area it can read the clipboard data and use these as the parameters to start a new conversation.  Django has implemented this in two high level methods. Firstly the ‘ClipboardHasPasteLink’ function returns TRUE if the clipboard contains a valid entry. Secondly the ‘StartClipboardPasteLinkConv’ method can be used to start a new DDEML conversation from the clipboard data.

The SYSTEM topic

Each DDEML server is supposed to support a special topic called the ‘SYSTEM’ topic. This system topic is used to find out information about the structure and scope of the DDEML server.

Django includes a set high level methods for querying all of the standard SYSTEM topic entries.

These include (the related Django methods are shown in parentheses) …

•	Server help message (ServerHelpMsg)

•	Topic supported by server (FirstServerTopic/NextServerTopic)

•	Data formats supported by server (FirstServerFormat/NextServerFormat)

•	Data formats supported by specific server/topic combination (FirstServerTopicFormat/NextServerTopicFormat)

•	Items supported by the system topic (FirstServerSysItem/NextServerSysItem)

•	Items supported by a specific server/topic (FirstServerTopicItem/NextServerTopicItem)

•	Server is busy (ServerBusy/ServerReady)

Again, although DDEML servers are supposed to support all of the above, in practice some of more well known applications do not.

Poking data

When a DDEML conversation is established the client application can poke (or send) data to the server using the poke transaction type. Django supports a number of high level poke related methods : ‘Poke’ for sending data in a text format; ‘PokeBitmap’ for sending bitmap data; and ‘PokeData’ for sending a custom data type.

To send text or numbers to the server use the ‘Poke’ method …

FUNCTION Poke(CONST AConvArgs  : ARRAY OF CONST;

                            CONST AnItemName : STRING;

                            CONST ADataArgs  : ARRAY OF CONST) : BOOLEAN;

The first parameter defines the conversation identifier. This can either be the conversation integer handle returned by the ‘StartConv’ method, or the server/topic strings

IF TheMngr.Poke([AHandle],’R1C1’,[‘Sample test’]) THEN ….

IF TheMngr.Poke([‘EXCEL’,’SHEET1’],’R1C1’,[40.45]) THEN ….

Both the examples shown above are valid uses of the ‘AConvArgs’ parameter. In both cases the parameter must be enclosed by the ‘[‘ ‘]’square brackets.

The data pushed out using the ‘ADataArgs’ parameter can be one or more entries in an open array that takes almost all types of variable.  In the example below ‘Age’ is presumed to be an integer variable.

IF TheMngr.Poke([‘EXCEL’,’SHEET1’],’R1C1’,[‘I am ’,Age,’ years old’]) THEN ….

Astring = ‘I am ’;

Age := 21;

Bstring = ‘ years old - really!’;

IF TheMngr.Poke([‘EXCEL’,’SHEET1’],’R1C1’,[AStr,Age,BStr]) THEN ….

To poke bitmap to a server use the ‘PokeBitmap’ method ….

FUNCTION PokeBitmap(CONST AConvArgs  : ARRAY OF CONST;

                                       CONST AnItemName : STRING;

                                       AFormat : TDDEMLClipFmtType;

                                       ABitmap : Graphics.TBitmap) : BOOLEAN;

The ‘AFormat’ parameter can be set to either ‘cfBitmap’ or ‘cfDIB’ .

Any other form of data can be sent using the generic ‘PokeData’ method.

FUNCTION PokeData(CONST AConvArgs : ARRAY OF CONST;

                                   CONST AnItemName : STRING;

                                   AFormat : TDDEMLClipFmtType;

                                   AData : POINTER;

                                   ALen : LONGINT;

                                   OwnData : BOOLEAN) : BOOLEAN;

The ‘AData’ parameter is a generic pointer to some block of memory holding the data to be transferred to the server. The ‘OwnData’ flag is used to indicate whether Django should just take ownership of the data pointer (i.e. dispose of the data once the process is complete).

All Poke operations return TRUE if the server accepted the data. It will return false if the server refused the transaction or no result was returned within the declared time out period.

Requesting data

The opposite to a Poke is a Request. A request transaction retrieves data from a DDEML server.

Django uses a ‘Request’ method to retrieve data. The data itself is passed back using the ‘OnRequestResponse’ event above.

FUNCTION Request(CONST AConvArgs  : ARRAY OF CONST;

                                 CONST AnItemName : STRING) : BOOLEAN;

A Request method returns TRUE if it was accepted by the server. IF returns FALSE if it was not accepted by the server or it timed out.

A request method has the data sent via the ‘OnRequestResponse’ event.  If you do not define this event you will never receive any data! This type of indirection is used because DDEML can move a wide variety of different data types.

The ‘CLTTEST’ demo application includes an ‘OnRequestResponse’ event, as shown below:

procedure TMainForm.TheDdeMngrRequestResponse(Sender: TObject;

  const AConvHandle: Integer; const AServerName, ATopicName,

  AnItemName: String; const ATransH: Longint;

  const AFormat: TDDEMLClipFmtType; const ADataLen: Longint);

begin

   IF ADataLen > 0 THEN

      TheReqResMemo.Lines.Add(TheDdeMngr.GetClientText([AConvHandle],AnItemName,ATransH))

   ELSE

      TheReqResMemo.Lines.Add('<NULL>')

end;

Django includes a set of ‘GetClientXXX’ functions for retrieving request related data. Inside the event handler the client application can call a specific ‘GetClientXXX’ function according to the type of data requested. The table below summarises the appropriate method to use:

Data type requested	Related ‘GetClientXXX’ function
Bitmap	GetClientBitmap
Large strings ( > 255 chars)	GetClientData
Integer/Longint	GetClientInt
Meta file	GetClientMetaFile
Double	GetClientNumber
Pascal String	GetClientText
Other data type	GetClientData
Sending an Exec command

DDEML uses Poke and Request transaction types to move data. It uses a ‘exec command’ transaction type to initiate some DDEML server based function. In most cases a DDEML server will include a range of DDEML exec commands that mirror either its menu structure or general functionality. There is no formal standard for how exec commands are formatted. Each server application will have it own individual way of doing things.

Generally an exec command is passed as a formatted text string, with individual commands set within square brackets, like ‘[CLEAR]’.  Parameters to a command are normally set in parentheses within the square brackets, like  ‘[CLEAR(10,10)]’.  Commands can be concatenated together in a sequence, like ‘[CLEAR(10,10)][SET(5,6,7)]’.

Django uses the ‘Execute’ method to forward commands.

FUNCTION Execute(CONST AConvArgs : ARRAY OF CONST;

                                 CONST AnExeCmd : STRING) : BOOLEAN;

The ‘Execute’ method will return TRUE if all elements of the command string were accepted and processed by the server.

Stopping a conversation

An active conversation can be terminated using the ‘EndConv’ method.  All active conversations can be end using the ‘EndAllConvs’ method.

It is normally the client’s job to start and stop conversations. If a server for some reason stops a conversation then it often disrupts the processing flow. To that end Django has a special event that client applications can use to capture such situations. The ‘OnServerDisconnecting’ event is called whenever a server initiates a conversation termination.

Restarting a conversation

A client can attempt to restart a stopped conversation by using the ‘RestartConv’ method.

Starting multiple conversations

Django can support multiple simultaneous conversations.

IF TheMngr.StartConv(‘’,’EXCEL’,’SHEET1’,Handle1) THEN …..

IF TheMngr.StartConv(‘’,’EXCEL’,’SHEET2’,Handle2) THEN …..

IF TheMngr.StartConv(‘’,’EXCEL’,’SHEET3’,Handle3) THEN …..

The client application must use the server/topic string combination or the unique handle returned by ‘StartConv’ to select a particular conversation. Some servers support multiple conversations into the same server/topic combination. In this case you would have to use the handle as a means of identifying the required conversation.

There area set of methods for translating handles to server/topic names and vice-versa

FUNCTION ConvHandleToNames(AHandle : INTEGER;

                                                       VAR AServerName,

                                                       ATopicName : STRING) : BOOLEAN;

FUNCTION ConvHandleToDDEId(AHandle : INTEGER;

                                                      VAR ADDEConvId : WORD) : BOOLEAN;

FUNCTION ConvNamesToHandle(CONST AServerName,

                                                       ATopicName : STRING;

                                                       VAR AHandle : INTEGER) : BOOLEAN;

FUNCTION ConvNamesToDDEId(CONST AServerName,

                                                      ATopicName : STRING;

                                                      VAR ADDEConvId : WORD) : BOOLEAN;

The ‘ADDEConvId’ parameter type shown above is the low level DDEML conversation handle used by DDEML API functions


Adding DDEML server functionality to an application

Using Django to define DDEML server functionality is a quick and rapid process. There is less procedural programming work here, as by and large the task is associated with defining a set of reactions to pre-defined access points.

Design time issues

Properties

Name

Select a name appropriate to the Django component.

Scope

Set the scope to ‘ddeServerOnly’.

Services

Each server application identifies itself through its server name. This can be different to the application name. Most DDEML servers usually only offer one service, but you can support multiple service names if you so require.  Different service names can be used to segregate different types of functionality or access to types of data.

By default if no entry is defined here then Django will create a service using the name of the application, e.g. ‘MYAPP’ service from ‘MYAPP.EXE’.

To define a specific service name select the ‘Services’ line on the Object Inspector. It will open a custom form that allows for definition of single or multiple service names.

To add a defined service name, enter an alphanumeric name in the ‘Name’ edit control and then select the ‘Add’ button. An entry will appear in the ‘Defined’ list box. The start up status of a service can be set using the ‘Enabled at start’ check box. To change a service name use the list box cursor to highlight the required item. The name will appear in the ‘Name’ edit control. Edit this text and then select the ‘Update’ button.  To remove a service name highlight the required item in the ‘Defined’ list box and then select the ‘Delete’ button.

On the right side of the form there are two list boxes used to control the range of exec commands that a service can employ. Where a server application uses more one service, it might be important to restrict certain exec commands to particular services.  By default this form lists for the currently defined service all of the available commands in the ‘Valid’ list box.  To reduce this scope select items from the valid list box and using the arrow keys move them into the ‘Invalid’ list box. Any command names appearing in the ‘Invalid’ list box will not be available for the selected service.

Once all definitions are complete, select the ‘OK’ button. The Object Inspector form will display the number of services defined.

AutoInit

Setting this to TRUE will have Django auto initiate the underlying DDEML functionality. If this is set to FALSE then no Django functionality can be used until an ‘InitDDEML’ method is called. This property is normally set to TRUE.

DefaultTimeOut

This property defines the default time period in seconds for transactions to complete.

ExecCmds

A service can support a range of commands that equate to functions within its own applications. These commands can be called by clients.  This property is supported by a form that allows set ofg commands to be defined. To activate the form highlight the ‘ExecCmds’ property in the Object Inspector. A double click on this line opens the command definition form ….

The command definition form provides a grid into which the command definitions and there parameters can be set.

The ‘Command Name’ column defines the name that the client will use to activate the command. The ‘Param Types’ column is used to define the range and type of parameters required for each command. This column can take any number of parameter entries. Each parameter is represented by a single character.

S	An upper case ‘S’ indicates a mandatory string type parameter

s	A lower case ‘s’ indicates an optional string type parameter

I	An upper case ‘I’ indicates a mandatory integer type parameter

i	A lower case ‘i’ indicates an optional integer type parameter

N	An upper case ‘N’ indicates a mandatory number (decimal) type parameter

n	A lower case ‘n’ indicates an optional number (decimal) type parameter

Lower case parameter types should not appear before uppercase type parameters.

Django uses this parameter list definition to automatically verify any incoming exec command transactions. It rejects any that do not have the required parameter format.

The third column ‘Active?’ is used to define whether a command is active (available) at the start of a session.  A command can be used by a client if it is inactive.

The sample screen shown above illustrates the exec command settings for the SERVGRID demo application.

Having defined all the required commands, select the ‘OK’ button. The Object Inspector line will display an indication of the number of defined commands.

Events

Having established the structure (services and commands) the next stage is to set up a series of events to respond to incoming client requests.

Almost all of the server related events use a ‘OnxxxxxReceived’  naming convention.

The table below summaries the server specific events and their use:

Purpose	Event name
Receiving a start new conversation ‘connect’ message from a client application	OnConnectReceived
Receiving a wild connect call from a client application	OnWildConnectReceived
Receiving a conversation about to terminate message from a client application	OnDisconnecting
Receiving a ‘Poke’ transaction from a client application	OnPokeReceived
Receiving a Request transaction from a client application	OnRequestReceived
Receiving an execute command transaction from a client application	OnExecuteReceived
Responding to a start new advise loop transaction sent bya client application	OnAdviseStartReceived
Responding to a stop existing advise loop transaction sent by a client application	OnAdviseStopReceived
Receiving a request from a client application for its system help message	OnSyshelpReceived
Receiving a request from a client application for the list of items supported by the system topic	OnSysItemReceived
Receiving a request from a client application for a list of supported topics	OnTopicReceived
Receiving a request from a client application for a list of supported data formats for all topics	OnFormatReceived
Receiving a request from a client application for a list of data formats supported by a specific topic	OnTopicFormatReceived
Receiving a request from a client application fro a list of items supported by a specific topic	OnItemReceived

Detailed explanations on how to employ each event are given in the reference section of this document.

Programming activities

Beyond the data property and event setting issues described above there is very little else for Django server applications to worry about.


Version History

Version 1.0

Supporting 16 bit DELPHI is launched in November 1996.


Adding both DDEML client and server functionality to an application

To establish a project that acts as both DDEML client and server simply change the ‘Scope’ property to use the ‘ddeClientAndServer’, and make sure all of the steps outlined the Separate clienta nd server tutorial sections are implemented. It’s as simple as that!

Adding Client functionality

Adding server functionality


Copyright notice

The use of this product indicates your understanding and acceptance of the following terms and conditions. This license shall supersede any verbal, or prior verbal or written, statement or agreement to the contrary.

If you do not understand or accept these terms, or your local regulations prohibit "after sale" license agreements or limited disclaimers, you must cease and desist using this product immediately. No contract is assumed unless a signed copy of this document has been returned to, and acknowledged by,  ICFM Software. Copyright laws supersede all local regulations.

Copyright

This product (in whole or in part, including all files, data, and documentation, from here on referred to as “Product”) is © Copyright 1996 ICFM Software, all rights reserved, and is protected by UK copyright laws, international treaties and all other applicable national or international laws. This product may not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine readable form, without prior consent in writing, from ICFM Software and according to all applicable laws. The sole owner of this product is ICFM Software.

Liability disclaimer

This product and/or license is provided exclusively by ICFM Software, on an “as is” basis,  without any representation or warranty of any kind, either express or implied, including without limitation any representations or endorsements regarding the use of, the results of, or performance of the product, its appropriateness, accuracy, reliability, or correctness. The entire risk as to the use of this product is assumed by the user and/or licensee. ICFM Software do not assume liability for the use of this product beyond the original purchase price. In no event will ICFM Software be liable for additional direct or indirect damages including any lost profits, lost savings, or other incidental or consequential damages arising from any defects, or the use or inability to use this product, even if ICFM Software have been advised of the possibility of such damages.

Restrictions

You may not use, copy, modify, translate, or transfer the product or any copy except as expressly defined in this agreement. You may not attempt to unlock or bypass any copy-protection or authentication algorithm utilized by this product. You may not remove or modify any copyright notice, nor any “about” dialog or the method by which it may be invoked.

Operating license

You have the non-exclusive right to use the product only by a single person, on a single computer at a time. If the product permits, you may physically transfer the product from one computer to another, provided that the product is used only by a single person, on a single computer at a time. In group projects where multiple persons will use the product, you must purchase an individual license for each member of the group. Use over a local area network (within the same locale) is permitted provided that the product is used only by a single person, on a single computer at a time. Use over a wide area network (outside the same locale) is strictly prohibited under any and all circumstances.

Terms

This license is effective until terminated. You may terminate it by destroying the complete product and all copies thereof. This license will also terminate if you fail to comply with any terms or conditions of this agreement. You agree upon such termination to destroy all copies of the software and of the documentation, or return them to ICFM Software for disposal.

Other rights and restrictions

All other rights and restrictions not specifically granted in this license are reserved by ICFM Software.


Special DDEML debugging within Django

Most of the problems encountered whilst adding DDEML functionality are not functional but procedural, i.e. determining the correct order to process events.

Such procedural issues are often difficult to debug even within DELPHI IDE debugger, as it can interfere with the general timing process. Added to this the DELPHI IDE debugger will not operate when certain DDEML functions are active - starting and stopping conversations.

To counter these problems Django includes a debug utility of its own to provide a measure of support.

Viewing the Django component with the Object Inspector will indicate three debug related properties:

DebugState

This offers three states : dbNone, dbFile, dbForm.

•	If set to ‘dbNone’ no Django debugging output is created.

•	If set to ‘dbFile’ Django sends all debug output to a ASCII text file using the name set in the ‘DebugFileName’ property.

•	If set to ‘dbForm’ all debug output is sent to a special floating form which Django opens when the application is run.

DebugFileName

This property stores the name of the file used to hold the debug output if the DebugState is set to ‘dbFile’.  When the application is run the process checks to see if the file already exists. If it does it renames the exist file as ‘XXXXX.001’.  If a ‘XXX.001’ file already exists it renames it the next available number.

DebugStayOnTop

If the debug state is set to ‘dbForm’ then setting this property to TRUE will keep that form on top of all other forms.

Django provides debug output for every major processing action and around each call to an underlying DDEML API function. The debug output is specific to the Django design, and includes reference to the Django class and method name.

The debug display form shown above has a number of simple functions available for developer use.

•	You can close the form by selecting all ‘Close’ button. This disables all subsequent debug output.

•	You can clear all existing entries in the debug window by selecting the ‘Clear’ button.

•	You print the debug from content by selecting the ‘Print’ button

•	You can save the output to a file using the ‘Save’ button.


Editing the Services property at design time

The Services property represents a list of pre-defined DDEML server services.

This propety can be defined at design time, using a custom dialog, as shown below.

Service names are entered into the 'Name' edit box.  Use the 'Add' button to create a new service. Use the 'Update' button to change an existing service name. Select the 'Delete' button to remove a service.

Each service is by default allowed to process all defined commands. Where this is not appropriate the dialog allows one or more commands to be taken out of the set allowed against a particular service. Highlight a service in the 'Defined' listbox. Then highlight the required command name in the 'Valid' listbox/ Click on the '--->' button to move to into the invalid listbox. Only those commands left in the 'Valid' listbox will be available against the designated service.


ExeNameAsService

PROPERTY FailOptions : TDDEMLFailTypeSet

This property determines whether a Django DDEML server uses the application’s EXE name as the default service. Where an application is defined a a DDEML server, and the Django component has no service names defined in the ‘ServiceNames’ property then normally Django would assign the EXE name as the default service. This default behaviour is only applied if this property is set to TRUE. If it is set to FALSE then no default service is used.

(The property is TRUE by default).


Editing ExecCmds at Design Time
Editing the ExecCmds property at Design Time

The ExecCmds property holds a list of exec commands supported by a server application.

At design time this list can edited using a dialog, as shown below.

Each line represents a separate command. For each comamnd the dialog requires the definition of a unique command name; a param type string and an active status (Y/N).

The parameter string consists of one or more string characters. Each parameter is represented by a single character.

S	An upper case ‘S’ indicates a mandatory string type parameter

s	A lower case ‘s’ indicates an optional string type parameter

I	An upper case ‘I’ indicates a mandatory integer type parameter

i	A lower case ‘i’ indicates an optional integer type parameter

N	An upper case ‘N’ indicates a mandatory number (decimal) type parameter

n	A lower case ‘n’ indicates an optional number (decimal) type parameter

Lower case parameter types should not appear before uppercase type parameters. Django uses this parameter list definition to automatically verify any incoming exec command transactions. It rejects any that do not have the required parameter format.  For example a command parameter string of 'SSI' would equate to three mandatory parameters, the first two being string types, the third an integer.

The third column ‘Active?’ is used to define whether a command is active (available) at the start of a session.  A command cannot be used by a client if it is inactive.


Design Limitatations

General Design Issues

There are very few limitations to Django’s design   …

•	Text data passed into Django from the other end of a conversation using POKE or REQUEST cannot exceed 64K in length.

•	Parsed commands cannot have more than 20 parameters

WIN32 limitations or issues

Currently the WIN32 version of Django cannot detect whether another task is running. (This is because the WIN32 code required to detect other running applications is enormously complex, involving all sorts of strange registry calls. We were unable to complete this in time, and will supply a fix some time in the New Year). This means that any Django method that uses an EXE name parameter (e.g. ‘StartConv’) will not detect that application, and will always start a new instance of that application. We would suggest not specifying an EXE name parameter in such calls. Use a null string (‘’) instead.  The equivalent 16 bit process works perfectly normally.

If you retain the standard Borland DDE components in your DELPHI 2 component toolbar then we would suggest always nominating a specific service name (different to the EXE name) for your Django DDEML server.  This because the Borland components automatically register a DDEML service using the DELPHI project name as soon as DELPHI is loaded. If you were not to specify a Django service name then Django would automatically use the EXE name as a default service. Thus, when running the application from the DELPHI IDE there could be two identical service names registered (the Borland default and your Django name).  The WIN32 version of DDEML does’nt seem to like this. In such occasions GPF’s can occur inside the DDEML DLL when the server application is closed (it seems to be a bug inside the DDEML ‘DdeUnInitialise’ API function). This problem has been reported to Microsoft, but no response has been received to date.

In a similar vein we have experienced occasional problems with GPF’s inside the DDEML DLL when running the MCDEMO32 demo.  These occur when the main MCDEMO32.EXE is closing its own use of DDEML, and appear to be caused by a bug inside the DDEML ‘DdeUnInitalise’ API function. If this GPF occurs reboot your PC.