*+
*  Name:
*     ARY_DCB

*  Purpose:
*     Define ARY_ system Data Control Block (DCB).

*  Language:
*     Starlink Fortran 77

*  Type of Module:
*     Global variables include file.

*  Description:
*     This file defines global variables which hold information about
*     the data objects handled by the ARY_ system.  A one-to-one
*     correspondence is maintained between entries in this block and
*     the actual data objects known to the system. This is in contrast
*     to the virtual objects which are described in the Access Control
*     Block, several of whose entries may refer to a single actual data
*     object via its entry in the DCB.

*  Prior Requirements:
*     The SAE_PAR, ARY_PAR and ARY_CONST include files should be
*     included prior to this file, in order to define constants used
*     here.

*  Authors:
*     RFWS: R.F. Warren-Smith (STARLINK)
*     {enter_new_authors_here}

*  History:
*     22-SEP-1989 (RFWS):
*        Original version.
*     26-SEP-1989 (RFWS):
*        Tidied comments.
*     5-MAR-1990 (RFWS):
*        Made comments system-independent.
*     {enter_further_changes_here}

*-

*  Global Variables:

*  Which slots have been used.
*  ==========================
*  This array is initialised to .FALSE. by the ARY1_INIT block data
*  routine. Its entries are then selectively set to .TRUE. to indicate
*  which slots in the DCB are in use (i.e. have data objects associated
*  with them).
      LOGICAL DCB_USED( ARY__MXDCB )
      
*  Form of array.
*  =============
*  If a slot is in use and its DCB_KFRM entry is .TRUE., then the
*  DCB_FRM entry contains the storage form (e.g. 'SIMPLE') of the array
*  data object associated with that slot. If DCB_KFRM is .FALSE., then
*  this information is not available or is out of date.
      LOGICAL DCB_KFRM( ARY__MXDCB )
      CHARACTER * ( ARY__SZFRM ) DCB_FRM( ARY__MXDCB )

*  Reference count.
*  ===============
*  If a slot is in use, then DCB_REFCT stores the number of Access
*  Control Block (ACB) entries which currently refer to the slot, and
*  hence to the associated data object. DCB_NREAD and DCB_NWRIT count
*  the number of these ACB entries for which mapped access is in effect
*  and requires data to be read or written (respectively) to the data
*  object; UPDATE access is included in both counts.
      INTEGER DCB_REFCT( ARY__MXDCB )
      INTEGER DCB_NREAD( ARY__MXDCB )
      INTEGER DCB_NWRIT( ARY__MXDCB )

*  Data object locator.
*  ===================
*  If a slot is in use, then DCB_LOC contains an HDS locator to the
*  associated data object.
      CHARACTER * ( DAT__SZLOC ) DCB_LOC( ARY__MXDCB )

*  Access mode.
*  ===========
*  If a slot is in use and the DCB_KMOD entry is .TRUE., then the
*  DCB_MOD entry contains the access mode available for the associated
*  data object ('READ' or 'UPDATE'). If the DCB_KMOD entry is .FALSE.,
*  then this information is not available, or is out of date.
      CHARACTER * ( ARY__SZMOD ) DCB_MOD( ARY__MXDCB )
      LOGICAL DCB_KMOD( ARY__MXDCB )

*  Array state.
*  ===========
*  If a slot is in use and the DCB_KSTA entry is .TRUE., then the
*  DCB_STA entry indicates whether the array's data values have been
*  defined by the completion of a WRITE operation on the array, while
*  DCB_INIT indicates whether those array values which cannot be
*  affected by current write operations have been initialised, so that
*  they are not left undefined when the write operation completes.
*  (Normally, DCB_STA and DCB_INIT are set to .FALSE. when an array is
*  created. DCB_INIT is set .TRUE. when the first write access is
*  initiated and unaffected data in the array is initialised.  DCB_STA
*  is set .TRUE. when the first write operation completes.) If the
*  DCB_KSTA entry is .FALSE., then this information is not available or
*  is out of date.
      LOGICAL DCB_KSTA( ARY__MXDCB )
      LOGICAL DCB_STA( ARY__MXDCB )
      LOGICAL DCB_INIT( ARY__MXDCB )

*  Disposal mode.
*  =============
*  If a slot is in use, then the DCB_DSP entry contains the disposal
*  mode ('DELETE', 'KEEP' or 'TEMP') which indicates the action to be
*  taken when the associated data object is released from the ARY_
*  system. Release occurs when the DCB_REFCT entry for the object falls
*  to zero.
      CHARACTER * ( ARY__SZDSP ) DCB_DSP( ARY__MXDCB )

*  Data type and component locators.
*  ================================
*  If a slot is in use and the DCB_KTYP entry is .TRUE., then the
*  DCB_TYP entry contains the numeric data type of the associated data
*  object and DCB_CPX indicates whether it holds complex data. The
*  DCB_DLOC entry holds an HDS locator to the non-imaginary data
*  component and, if DCB_CPX is .TRUE., DCB_ILOC holds a locator to the
*  imaginary data component. If the DCB_KTYP entry is .FALSE., then
*  this information is not available or is out of date.
      LOGICAL DCB_KTYP( ARY__MXDCB )
      CHARACTER * ( DAT__SZTYP ) DCB_TYP( ARY__MXDCB )
      LOGICAL DCB_CPX( ARY__MXDCB )
      CHARACTER * ( DAT__SZLOC ) DCB_DLOC( ARY__MXDCB )
      CHARACTER * ( DAT__SZLOC ) DCB_ILOC( ARY__MXDCB )

*  Bad pixel flag.
*  ==============
*  If a slot is in use and the DCB_KBAD entry is .TRUE., then the
*  DCB_BAD entry stores the value of the logical "bad pixel flag" for
*  the associated data object. If the bad pixel flag is .FALSE., then
*  there are no "bad" pixels in the data and no checks for them need be
*  made. If the bad pixel flag is .TRUE., then there are (or may be)
*  "bad" pixels present which must be checked for. If DCB_KBAD is
*  .FALSE., then this information is not abailable or is out of date.
      LOGICAL DCB_KBAD( ARY__MXDCB )
      LOGICAL DCB_BAD( ARY__MXDCB )

*  Dimensionality and bounds information.
*  =====================================
*  If a slot is in use and the DCB_KBND entry is .TRUE., then the
*  DCB_NDIM entry holds the number of dimensions of the data object and
*  DCB_LBND and DCB_UBND hold its lower and upper pixel index bounds in
*  each dimension. These latter entries are padded with 1's to make the
*  number of bounds up to ARY__MXDIM. If DCB_KBND is .FALSE., then this
*  information is not available or is out of date.
      LOGICAL DCB_KBND( ARY__MXDCB )
      INTEGER DCB_NDIM( ARY__MXDCB )
      INTEGER DCB_LBND( ARY__MXDIM, ARY__MXDCB )
      INTEGER DCB_UBND( ARY__MXDIM, ARY__MXDCB )

*  Accumulated pixel index shifts.
*  ==============================
*  If a slot is in use, then the DCB_SFT entry holds an accumulated sum
*  of all the pixel index shifts which have been applied to the
*  associated data object since it was first made known to the ARY_
*  system. A total of ARY__MXDIM shifts is held, regardless of the
*  actual data object dimensionality.
      INTEGER DCB_SFT( ARY__MXDIM, ARY__MXDCB )

*  Container file and HDS path names.
*  =================================
*  If a slot is in use, then the DCB_FILE entry contains the full name
*  of the HDS container file containing the associated data object and
*  the DCB_PATH entry contains the data object's HDS path name within
*  that file.
      CHARACTER * ( ARY__SZFIL ) DCB_FILE( ARY__MXDCB )
      CHARACTER * ( ARY__SZPTH ) DCB_PATH( ARY__MXDCB )

*  Common Blocks:    

*  Character data.
      COMMON /ARY1_DCB1/ DCB_DLOC, DCB_DSP, DCB_FILE, DCB_FRM, DCB_ILOC,
     :                   DCB_LOC, DCB_MOD, DCB_PATH, DCB_TYP

*  Non-character data.
      COMMON /ARY1_DCB2/ DCB_BAD, DCB_CPX, DCB_INIT, DCB_KBAD, DCB_KBND,
     :                   DCB_KFRM, DCB_KMOD, DCB_KSTA, DCB_KTYP,
     :                   DCB_LBND, DCB_NDIM, DCB_NREAD, DCB_NWRIT,
     :                   DCB_REFCT, DCB_SFT, DCB_STA, DCB_UBND,
     :                   DCB_USED

*.
