6 Using IRQ routines

This section gives a brief outline of the IRQ routines which are available to perform some common tasks. The specific details required to use these routines are not included here but can be found in the subroutine specifications contained in the full specifications.

6.1 Constants and Error Values

The IRQ package has associated with it various symbolic constants. These values consist of a name of up to five characters prefixed by “IRQ__” (note the double underscore), and can be made available to an application by including the following line at the start of the routines which uses them:

This assumes that the IRQ library has been installed as part of the UNIX Starlink Software Collection.

The values thus defined are described in the following sections, and also in the subroutine specifications. Another set of symbolic constants is made available by the statements

These values have the same format of those contained in IRQ_PAR, put define various error conditions which can be generated within the IRQ package. Applications can compare the $STATUS$ argument with these values to check for specific error conditions. These values are described in IRQ Error Codes.

6.2 Initialising an NDF for use with IRQ

Certain HDS structures must be created within an NDF before the NDF can be used by IRQ. These structures hold information describing the currently defined quality names within the NDF. Routine IRQ_FIND can be used to see if such structures exist within an NDF (see below). If no such structure yet exists within an NDF, routine IRQ_NEW must be called to create the structure. This structure is held in a specified NDF extension. IRQ_NEW returns an array of HDS locators which must be passed to subsequent IRQ routines. One of these locators points to a cloned copy of the NDF identifier. All access to the NDF by subsequent IRQ routines is achieved through this cloned identifier. Once access to the quality names information is no longer required, the resources used by these HDS locators (including the cloned NDF identifier) should be annulled by calling IRQ_RLSE. Note, routines IRQ_ANNUL and IRQ_CLOSE play no part in releasing resources used for accessing quality name information. These two routines are only used for releasing resources used to store compiled quality expressions (see a description here). IRQ_RLSE is the only routine which needs to be called to release resources used for accessing quality names.

6.3 Using previously initialised NDFs within IRQ

If the NDF has been initialised for use by IRQ, then the structure holding the quality names information must be found before other IRQ routines can be called. Routine IRQ_FIND does this. This routine looks through all the NDF extensions until a suitable structure is found. If no such structure is found the status value IRQ__NOQNI is returned. If more than one extension contains such a structure, then the status value IRQ__MULT is returned. If the routine runs successfully, then an array of HDS locators is returned similar to the array returned by IRQ_NEW. Once access to the quality names information is no longer required, the resources used by these HDS locators (including the cloned NDF identifier) should be annulled by calling IRQ_RLSE.

6.4 Accessing the quality names information stored in an NDF

To access the quality names information stored within an NDF, a set of HDS locators to the information must first be obtained by calling either IRQ_NEW or IRQ_FIND (see above). Once this has been done the information can be read, modified, or added to. IRQ_ADDQN adds a new quality name definition to an NDF (so long as there is room for it within the structures and the QUALITY component). IRQ_CHKQN checks to see if a given name is defined. IRQ_GETQN searches for a specified quality name, and returns various items of information about it (such as which bit of the QUALITY component it is assigned to). IRQ_NUMQN returns the number of defined quality names. IRQ_NXTQN returns the next defined quality name. Repeated calls to IRQ_NXTQN can be made to get a list of all the quality names defined within an NDF. IRQ_REMQN removes the definition of a quality name from an NDF, so long as the quality name has not been flagged as ‘read-only’ (see IRQ_RWQN).

6.5 Assigning and removing qualities to and from NDF pixels

Once quality names have been defined, they can be assigned to selected pixels within the NDF. There are two ways of specifying which pixels are ‘selected’. Routine IRQ_SETQM requires a mask image to be provided in which the ‘bad’ pixels define the pixels in the NDF DATA component to which the quality is to be assigned. Routine IRQ_SETQL requires a list of pixel indices to be provided which defines the pixels in the NDF DATA component to which the quality is to be assigned. The quality of the NDF pixels which are not selected is left unchanged. Thus, if an unselected pixel already has the specified quality, these routines will not remove the quality from those pixels.

The routines IRQ_RESQM and IRQ_RESQL, are complementary to IRQ_SETQM and IRQ_SETQL. Instead of ensuring that the selected pixels hold the specified quality, these routines ensure that the selected pixels do not hold the specified quality. Again, the quality of unselected pixels is left unchanged.

Routine IRQ_SETQ ensures that all pixels in an NDF have a specified quality, and routine IRQ_RESQ ensures that no pixels in an NDF have a specified quality.

The routine IRQ_CNTQ will count the number of bits set in each bit plane in the QUALITY component.

6.6 Finding NDF pixels which satisfy a quality expression

If a subset of pixels are to be operated on by an application, the application will usually obtain a quality expression from the user which defines the pixels to be operated on. That is to say, pixels which have qualities which do not satisfy the quality expression would not usually be used by the application. The quality expression is usually obtained from the user using the ADAM parameter system. It is then passed to IRQ_COMP to be compiled. If any problems are detected with the expression (such as syntax errors, or undefined quality names) IRQ_COMP will report an error, and it is then up to the applications to decide what to do. Typically, it will flush the error, and reprompt the user for a new quality expression. The routine IRQ_SYNTX will check a quality expression for syntax errors without actually compiling it or checking that the referenced quality names are defined.

If IRQ_COMP successfully compiles the quality expression, it returns an identifier for the compiled quality expression. This identifier is actually a pointer to a temporary HDS structure holding information about the quality expression. The identifier is passed to IRQ_SBAD which locates all NDF pixels that have qualities that satisfy the quality expression. The corresponding pixels in an array supplied to IRQ_SBAD are set ‘bad’. The other pixels are left unchanged. Alternatively, pixels with qualities which do not satisfy the quality expression can be set bad in the supplied array. Note, the array supplied to IRQ_SBAD must be the same shape and size as the NDF supplied to IRQ_FIND or IRQ_NEW. If an NDF section was used, then the array supplied to IRQ_SBAD must be the same shape and size as the NDF section, not the base NDF.

Up to ten compiled quality expressions can be active at once. The identifiers for each compiled quality expression should be annulled when it is no longer needed by calling IRQ_ANNUL. IRQ_CLOSE should be called when all compiled quality expressions have been finished with.