DDE server event function

The DDE server event function receives DDE messages sent by clients to the specified service.

When a DDE message is received, Sculptor calls the DDE event function for the service name. This function is defined when the service is registered (see dde_register()).

Calling the event function interrupts the processing of other statements, and care must be taken that variables are not used, and that files are not accessed, in a way that could affect the interrupted logic. If the event function only reads data from variables, and does not alter variables or access files that the main logic may be accessing, then random interruption of the main program will be safe. If the event function does in fact alter variables or access files which are also used by the main program, then the correct approach is to set sys.AutoEventCheck to zero, and to execute the checkevents command at times when it is safe to process an incoming request.

In order to avoid a DDE client request from timing out, messages sent to the server’s DDE event function should be processed as quickly as possible.

Once the event function has been called, Sculptor stops checking for messages until the function returns, regardless of the value of sys.AutoEventCheck. This avoids the risk of recursive calls to the function.

Interactive commands such as dialog, which force message checking, should be avoided inside a DDE event function. It is however safe to use the prompt command for debugging purposes, provided that no further messages are expected.

The function is called as follows:

func_id(event_code, conv_ID, topic, item, data)

The event codes that may be sent are:

DDE_CONNECT_REQUEST	A client is requesting a conversation on the topic specified. The item contains the service name. The conv_ID and data arguments are not used. Return OKAY to accept the conversation, or ERROR to refuse it.
DDE_CONNECT_CONFIRM	This confirms an accepted conversation request. The conv_ID argument contains a unique i4 number, identifying the conversation. This number is sent as the conv_ID with all subsequent messages in this conversation. The function return value is not used.
DDE_DISCONNECT	The client has disconnected the conversation identified by conv_ID. The function return value is not used.
DDE_EXECUTE	A client is requesting the server to execute a command. The topic argument contains the name of the topic; data contains the command text. The item argument is not used. Return OKAY if the command is executed, or ERROR to refuse the request.
DDE_POKE	A client has sent unsolicited data. The topic argument contains the name of the topic; item contains the name of the item; data contains the data value (text). Return OKAY if the data is accepted or ERROR to refuse the transaction.
DDE_REQUEST	The client is requesting data. The topic argument contains the topic name; item contains the item name; data is not used. Return the requested data as a text string or alphanumeric field (maximum length 255 characters). If the data cannot be supplied, return the special value NULL.

A typical event function is structured as follows:

!function ServerEvent(EventCode, ConvID, Topic, Item, Data) {
     switch(EventCode) {
          case & DDE_CONNECT_REQUEST:
               statements
               return OKAY

          case & DDE_CONNECT_CONFIRM:
               statements
               return OKAY

          other cases

          default:
               return ERROR        /* event code not recognised */
     }
}

---

RELATED TOPICS

DDE