The collections
================

Object collections JEVEUX are structures that allow the sharing of attributes and possibly named access to a group of objects. They can be associated with a single value segment (contiguous collection) or with as many value segments as there are objects (dispersed collection). They are built from simple objects JEVEUX, and therefore appear in this form among the objects associated with a class. The main object of the collection is the object of genre X, it is a vector of 11 integers containing the identifiers of the various objects that make up the collection (among others the system objects of the collection that contain a suffix starting with $). This vector has the name assigned using routine JECREC (CHARACTER *24). System objects specific to the collection have a suffix beginning with $ in position 25; if they are associated with a shared object, they have a suffix starting with &&. The attributes common to all collectibles are deposited among the attributes of the system object $$ DESO (genre, type, length, etc.).

The system objects associated with a collection are created in the associated class (identical attribute for all system objects) and loaded into memory using the JJCREC routine.


.. csv-table::

    "", "**Collection system object name suffix**", "**Content**", "**Associated Fortran type**", "**Collection type**"
    "1", "$$ DESO
    the attributes associated with this object are the common attributes of the collection", "contiguous collection: values associated with the various collection objects", "INTEGER *8", "scattered and contiguous the value segment only exists for contiguous collections"
    "2", "$$ IADD ", "disk addresses of objects from scattered collections", "INTEGER *8", "scattered"
    "3", "$$ IADM ", "memory addresses of objects from scattered collections", "INTEGER *8", "scattered"
    "4", "$$ MARQ ", "marks associated with scattered collectibles", "INTEGER *8", "scattered"
    "5", "$$ NOMou shared object property", "list of names of objects from named collections", "next
    the associated directory", "named"
    "6", "$$ LONGou shared object", "length measured in the value segment type; receive values associated with attributes LONMAXet NOMMAX "," INTEGER *8", "" of variable length"
    "7", "$$ LONOou & LONO ", "effective length measured in the value segment type; is used internally by the software", "INTEGER *8", "of variable length"
    "8", "$$ LUTIou & LUTI ", "used length of value segments", "INTEGER *8", "of variable length"
    "9", "$$ NUM ", "information about numbered collections", "INTEGER *8", "numbered"


The routines using collections, and more specifically the collection descriptor object, contain the following instructions:


.. code-block:: text
 INTEGER IVNMAX, IDDESO, IDIADD,, IDIADM,
+ IDMARQ, IDNOM, IDLONG,
+ IDLONO, IDLUTI, IDNUM
PARAMETER (IVNMAX = 0, IDDESO = 1, IDIADD = 2, IDIADM = 3,
+ IDMARQ = 4, IDNOM = 5, IDLONG = 7,
+ IDLONO = 8, IDLUTI = 9, IDNUM = 10)

This makes it possible to position yourself directly in the memory area to obtain the identifiers of the system objects (when they exist) in the following order: $$ DESO, $$ IADD, $$ IADM, $$ MARQ, $$ NOM, $$, $$, $$, $$, $$, $$, $$, $$, $$, $$ LONG, $$, $$, $$, $$,,, $$,,, $$,,, $$,,, $$,,, $$,,, $$,,, $$, LONO LUTI NUM The maximum number of collectibles is stored at IVNMAX.

**The named collections**

The objects associated with such a collection are accessible by their name (function JEXNOM) and by their insertion order number (function JEXNUM). It is possible to use the routines JENUNO and JENONU to go from number to name and vice versa. The length of object names is limited to 8 characters (CHARACTER *8) if the collection is based on an "internal" name directory, or may be worth 8, 16 or 24 if the collection is based on an "external" name directory, i.e. created previously (shared name directory).

**Numbered collections**

Objects associated with such a collection are only accessible by their insertion order number (function JEXNUM). The system object $$ NUM is a vector of 2 integers containing the maximum number of collectibles and the number of objects used respectively.

**The scattered collections**

Each object is associated with a value segment, so there is no need to bring back the entire collection to access a particular object. In this case it is necessary to manage 3 system objects: one for the memory addresses of the value segments ($$ IADM), the other for the disk addresses ($$ IADD) and the last to manage the releases ($$ MARQ).

**The contiguous collections**

There is a single value segment for all objects in the collection that is created and sized once and for all when one of the collection objects is first stored. This value segment is associated with the system object $$ DESO.

**Variable length collections**

Each object must be sized: by assigning the length attribute using the JEECRA routine or by providing a length vector (shared object). In this case, 3 system objects are required: for the lengths ($$ LONG or shared object), for the lengths in the type of associated value segments ($$ LONO or &LONO in the case of a shared object) and finally for the lengths used ($$ LUTI or &LUTI in the case of a shared object).

In the case of contiguous collections, it is possible to directly access the vector of cumulative lengths (LONCUM) using the JEXATR function combined with the call to JEVEUO to obtain the address of this vector. This access allows you to avoid a call to JEVEUO per collection object. The dimension of the system object $$ LONO is incremented by 1 with respect to the length of the system object $$ LONG for this purpose.

This mechanism has been extended to scattered collections to access attributes LONMAX and LONUTI for each collection object, as accessing the attribute for each of the objects in the collection using the JELIRA function can be expensive.

**Fixed length collections**

Each object has the same dimension, this attribute can be assigned in different ways: by directly assigning the length attribute of an object in the collection or the total length attribute LONT for a contiguous collection (call to JEECRA).

**The mechanism for accessing collectibles**

Requests for access to collection objects request the system objects attached to the collection, in the same way that it is necessary to have access to system objects associated with a class when requesting simple objects. It is therefore necessary for these objects to be present in memory as soon as a request is made on one of the collection objects. The JJALLC routine is responsible for storing collection system objects in memory. They obey specific rules concerning releases because they can only be unloaded from memory when all the collectibles have themselves been unloaded (updating the disk and memory addresses). The management of shared objects is even more delicate because it is necessary to be able to prevent them from being released untimely. To this end, they receive a particular mark equal to -1.

The various queries on collection objects are based on the JE routines used for simple objects, but require the use of the synchronization functions JEXNOM, JEXNUM, or JEXATR. These functions of type CHARACTER *32 update the content of the respective commons/IDATJE/,//,//,/,/INUMJE/, and/KNOMJE/, in addition, they replace the character string associated with the name of the object JEVEUX in position 25 to 32 with the respective suffixes $$ XNOM, $ XNUM and $$ XATR. The low-level routines will then search for this information within the various commons depending on the type of access.


.. _ BM9_Les_poursuites: