DM_QueueExtEvent

3.54 DM_QueueExtEvent

The execution of a rule attached to an external event is registered by the application with the function DM_QueueExtEvent.Registered means that the rule is not executed immediately, but that the external event is queued and then processed according to the dialog event mechanisms.

The event is processed by the IDM with the usual event processing algorithm which results in calling a rule with the scheme on <object> extevent <no.>.

DM_Boolean DML_default DM_EXPORT DM_QueueExtEvent
(
  DM_ID       objectID,
  DM_Int4     event_no,
  DM_UInt     argc,
  DM_Value   *argv,
  DM_Options  options
)

Parameters

-> DM_ID objectID

This is the identifier of the object to which this external event is to be sent.

-> DM_Int4 event_no

This parameter is the number of the external event to be triggered.

-> DM_Int argc

This parameter transfers the number of parameters (up to 16).

-> DM_Value *argv

This parameter indicates the arguments (up to 16) which the IDM passes to the rule on invocation. This vector must have the length that is specified in the argc parameter.

-> DM_Options options

The following values can be specified as options:

Option	Meaning
DMF_DontTrace	This option implies that the function call shall not be traced, if the application is started with the trace option.
DMF_Synchronous	This option can be set, if it is ensured that the function DM_QueueExtEvent is called synchronously to the process. In this case, the function internally can work more efficiently. A synchronous call is not given, when the function is called from a signal handler, for instance.
DMF_NoCriticalSection	This option prevents the function from using a critical section on Microsoft Windows.

Return Value

DM_TRUE	External event could be put in queue.
DM_FALSE	External event could not be put in queue.

Note for Microsoft Windows

Since IDM version A.05.01.a, the function DM_QueueExtEvent uses a critical section to ensure, that it has been completed before this function or the functionDM_SendEvent is invoked once more. If one of these functions is called in a situation where a critical section is not permitted, the use of the critical section can be prevented through the option DMF_NoCriticalSection.

Attention

A thread, that carries out one of the two functions must not be canceled.

Example

In a dialog, there shall be a response to a signal of the operating system. The dialog looks as follows:

on dialog extevent 4711 (integer ErrCode)
{
  variable string S;
  S := "Dialog has received extevent " + itoa(ErrCode);
  print S;
}

The corresponding C program looks like this:

#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <IDMuser.h>

DM_ID dialogID;

/* This function has been installed as signal handler */
void handler __1((int, sig))
{
  DM_Value data;
 
  data.type = DT_integer;
  data.value.integer = sig;
  DM_QueueExtEvent(dialogID, 4711, 1, &data, 0);
}