Next: 5 Diverse utilities Up: 4 Data Structures Prev: 4.1 Utilization Index Contents

4.2 Programming

The programmer must know the internal presentation of the DS, as well as the utilities manipulating them.

4.2.1 Internal representation of a DS

A DS is a set of arrays residing in main or secondary memory. The significance of the information contained in these arrays depend on the type of DS (Part iii). In this manner, a NOPO type DS contains a mesh, a MUA type DS contains a "skyline" matrix, etc.

This section describes the names of these arrays and their respective contents.

Identification of arrays in a DS

When an array is present in main memory, it forms part of a DS and a dynamic array. Its name is formed of four characters:

• the two first characters of the DS type,
• the character NUMALP(NI) (p. ), where NI is the DS level, and
• the character NUMALP(I) (p. ), where I is the array row (counted from 0).

For example, when a MAIL type DS with level 0 is read into main memory, 22 dynamic arrays are present: MA00, MA01, ..., MA09, MA0A, MA0B, ..., MA0L.

The names, addresses and lengths of all these arrays are contained in a unique array, of which the name ends with a percentage character (in our example, MA0%).

In addition, the programmer has the possibility to create arrays associated with the DS. These arrays are referenced by Array 1 (see below) and are manipulated by the various utilities at the same time as the other arrays. This enables the transfer of information between specific modules.

Whatever the DS type, the significance of arrays %, 0 and 1 is always the same. Those of the other arrays present some similarities. The description of all these arrays is given below.

Array

This array is used when the DS is in main memory. It contains 1 + 3 n integers, where n is the number of dynamic arrays which form the DS (without counting Array % and the associated arrays). Some of these integers in fact contain 4 characters, coded with the aid of utility ICHAR4 (p. ). The following description gives, for each integer, its traditional Fortran identifier, its length and its contents.

• NEtysd (1 integer): number of records already read on disk, with sequential or direct access (little used).
• Loop i from 1 to n
  • N (1 4 characters): name of the dynamic array in row (i-1).
  • IA (1 integer): address of this array in M.
  • L (1 integer): length (in words) of this array
• End of loop

Array 0

This array contains 32 integers:

• NTITRE (20 4 characters): title of the DS (the title describes the problem under consideration to the user when the DS is created).
• NDATE (2 4 characters): date of creation of the DS.
• NOMCRE (6 4 characters): name of the creator of the DS.
• NTYSD (1 4 characters): DS type.
• NI (1 integer): DS level at the time of the last write (unused).
• NETAT (1 integer):] DS "status number" (unused).
• NTASD (1 integer):] number of arrays associated with the DS.

Array 1

If NTASD = 0 (see "Array 0"), then this array is absent. If not, it occupies 22 NTASD integers and contains the description of the arrays associated with the DS:

• Loop i from 1 to NTASD
  • NTAB (1 4 characters): name of i-th associated array.
  • IATAB (1 integer): address of this array in M.
  • LTAB (1 integer): number of words in this array.
  • NTYTAB (1 integer): array type.
  • COMTAB (18 4 characters): comment regarding the contents of this array.
• End of loop

Array 2

This array contains the general information (for example: the number of elements, the number of degrees of freedom, the length of the arrays which follow, etc.).

Arrays 3, 4, ...

These arrays contain, either "pointers" to the arrays which follow, or the values themselves (for example: mesh point coordinates, mesh coefficients, etc.).

Associated arrays

The number and the contents of the associated arrays are totally dependent on the programmer.

4.2.2 Utilities required by the programmer

During the programming of a new module, a certain number of utilities are necessary for the manipulation of the DS.

Generally speaking, a module reads a IDS, allocates the arrays that will constitute the ODS, calls an algorithms, and writes the ODS (section 1.7.2). The manipulation operations of the DS are done with the help of utilities: INICSD, SDREST and SDSAUV.

During the creation of a new DS, utilities COPISD, COTASD and INTAB0 can also be called.

All these utilities manipulate Array % of the DS under consideration (section 4.2.1) and a copy of this array at the same time. The first is a dynamic array of which the name is contained in variable NC and the address in variable IC. The second is found in a classical Fortran array, declared by the programmer, which is traditionally called NZ. In the remainder, these two arrays are respectively called array % and array NZ.

Utility COPISD

SUBROUTINE COPISD( , , , , , , , , )

INTEGER M(*), NTAB, NI1, NC1, IC1, NI2, NC2, IC2

CHARACTER*4 TYSD

This utility copies the NTAB first arrays from DS 1 to DS 2.

Let n be the total number of arrays in DS 1 (Part iii of this user guide gives the total number of arrays for a given type of DS).

NTAB = n corresponds to a total copy, and NTAB < n, to a partial copy.

Utility COTASD

SUBROUTINE COTASD( , , , , , )

INTEGER M(*), NTAC, NBTASD, NTAB1, IATAB1, LTAB1

This utility creates the arrays associated with a DS. It allocates NTAC associated arrays, reads them in free format, and creates Array 1 of the DS.

NBTASD is the total number of associated arrays. NTAC is equal to NBTASD, except in the exceptional case where the arrays are associated by program.

NTAB1, IATAB1 and LTAB1 are respectively the name, address and length of Array 1 in the DS.

Utility INICSD

SUBROUTINE INICSD( , , , , , , )

INTEGER M(*), NI, NZ(LZ), LZ, NC, IC

CHARACTER*4 TYSD

This utility initializes array NZ in an ODS, i.e:

1. Construct the identifier of Array % and search for a dynamic array with this name.
2. 1. If the array exists, it is copied into array NZ.
   2. If the array does not exist, array NZ is initialized as follows: the identifiers of the array names are constructed from the type of DS and its level (section 4.2.1) ; the others are set to zero (addresses and lengths).

Utility INTAB0

SUBROUTINE INTAB0( , , , )

CHARACTER*4 TYSD

INTEGER NI, NBTASD, NTAB0(32)

This utility initializes the 32 elements of array NTAB0, where Array 0 of the new DS has NBTASD associated arrays.

Utility SDREST

SUBROUTINE SDREST( , , , , , , , )

INTEGER M(*), NF, NI, NZ(LZ), LZ, NC, IC

CHARACTER*4 TYSD

This utility restores an IDS, i.e:

1. 1. If NF 0, allocate (utility READRE, p. ) and read (instruction READ) the arrays of the DS.
   2. If NF = 0, verify that all the arrays of the DS are already in main memory.
2. Update Arrays % and NZ.

In certain cases, SDREST only reads the first arrays in the DS (see section "DS of Category 1 or 2" below).

Utility SDSAUV

SUBROUTINE SDSAUV( , , , , , , , , )

INTEGER M(*), NF, NI, NZ(LZ), LZ, NC, IC, NMO

CHARACTER*4 TYSD

This utility saves a DS, i.e:

1. IF NF , write (command WRITE) the arrays of the DS.
2. Allocate array % (utility READRE, p. ), and copy array NZ into this dynamic array. ( This operation is done by utility SAUCSD, which can also be called directly when NF = 0.)

In certain cases, SDSAUV only writes the first arrays of the DS (see section "DS of Category 1 or 2" below).

Example: manipulation of an IDS and an ODS

The form of a model transforming an IDS AMAT into an ODS MUA is the following: 

      SUBROUTINE TAMMUA(M, NFAMAT, NIAMAT, NFMUA, NIMUA)

C --- M : SUPER-ARRAY
C --- NFAMAT, NIAMAT : FILE AND LEVEL OF THE IDS AMAT
C --- NFMUA,  NIMUA  : FILE AND LEVEL OF THE ODS MUA

      INTEGER M(*)
      INTEGER NZMUA(19),NZAMAT(22)
      CHARACTER KINFO*80, CHAR4*4

 1000 FORMAT(1X,78('&')/' MODULE TAMMUA : ',20A4/1X,78('&'))

C --- PRINT THE TITLE

      IMPRIM = IINFO('I')
      IMPRE  = IINFO('BAVARD')
      IF (IMPRE.NE.0) WRITE (IMPRIM,1000) KINFO('TITRE')

C --- RESTORE THE IDS AMAT

      CALL SDREST(M,'AMAT',NFAMAT,NIAMAT,NZAMAT,22,NCAMAT,ICAMAT)

C --- GET THE NECESSARY ADDRESSES

      IAMA0 = NZAMAT(3)
      IAMA1 = NZAMAT(6)
      IAMA2 = NZAMAT(9)
      ...

C --- ALLOCATE THE ARRAYS OF THE ODS MUA

      CALL INICSD(M,'MUA ',NIMUA,NZMUA,19,NCMUA,ICMUA)
      NZMUA(4) = 32
      CALL READRE(1,CHAR4(NZMUA(2)),NZMUA(3),NZMUA(4),M,NRET)
      ...

C --- CALL THE ALGORITHM

      CALL ALGO(M(IAMA2), M(NZMUA(3)), ...)

C --- SAVE THE ODS MUA

      CALL SDSAUV(M,'MUA ',NFMUA,NIMUA,NZMUA,19,NCMUA,ICMUA,I)
      END

      SUBROUTINE ALGO(AMA2, MUA0, ...)
C --- ALGORITHM CALLED BY MODULE TAMMUA
      INTEGER AMA2(10), MUA0(32), ...
      NTDL   = AMA2(1)
      NTY    = AMA2(2)
      NOE    = AMA2(8)
      MUA0(32) = ...
      ...
      END

Remark

A widespread trick, which is to be avoided, consists of adding the COMMON and EQUIVALENCE commands. For example:

 

C --- PROGRAMMING NOT ADVISABLE !!! 

      INTEGER NZMUA(19)
      COMMON /ALMUA/ NEMUA,
     &   NMUA0, IAMUA0, LMUA0, NMUA1, IAMUA1, LMUA1,
     &   NMUA2, IAMUA2, LMUA2, NMUA3, IAMUA3, LMUA3,
     &   NMUA4, IAMUA4, LMUA4, NMUA5, IAMUA5, LMUA5
      EQUIVALENCE (NZMUA(1), NEMUA)

The EQUIVALENCE command allows us to write NMUA0, IAMUA0, LMUA0, ... rather than NZMUA(2), NZMUA(3), NZMUA(4), ... However, the above programming does not indicate clearly that array NZMUA is modified itself.

The COMMON /ALMUA/ command allows all the sub-programs to access array NZMUA. However, when several DS of the same type are in use, array NZ may be deleted involuntarily, and it furthermore becomes impossible to parallelize the program.

DS of Category 1 or 2

There are in fact two DS categories:

Category 1:

all the arrays are present when the DS is in main memory.

(DS of type BDCL, FORC, GEOM, MILI, NOPO, see Part iii).

Category 2:

only some arrays may be present when the DS is in main memory.

(DS of type AMAT, ATRI, B, COOR, MUA, TAE, TYNO, VVPR, see Part iii).

The functioning of the utilities SDREST (p. ) and SDSAUV (p. ) is slightly different for a category 2 DS, :

• On entry, SDREST only reads the first arrays of the DS. These arrays contain information used for the arrays which follow.

• On exit, SDSAUV only writes the first arrays of the DS. The arrays which follow must be written directly using the WRITE command. In addition, when the DS is written completely, array % must be updated in order to make the DS coherent in main memory. This operation is done by a new call to SDSAUV, with NF= 0 as a parameter.