Programming Guide : Inter-Frame Communication Techniques : How You Can Communicate with an External Program Using External User Events : How You Can Send the External User Event to OpenROAD
 
Share this page          
How You Can Send the External User Event to OpenROAD
To send the event from the external program to OpenROAD, you must write a 3GL program that sends the named event to OpenROAD.
This program sends the event to any running OpenROAD frames. If an OpenROAD frame has registered for that event, the associated event block is triggered. If none of the events are registered or if none of the registered frames are running, the request is ignored.
OpenROAD provides the IIW4GL_SendUserEvent procedure to send the event name and optional integer value. This procedure is described in the . (see IIW4GL_SendUserEvent Procedure.
IIW4GL_SendUserEvent Procedure
The IIW4GL_SendUserEvent procedure sends the event name and optional integer value directly to the OpenROAD application. It returns an integer status value. The syntax follows:
status = IIW4GL_SendUserEvent(errormsg, &sent, token,
    eventname, fb, msgi4)
This procedure takes the following arguments:
errormsg
Specifies an output character string variable that holds the text of any error that occurs while the procedure executes. Declare this as “char errormsg[256].”
&sent
Specifies an output parameter that indicates how many frames are registered for the specified event and, consequently, how many events were sent. You must use the & operator. Declare this as “int sent.”
token
Specifies an obsolete parameter. No values are sent or returned to this variable. Declare this as “char *token.”
eventname
Specifies an input parameter that identifies the user event. This event must have been registered by a previous 4GL RegisterUserEvent method. This parameter is case sensitive and must be null terminated. Declare this as “char *eventname.”
fb
Specifies an input parameter that specifies the focus behavior for the current field in the frame. Declare this as “long fb.”
This parameter corresponds to the focusbehavior parameter of the SendUserEvent method for internal events. It lets you trigger the SetValue event or both SetValue and Exit events for the field with the input focus before the external event is triggered. For more information, see Focusbehavior Parameter.
Valid values for fb are:
1
FT_NOSETVALUE
2
FT_SETVALUE
3
FT_TAKEFOCUS
These FT constants are defined in the w4glext.h include file.
msgi4
Specifies an input parameter that specifies a single integer value to be sent to the receiving frame. In the receiving frame, you can access this value with the MessageInteger attribute of the FrameExec object. Declare this as “long msgi4.”
status
Specifies a return variable that is an output integer variable that indicates the success or failure of the procedure. If the return value is IIW4GL_OK, the send was successful. If the return value is a nonzero value, the send failed (the text of the error message is in errormsg). Declare this as “int status.”