This section describes the use of the Image Display Interface (IDI) in ADAM application programs. It is expected that the reader is familiar with programming for ADAM and with IDI.
The image display interface (IDI) is fully described in the specification document, and the details of the Starlink implementation are given in the preceding sections. This section will therefore only deal with issues relating to the use of IDI in ADAM application programs.
All IDI routines may be used in ADAM applications with the exception of the following routines, which must never be called in ADAM programs
IIDOPN - Open Display
IIDCLO - Close Display
The function of IIDOPN is performed by the environment routine IDI_ASSOC. The function of IIDCLO is performed by the environment routine IDI_CANCL, or IDI_ANNUL.
Note that these routines, unlike the core IDI routines, use the principle of inherited status. The routine IDI_ASSOC will only execute if the status is equal to zero on entry. The routines IDI_ANNUL and IDI_CANCL will execute if the status is non-zero on entry, so that devices can be closed in the event of unrelated errors, and will return the error status unchanged.
As with all other packages in the Software Environment, the only access to objects outside of application programs is via Program Parameters. IDI has three subroutines (the IDI parameter routines) that provide the necessary interaction with the outside world. They are:
IDI_ANNUL( dispid, status )
Associate an IDI device with a parameter
IDI_ASSOC( pname, acmode, dispid, status )
Release an IDI device
IDI_CANCL( pname, status )
Release an IDI device and cancel the parameter
Here is a skeletal example of a program using IDI
IDI_ASSOC should be the first IDI routine to be called in the application. It obtains the name of the graphics device to be used (via the parameter system) and opens this device for subsequent IDI operations.
The first argument of IDI_ASSOC is a Program Parameter (which should be defined to be a device parameter in the Interface Module for the application).
The second argument is the access mode required. This can be one of
’READ’ The application is only going to ’read’ from the device, (i.e. perform cursor or similar operations), without altering the display appearance. The display is not cleared or reset when the device is opened.
’WRITE’ The application is going to ’write’ on the device creating a new screen display. The display is cleared and reset when it is opened.
’UPDATE’ The application will modify the device, taking the existing display and changing it. The display is not cleared or reset when the device is opened.
The third argument is the display identifier returned to the application. This must be passed to all subsequent IDI routines which are to be used on this device.
The fourth argument is the usual status value.
When the application has finished using the device, the display is closed and the identifier annulled using the IDI_ANNUL, or IDI_CANCL routines.
A simple interface file for the above example would be:
The description of each of the application level subroutines in the package now follows