Appendices

ILWIS as DDE server (advanced)

When you have programming experience and quite some ILWIS experience, you can write your own dedicated applications e.g. Visual Basic, Delphi, or C++. The applications will run on top of ILWIS. The end users of your application are not required to have any major ILWIS knowledge.

Purpose and opportunities:

• create your own dialog boxes for input;
• all difficult ILWIS calculations/expressions will be performed by your dedicated application, (i.e. not by the end user);
• combine and present information which you get from ILWIS in your own user-interface.
• combine the functionality of two or more different programs that act as DDE servers (e.g. ILWIS, Microsoft Word, Microsoft Excel, Microsoft Access, etc.).

In short, you can:

1. Access or execute all ILWIS commands, all MapCalc operators and functions, all TabCalc operators and functions, all ILWIS expressions, and all ILWIS script commands (SYSTEM - EXECUTE).
2. Retrieve or calculate simple information of a map, table or georeference, such as the value in a map at a certain coordinate, the number of rows (or columns) in a raster map, the minimum (or maximum) value in a map, the value as found in a certain record and column in a table, etc. The value to be retrieved or calculated is expected to be one value, string etc. only (CALC - REQUEST).
3. At the position of a mouse click in a map window, retrieve the value in a map or the coordinates at that mouse click, i.e. simulate Pixel Info (COORD).

GENERAL INFORMATION

What is DDE?

DDE is an abbreviation for Dynamic Data Exchange. Two Windows programs which both support DDE can exchange data with each other. The data transfer is called a conversation. A conversation takes place between a DDE server and a DDE client. A DDE client can transfer data (e.g. expressions/commands or any other information) to a DDE server. The server then replies with a response to the client; the response can either be an acknowledgement that the data was processed, or the result of a request for which the client asked. The DDE client can also 'subscribe' to data that the server sends to all subscribed clients every time a certain event occurs.

ILWIS always acts as the DDE server:

• executing the text (command, formula, expression) that is sent via DDE as if it were a script command;
• replying to the client by providing or calculating requested information;
• supplying information at a mouse click in a map window to DDE clients that 'subscribed' to such information.

The DDE server or source (ILWIS) thus supplies data to another application through a DDE link.

The DDE client is a program written in Visual Basic, Delphi, C++, etc. in which:

• you may have built your own user-interface for any necessary input;
• you may have defined the commands, formulas, expressions that ILWIS should execute for you;
• you may have built your own user-interface for the output.

The DDE client or destination is thus the application that requests and receives data.

In this Help topic, a general overview of DDE is given, sufficient to start building applications upon ILWIS. Some sample applications which show how DDE can be correctly used and which give some useful examples are supplied on the ILWIS CD.

For information on the programming process and required syntax of your dedicated application program, refer to the documentation of Visual Basic, Delphi or C++, etc., i.e. the language in which you are programming.

Introduction to DDE:

A DDE conversation in a DDE capable environment can be established as follows (ILWIS independent):

1. Set the DDE Link Topic. This tells the Windows DDE manager with which DDE server you wish to communicate, and it tells the DDE server which one of its available 'topics' you wish to use. Depending on the programming language used, you may need to specify the DDE server separately.
2. Set the DDE Link Mode. The Link Mode can be one of the following: none, manual or automatic. Setting the mode to manual or automatic will actually establish the DDE link between the client and the server. An existing link is cleared and freed when the mode is set to none.
3. Set a Link TimeOut if needed. The Link TimeOut has to be set to 10x the number of seconds that the application should wait before it concludes that there is a problem with the DDE communication (-1 means 'wait forever').
4. If the intention is to do a Link Request, you may first need to set the DDE Link Item (server dependent). The DDE Link Item does not have to be specified in other cases. Depending on the programming language used, the Link Item may be a parameter of the Link Request method instead of a link property. If the intention is to use automatic mode, it is recommended to set this property to a valid value before setting the Link Mode to establish the link. However, once the link is established, this property can safely be changed to a new valid value.
5. When manual mode is used, call Link Execute or Link Request; when automatic mode is used, just wait.
• Link Execute passes a parameter to the server; the server can read it and act accordingly.
• Link Request makes the server respond with the result of a calculation; the calculation may have been specified in Link Item.
• In automatic mode, the server will automatically send information 'asked for' through the Link Topic and Link Item parameters; the information will be sent every time a certain event occurs (this is up to the server).

Furthermore a DDE server usually responds to some standard DDE calls with which a client can find out, for instance, which topics are available by the DDE server and which data exchange formats are supported by the DDE server.

Language dependent DDE syntax:

DDE Link Topic

LinkTopic (Visual Basic)

SetLink (Delphi)

DDE Link Mode

LinkMode (Visual Basic)

ConnectMode (Delphi)

0 = None

1 = Automatic

2 = Manual

DDE Request method

LinkRequest (Visual Basic)

RequestData (Delphi)

DDE Execute method

LinkExecute (Visual Basic)

