Open topic with navigation

IDL_IDLBridge Properties

IDL_IDLBridge objects have the following properties. Properties with the word “Yes” in the “Get” column of the property table can be retrieved via IDL_IDLBridge::GetProperty . Properties with the word “Yes” in the “Init” column of the property table can be set via IDL_IDLBridge::Init. Properties with the word “Yes” in the “Set” column in the property table can be set via IDL_IDLBridge::SetProperty .

Note: For more information about the “Property Type”, “Name String”, and “Registered” columns, see Modifying Object Properties.

Objects of this class have the following properties:

• CALLBACK
• OUTPUT
• USERDATA

CALLBACK

The name of a user-defined callback procedure that is automatically called when an asynchronous command is completed. When an asynchronous command is done (completed, aborted, or halted due to an error) the procedure specified by the CALLBACK property is called.

This callback procedure must have the following signature:

PRO BridgeCallbackName, Status, Error, Objref [, Userdata]

where each argument of the BridgeCallbackName procedure is given the following values:

• Status — an integer value that contains one of the following values:

  Value	Description	ERROR Keyword Contents
  2	Completed command	Empty string
  3	Error halted execution	Descriptive error string
  4	Aborted execution	Abort message

  Note: Because the Callback is only called when a command ends, values of Status=0 (Idle) or Status=1 (Executing) will never be returned. (See IDL_IDLBridge::Status for a list of all possible status values.)

• Error — a string corresponding to any error that may have occurred while executing the command in the child process. As shown in the table above, if Status contains an error status (3), the Error argument returns a descriptive error string. If Status indicates an aborted status (4), Error returns an abort message. Otherwise, the Error argument will be set to an empty string.
• Objref — the object reference to the IDL_IDLBridge object that is associated with the callback.
• Userdata — the value of the USERDATA property. If the USERDATA property has been set, then this argument is required for your callback procedure. If the USERDATA property has not been set, this Userdata argument is optional, and if provided, will be set to an undefined variable.

When the asynchronous command is completed, aborted, or halted due to an error, the child IDL process calls back into the main IDL process. The main IDL process puts a callback event into the callback event queue for the bridge object. The callback queue for this bridge object is flushed (and the CALLBACK procedure or OnCallback method is called) when one of the following occurs:

• The widget event queue is flushed by IDL’s widget event processing
• The user calls WIDGET_EVENT
• The user calls any IDL_IDLBridge method (except Abort)
• The user calls OBJ_DESTROY

Note: See the IDL_IDLBridge Examples for samples of setting the CALLBACK property. Also see the IDL_IDLBridge::OnCallback.

OUTPUT

A string supplying the path and name of a file to which messages generated in the child process will be written. By default, any output written by the child process is quietly discarded by the IDL_IDLBridge object, and is not seen by the user. This is useful for debugged production quality code, but can be inconvenient when the code being executed by the child encounters errors, since you cannot see the text of the error messages.

Note: Under UNIX, but not Microsoft Windows, you may also set the OUTPUT keyword to a NULL file string (e.g. OUTPUT=''). In this case, the child process output is not diverted by the IDL_IDLBridge object, and is written by the operating system directly to stdout and stderr, which is usually the user’s tty.

USERDATA

A value of any type containing any information you wish. If USERDATA is set, the value contained within the USERDATA property is passed to the CALLBACK procedure after completion of an asynchronous command.

Note: Object references or pointers contained in the USERDATA property are not automatically cleaned up when the IDL_IDLBridge object is destroyed.