XMM-Newton Science Analysis System


oal (oal-3.139) [xmmsas_20230412_1735-21.0.0]

ODF data set name completion

The OAL provides functionality to expand a pair of two or a tuple of four identifiers into a valid ODF data set name which can then be used to physically open the set, e.g. with the dal open method. The corresponding OAL routine receives a string which is either a valid data set name or of the form

odf(<instr>, <mode>[, <expnr>, <ccdnr>[, scheduledFlag]])

or

oal(<instr>, <mode>[, <expnr>, <ccdnr>[, scheduledFlag]])

The four fields have the following meaning:

<instr>:

 a string which must uniquely identify an instrument. The following table lists the possible values:

identifier	meaning
XMM	selects satellite specific data sets or sets for which the instrument field is not applicable
XRT1/XRT2/XRT3	the mirror systems 1, 2, (in front of EMOS1/RGS1 and EMOS2/RGS2), and 3 (in front of EPN)
EMOS1/EMOS2	EPIC MOS camera units 1 and 2
EPN	EPIC PN camera unit
ERM	EPIC Radiation Monitor
RGS1/RGS2	units 1 and 2 of the RGS
OM	the optical monitor

<mode>:

 a string which must uniquely identify a data mode; see Appendix A for a list of allowed values

<expnr>:

 a numeric value identifying an exposure number within the current observation period; must be set to 0 if not applicable

<ccdnr>:

 a numeric value specifying a CCD chip of the selected instrument. CCD numbers are in the range 1–7 for EMOS1/EMOS2, 1–12 for EPN, and 1–9 for RGS1/RGS2; the numbering follows that used in the cal. For OM this is the science window identifier. Example: 1 for EMOS1 specifies the central chip on EMOS camera 1 and 12 for EPN the bottom right chip of the EPN camera as viewed from the mirror platform through the telescope tube onto the focal plane. For data sets for which the field is not applicable a value of 0 must be given. If neither expnr nor ccdnr are applicable as this is the case for some files in the satellite scope, the form

odf(<instr>, <mode>)

can be used in lieu of the above full form. Example: odf(XMM, Attitude) refers to the Attitude History File a single instance of which applies to the the entire observation period the current ODF covers.

<scheduledFlag>:

 the letter 'S' or 'U' for Scheduled/Unscheduled; the field is optional, if omitted no check for the scheduled status of the exposure will be done.

For the two non-numeric fields <instr> and <mode> abbreviations can be used to designate a wanted value, e.g. Im, or Ima, Image are all valid reference to `Imaging Mode'. If an abbreviated string value cannot be unambiguously expanded into its full form a fatal error condition is raised. Case is insignificant for both fields.

The ODF file name completion needs access to the Summary File of the ODF in question. Therefore, the name of the directory containing an ODF must be specified by the user, either in the form of a proper task parameter or in an environment variable. See below for details.