ExecuteMacro (Delphi)

Using the topics of the ILWIS DDE server:

The ILWIS DDE server has three available topics:

The system topic is meant to make the server execute ILWIS commands and ILWIS expressions; it is the only topic that will respond to the DDE Execute method. The ILWIS commands and expressions are passed (as a string) by the required parameter of this method.

The 'system' topic will also respond to Link Request methods. In that case, the only possible values for the Link Item property are 'topics', 'sysitems', 'status' and 'format'. The responses are only informative and are implemented so that ILWIS complies with the requirements of the DDE protocol.

The calc topic will only respond to the Link Request method, in which case the value of the Link Item property is used to pass the expression.

The coord topic will automatically respond upon clicks in a map window when the mode is set to Automatic, i.e. no Request is required; when the mode is set to Manual, the 'coord' topic will respond to the Request method. In both cases, the only possible values for the Link Item property are .X, .Y, .XY and mapname.ext.

Thus, the three Link Topics that are implemented in ILWIS and the Methods to access the topics are:

• for the system topic, use the Link Execute method, see section SYSTEM - EXECUTE,
• for the calc topic, use the Link Request method, see section CALC - REQUEST,
• for the coord topic, it is optional to use the Link Request method, see section COORD.

Detailed information can be found in the sections below.

For more information on ILWIS syntax that you may wish to use, refer to:

• To execute commands/expressions (SYSTEM - EXECUTE): Appendices : ILWIS commands, Map and Table Calculation : Functional overview of operators and functions, Appendices : ILWIS expressions, Appendices : ILWIS script language;
• To retrieve or calculate a single value (CALC - REQUEST): Coordinate functions, Point functions, Data property functions, Color functions;
• To retrieve information at mouse clicks (COORD): Pixel information window : functionality.

Tips:

• For more information about how to set up and close a DDE conversation, refer to the related documentation of Visual Basic, Delphi or C++, etc. Also check the sample applications available on the ILWIS CD.
• Make sure that ILWIS, i.e. the DDE server program, is running during the entire DDE conversation. Your program may hang or crash if no DDE server responds to a request.
• Mind that all data sent to ILWIS and all 'values' returned by ILWIS are in text format (strings).

1. SYSTEM - EXECUTE - MANUAL MODE

Use this DDE conversation method to perform ILWIS tasks as in an ILWIS script in order to define and/or calculate an ILWIS map, table, column, etc. or to display an ILWIS object, without the need to actually create an ILWIS script.

Through a DDE link, you can assign any task to ILWIS that can be handled by an ILWIS script. You can for instance:

• open an ILWIS dialog box on your screen;
• show an ILWIS map or table on your screen;
• perform any ILWIS MapCalc/TabCalc formula;
• perform any ILWIS operation;
• use the additional ILWIS script commands.

DDE syntax for SYSTEM - EXECUTE

To use the SYSTEM - EXECUTE conversation method in your application program:

• the DDE topic should be "ilwis|system"
  

   

  or server="ilwis" and topic="system" depending on the language you're using;

 

• use the DDE Execute method, its parameter is a string containing one or more ILWIS command(s) or expression(s); the ILWIS commands and expressions will be executed by ILWIS as if running an ILWIS script.
• You can establish one DDE link after the other, each time using a DDE Execute command and specifying one ILWIS expression, or
• You can also use one DDE Execute command, and specify all ILWIS expressions in the string; separate the expressions by semicolons.
  Note that this is only valid for ILWIS, as it differs from the method provided by the DDE protocol in which all commands are enclosed in square brackets ('[' and ']'). The square brackets are also supported by ILWIS for compatibility reasons.

The string containing the ILWIS command(s)/expression(s) to be executed is sent to the server; this string is a parameter to the DDE method 'Execute'; each call to the method 'Execute' is a request of the client to the server to execute the command(s)/expression(s) that are contained in the string.

Some examples of the ILWIS commands, MapCalc/TabCalc formulae, ILWIS operation expressions, and ILWIS Script commands that may be used are given below.

DDE example for SYSTEM - EXECUTE (Visual Basic):

' Assumption: MyControl is an existing object of class Control (e.g. a text box in the Visual Basic form)

MyControl.LinkTopic = "ilwis|system"

MyControl.LinkMode = 2      'mode Manual, to start the DDE conversation

MyControl.LinkExecute "Tmb1Edge=MapFilter(tmb1,edgesenh);calc Tmb1Edge.mpr;open -noask Tmb1Edge.mpr"

' The string on the previous line contains the ILWIS commands and expressions to be executed, separated by a ';'

MyControl.LinkMode = 0      'mode None, to close the DDE conversation

Map TMB1 is filtered with the edge enhancement filter, the output map TMB1Edge is calculated and displayed on the screen.

Some examples of ILWIS commands, MapCalc/TabCalc formulae, ILWIS expressions for operations, and ILWIS script commands which can be used with SYSTEM - EXECUTE:

2. CALC - REQUEST - MANUAL MODE

Use this DDE conversation method to retrieve or calculate a single value as using the pocket line calculator, in order to get information from ILWIS and use this in your dedicated application program.

DDE syntax for CALC - REQUEST

To use the CALC - REQUEST conversation method in your application program:

• the DDE topic should be "ilwis|calc"
  

   

  or server="ilwis" and topic="calc" depending on the language you're using;

 

• in the Link Item property, specify an ILWIS expression (string) to be evaluated;

 

• use the DDE Request method.

By applying the DDE Request method on a client control in your application, the server is asked to evaluate the expression. The result is then made available as the value of the used control object.

Some examples of MapCalc/TabCalc functions that retrieve or calculate a single value or a single string are given below.

DDE example for CALC - REQUEST (Visual Basic):

' Assumption: TextResult is an existing object of class Control (e.g. a text box in the Visual Basic form)

TextResult.LinkTopic = "ilwis|calc"

TextResult.LinkMode = 2      'mode Manual, to start the DDE conversation

TextResult.LinkItem = "MAPVALUE(tmb1, coord(800000,8080000))"

' The string on the previous line sets the expression to be evaluated at the next request

TextResult.LinkRequest

TextResult.LinkMode = 0      'mode None, to close the DDE conversation

The value in map TMB1 at the specified XY-coordinate will be retrieved from ILWIS and displayed in the TextResult control in the dialog box of your application.

Examples of ILWIS MapCalc/TabCalc functions that retrieve/calculate a single value or a single string:

3. COORD - AUTOMATIC AND MANUAL MODE

Use this DDE conversation method to retrieve value or coordinate information from maps at the position of a mouse click in a map window as in Pixel Info, in order to get information from ILWIS and use this in your dedicated application program.

When an analog map is referenced on a digitizer tablet, you can also use the digitizer cursor to retrieve this information. For more information, see Pixel information window : functionality.

If Automatic Mode is used, each mouse click will be automatically sent to your DDE application; this method 'subscribes' your application to (a subset of) the information that ILWIS can send to subscribed DDE clients on every mouse click.

If Manual Mode is used, the 'value' of the latest mouse click has to be requested for.

DDE syntax for COORD

To use the COORD conversation method in your application program:

• the DDE topic should be "ilwis|coord"
  

   

  or server="ilwis" and topic="coord" depending on the language you're using;

 

• set the Link Item property to either .X, .Y, .XY or mapname.ext.

.X	To retrieve the X-coordinate of any raster, polygon, segment or point map at the position of a mouse click.
.Y	To retrieve the Y-coordinate of any raster, polygon, segment or point map at the position of a mouse click.
.XY	To retrieve the XY-coordinate as (X, Y) of any raster, polygon, segment or point map at the position of a mouse click.
MapName.ext	To get the class name, ID or value from any raster, polygon, segment or point map MapName.ext at the coordinate of the mouse click. It is not required that Map MapName.ext is currently displayed in the map window.

When specifying Automatic Mode, any click in a map window will automatically update the value of the object in the dedicated application program. This happens in the same way as with the CALC conversation method: the result becomes available as the value of the control object used to do the DDE conversation.

When using Manual Mode, information of the latest click in a map window will be sent to the dedicated application program upon making a Request.

The Timeout can be used to determine how long a control waits before assuming that there is a problem with the DDE conversation. A Timeout of -1 will keep the DDE conversation active forever.

DDE example for COORD, using Mode Automatic (Visual Basic):

' Assumption: CurrVal and CurrX are existing objects of class Control (e.g. text boxes in the Visual Basic form)

CurrVal.LinkTopic = "ilwis|coord"

CurrVal.LinkItem = "Landuse.mpa"

CurrVal.LinkMode = 1      'mode Automatic

CurrVal.LinkTimeOut = -1

CurrX.LinkTopic = "ilwis|coord"

CurrX.LinkItem = ".X"

CurrX.LinkMode = 1          'mode Automatic

CurrX.LinkTimeOut = -1

OVERVIEW of DDE syntax in ILWIS

The topic identifies the source application and topic.

The item identifies the particular data (the item) that the server sends to the client. Under topic SYSTEM, the items TOPICS, SYSITEMS, STATUS and FORMAT (that resp. return the server's topics, the system items, the status and the supported data formats) are only there so that ILWIS complies to the DDE protocol. Most likely you will not need to use these items in your application.

The execute method sends a command string to the conversation partner; the request method asks the server to update the property values of a client's DDE control.

The mode identifies the type of link that is used during a DDE conversation. It lets the application determine whether the client control receives new values anytime the data changes in the source ('automatic' or 'hot link'). Alternatively, the mode lets the application decide whether the client must explicitly request the updated values ('manual' or 'cold link').

The timeout determines how long a control waits before assuming that there is a problem with the DDE conversation.

Topic, Item, Mode and Timeout are the properties of a DDE conversation.

Execute and Request are methods that act as DDE commands.