### 18.6.4. Subroutines

This section describes the subroutines available to a program developer, by giving a specification for each of the subroutines provided by the memory management system. A consistent approach to error handling is adopted, with character variables CERACT and CRESLT used to control and report errors. For details, see Error Conventions.

#### 18.6.4.1. Directories

##### 18.6.4.1.1. MAKDIR

          SUBROUTINE MAKDIR (CDRNAM, CERACT, CRESLT)
          CHARACTER*(*) CDRNAM, CERACT (input)
          CHARACTER*4 CRESLT (output)

This creates a new directory CDRNAM, where CDRNAM can be a full pathname (in which case it must start with ‘/‘) or it can be a relative pathname. Note that the relative pathname can include ‘.’ to indicate the current directory or ‘..’ to indicate the parent directory, just as in UNIX. However, you must be careful when using ‘..’ in the presence of linked directories.

##### 18.6.4.1.2. DELDIR

          SUBROUTINE DELDIR (CDRNAM, CERACT, CRESLT)
          CHARACTER*(*) CDRNAM, CERACT (input)
          CHARACTER*4 CRESLT (output)

This deletes the directory CDRNAM, along with all subdirectories and data areas that it contains.

##### 18.6.4.1.3. CHGDIR

          SUBROUTINE CHGDIR (CDRNAM, CERACT, CRESLT)
          CHARACTER*(*) CDRNAM, CERACT (input)
          CHARACTER*4 CRESLT (output)

This changes the current directory to CDRNAM.

Note that linked directories behave like UNIX hard links as far as changing directories is concerned. For example, suppose you have two directories ‘A1’ and ‘A2’, each with subdirectories ‘B1’ and ‘B2’, and that ‘B1’ is linked to ‘B2’:

A1/ B1 A2/ B2

Suppose that ‘A1’ is the current directory, and you perform the following sequence of commands:

          CALL CHGDIR (‘B1’, ‘STOP’, CRESLT)
          CALL CHGDIR (‘..’, ‘STOP’, CRESLT)

Then you finish up back in ‘A1’, unlike UNIX soft links, which would finish up in ‘A2’.

##### 18.6.4.1.4. CHMDIR

          SUBROUTINE CHMDIR (CDRNAM, CERACT, CRESLT)
          CHARACTER*(*) CDRNAM, CERACT (input)
          CHARACTER*4 CRESLT (output)

This changes the current directory to CDRNAM, if CDRNAM exists; otherwise it first makes the directory CDRNAM and then changes into it.

##### 18.6.4.1.5. PSHDIR

          SUBROUTINE PSHDIR (CDRNAM, CERACT, CRESLT)
          CHARACTER*(*) CDRNAM, CERACT (input)
          CHARACTER*4 CRESLT (output)

This places the name of the current directory on a stack of previous current directories, and then changes the current directory to CDRNAM. It is designed to be used in combination with POPDIR (see below).

##### 18.6.4.1.6. PSHDRH

          SUBROUTINE PSHDRH (CDRNAM, CERACT, CRESLT)
          CHARACTER*(*) CDRNAM, CERACT (input)
          CHARACTER*4 CRESLT (output)

This places the name of the current directory on a stack of previous current directories, and then changes the current directory to CDRNAM. It is designed to be used in combination with POPDIR (see below). This routine behaves the same as PSHDIR if a directory is not a link to another directory. However, if the input directory is a link, this routine follows the link so that ‘..’ is actually the parent directory of CDRNAM. With PSHDIR, ‘..’ follows the original linked directory.

##### 18.6.4.1.7. POPDIR

          SUBROUTINE POPDIR (CERACT, CRESLT)
          CHARACTER*(*) CERACT (input)
          CHARACTER*4 CRESLT (output)

This changes back to the directory stored on the top of the stack of previous current directories, and removes this directory from the stack.

If this directory no longer exists, the current directory remains unchanged, but the top entry on the stack of previous current directories will still be removed. The value of CERACT then determines whether the program continues. Note that the stack is not cleared and any subsequent call to POPDIR attempts to change to the directory given by the new top entry on the stack.

POPDIR is designed to be used in combination with PSHDIR (see above). Note that the stack of current working directories is a last-in-first-out stack, so care must be taken if nesting PSHDIR’s and POPDIR’s.

##### 18.6.4.1.8. LISDAT

          SUBROUTINE LISDAT

All subdirectories and data areas are listed (in the standard output file) for the current directory. The name of this current directory is also printed.

##### 18.6.4.1.9. PUTDIR

          SUBROUTINE PUTDIR (CURDIR, LENCD)
          CHARACTER*200 CURDIR (output)
          INTEGER LENCD (output)

The full pathname of the current directory is written into CURDIR (which should be at least of length 200 bytes). The actual number of active bytes in the full pathname is returned as LENCD.

##### 18.6.4.1.10. FNDFIL

          SUBROUTINE FNDFIL(CDRNAM, CNAME, COPTS, CFNAME, LFNAME, CLNAME, \
          LLNAME, CDTYPE, CERACT, ISIZE, JADRES, CRESLT)
          CHARACTER*(*) CDRNAM (input)
          CHARACTER*(*) CNAME (input)
          CHARACTER*(*) COPTS (input)
          CHARACTER*(*) CERACT (input)
          CHARACTER*208 CFNAME (output)
          CHARACTER*4 CDTYPE, CRESLT (output)
          CHARACTER*208 CLNAME (output)
          INTEGER ISIZE, JADRES, LFNAME, LLNAME (output)

This routine replaces the old TARLIS routine, and its call is done in very much the same way. Much more control over what is returned by this routine is provided than for TARLIS however, and the DEFAULT action is to search only in the directory CDRNAM and not recursively through subdirectories of CDRNAM.

`CDRNAM` is the directory to be searched.

`CNAME` is the filename to be searched for. The name may contain up to two wild cards for which the ‘*’ character is used as in Linux. The following are valid examples of CNAME:

`CNAME = ‘FRED’`

  Returns only files called FRED

`CNAME = ‘*DAT’`

  Returns only files ending in ‘DAT’

`CNAME = ‘FCP*’`

  Returns only files beginning in ‘FCP’

`CNAME = ‘*STR*’`

  Returns only files including the string ‘STR’

`CNAME = ‘*’`

  Returns all filenames.

Note that CNAME should be set only on the first call. FNDFIL is always initialized for a new search whenever CNAME is non-blank.

COPTS is a string holding the file system type options. All options should be prepended with a ‘-’ character, the minus sign. More than one option can be included, for example, COPTS=’-opt1 -opt2 -opt3 ....’. Valid options are:

`R`

  Search recursively through all subdirectories

`-ALL`

  Return all file types

`-DIR`

  Return directory files

`-LINK`

  Return link files

`-’DATA’[>lev | <lev]`

  Return files of data type ‘DATA’.

The optional part in [ ] after the data type option is used to specify a vulnerability level restriction on the data areas. For example:

    -INTR > All integer data areas;

`-INTR` >10 > Integer data areas with a vulnerability >10;

    -REAL <50 > Real data areas with a vulnerability <50.

Thus, to specify all vulnerable integer data areas use, ‘`-INTR>0`’. For all non-vulnerable logical files, use ‘`-LOGL<1`’.

Options are processed in order and so can be modified in the expected manner; thus, ‘`-ALL-INTR<10`’ => all files but only integer files with a vulnerability less than 10.

Note if the options string is left blank then this is the same as ‘`-ALL`’.

`CFNAME` is returned with the relative path name of the file from the directory being listed, in the form '`./d1/d2/.../filename`'.

If `CRESLT` = ‘`END`’ then there are no more data areas to be found, and so `CFNAME` will not contain the name of a new directory or data area.

Note that `CRESLT` = ‘`END`’ is treated like `CRESLT` = ‘`GOOD`’ as far as error handling is concerned, so it is not an error condition.

Once a call has produced the result `CRESLT` = ‘`END`’ or `CRESLT` = ‘`ERR`’ the next call to `FNDFIL` is treated as a first call and a new search begins.

`LFNAME` contains the length of `CFNAME` in characters, and `CDTYPE` contains the data type of `CFNAME`; this will be one of ‘`REAL`’, ‘`INTR`’, ‘`DBLE`’, ‘`LOGL`’ or ‘`CHAR`’.

`ISIZE` is the size of the data area `CFNAME`, and `JADRES` is the start address for this data area in the relevant stack.

If `ISIZE` = 0 and `LLNAME` = `0` then `CFNAME` is actually a directory. But if `ISIZE`=`0` and `LLNAME` is greater than zero, then `CFNAME` is a link to another data area or directory, in which case `CLNAME` and `LLNAME` are returned containing the name of the link, and the length of this name, respectively. When `ISIZE`=`0`, `CDTYPE` is not defined.

The following illustrates the calling sequence using FNFIL:

First call:

    CALL FNDFIL(‘Dir. name’, ’*’, ’-R -ALL’, ...)

Subsequent calls:

    CALL FNDFIL(‘ ‘, ‘ ‘,’ ‘, ...)

For the subsequent calls only the CNAME argument is checked and it must be blank otherwise a new search will be initiated.

          LOGICAL FUNCTION LDIR(CDIR)
          CHARACTER*(*) CDIR (input)

This function is true if the directory CDIR exists.

          LOGICAL FUNCTION LFIL(CFIL)
          CHARACTER*(*) CFIL (input)This function is true if the file CFIL exists

#### 18.6.4.2. Data Areas

##### 18.6.4.2.1. MAKDAT

          SUBROUTINE MAKDAT (CDANAM, CDTYPE, CERACT, ISIZE, JADRES, CRESLT)
          CHARACTER*(*) CDANAM, CERACT (input)
          CHARACTER*4 CDTYPE (input)
          INTEGER ISIZE (input)
          INTEGER JADRES (output)
          CHARACTER*4 CRESLT (output)

CDANAM can be set to either a program name or a data area name. If CDANAM is a program name, then CERACT is also set to ‘CODE’, and MAKDAT simply initializes the character string CCODE to the program name, and then returns. CCODE is then saved for future calls to MAKDAT. The program name can then be used in user friendly memory error messages.

If CDANAM is a data area name, then MAKDAT creates a new data area called CDANAM, which is of type CDTYPE (CDTYPE= 'REAL','INTR','DBLE','LOGL' or 'CHAR'). CERACT performs its usual function, and ISIZE defines the size of the new data area (for character arrays, ISIZE is the total number of bytes required).

The start address in the appropriate global stack is returned as JADRES.

Note that MAKDAT may delete vulnerable data areas if there is no room available in the stack for a new data area (see VULDAT below).

If MAKDAT fails due to lack of space on one of the stacks, that is, CRESLT = ‘FULL’, the following message is sent to standard output, providing CERACT is not set to ‘SKIP’:

`*** INSUFFICIENT MEMORY ALLOCATED ***`

Action required:

Depending on what program is running, there then follows a message relating to what memory stack is full. If the program is ANSYS CFD-Flo, then the following message is shown:

`Re-run CFX-Pre and increase the CDTYPE stack memory factor. Use the Workspace Sizes menu under Advanced Control of ANSYS CFD-Flo Parameters.`

Where CDTYPE is one of ‘CHAR’, ‘DBLE’, ‘INTR’, ‘LOGL’, or ‘REAL’, to indicate for which data type MAKDAT has failed. Otherwise, for other programs, the following message is shown:

`Contact the CFDS Customer Helpline giving the following details`

If MAKDAT fails due to the file catalogue being full, that is, CRESLT = ‘FCAT’, the following message is sent to standard output, providing CERACT is not set to ‘SKIP’:

`>> Insufficient memory allocated. Try increasing file catalogue size.`

To increase the catalogue size, see Starting the CFX-Solver from the Command Line in the CFX-Solver Manager User's Guide and Configuring Memory for the CFX-Solver in the CFX-Solver Manager User's Guide.

##### 18.6.4.2.2. MAKVEC

          SUBROUTINE MAKVEC (CDANAM, CDTYPE, CERACT, LENVEC,ISIZE, JADRES, CRESLT)
          CHARACTER*(*) CDANAM, CERACT (input)
          CHARACTER*4 CDTYPE (input)
          INTEGER LENVEC (input)
          INTEGER ISIZE (input)
          INTEGER JADRES (output)
          CHARACTER*4 CRESLT (output)

This routine is identical to MAKDAT in every respect except that instead of creating a data area of length ISIZE stack words it creates a data area of ISIZE*LENVEC stack words. The vector word length, LENVEC stack words, is stored in the MMS. This is particularly useful for character string arrays; LENVEC is then the string length in characters of the character array. Note this is important when using PEEKCA and POKECA.

##### 18.6.4.2.3. GRBSTK

          SUBROUTINE GRBSTK (CDANAM, CDTYPE, CERACT, ISIZE, JADRES, CRESLT)
          CHARACTER*(*) CDANAM, CERACT (input)
          CHARACTER*4 CDTYPE (input)
          INTEGER ISIZE (output)
          INTEGER JADRES (output)
          CHARACTER*4 CRESLT (output)

This routine is identical to MAKDAT except that it returns a pointer to the largest free data area of the required type that is available. ISIZE is returned with the data area size in words. If no free areas exist, then the largest vulnerable data area is used.

##### 18.6.4.2.4. SQZDAT

          SUBROUTINE SQZDAT (CDANAM, CERACT, ISIZE, CRESLT)
          CHARACTER*(*) CDANAM, CERACT (input)
          INTEGER ISIZE (input)
          CHARACTER*4 CRESLT (output)

This shrinks the data area CDANAM, reducing its length to ISIZE, which must be no larger than the original length of the data area.

##### 18.6.4.2.5. RESIZE

          SUBROUTINE RESIZE (CDANAM, CERACT, ISIZE, CRESLT, CZ, DZ, IZ, LZ, RZ)
          CHARACTER*(*) CDANAM, CERACT (input)
          INTEGER ISIZE (input)
          CHARACTER*4 CRESLT (output)
          CHARACTER CZ(*) (input/output)
          DOUBLE PRECISION DZ(*) (input/output)
          INTEGER IZ(*) (input/output)
          LOGICAL LZ(*) (input/output)
          REAL RZ(*) (input/output)

This resizes the data area CDANAM, to the new size ISIZE, which may be larger or smaller than the original length of the data area.

NOTE that the address of CDANAM within the stack may be changed as a result of calling RESIZE.

##### 18.6.4.2.6. DELDAT

          SUBROUTINE DELDAT (CDANAM, CERACT, CRESLT)
          CHARACTER*(*) CDANAM, CERACT (input)
          CHARACTER*4 CRESLT (output)

This deletes the data area CDANAM.

##### 18.6.4.2.7. LOCDAT

          SUBROUTINE LOCDAT (CDANAM, CDTYPE, CERACT, ISIZE, JADRES, CRESLT)
          CHARACTER*(*) CDANAM, CERACT (input)
          INTEGER ISIZE, JADRES (output)
          CHARACTER*4 CDTYPE, CRESLT (output)

This subroutine locates an existing data area CDANAM, and provides its type CDTYPE, size ISIZE, and address JADRES.

Note that if CDANAM is a vulnerable data area, then LOCDAT makes it safe again until the next call to VULDAT for CDANAM.

##### 18.6.4.2.8. INFDAT

          SUBROUTINE INFDAT (CDANAM, CDTYPE, CERACT, LENVEC, ISIZE, JADRES, LEVVUL,CRESLT)
          CHARACTER*(*) CDANAM, CERACT (input)
          INTEGER LENVEC,ISIZE, JADRES,LEVVUL (output)
          CHARACTER*4 CDTYPE, CRESLT (output)

This subroutine locates an existing data area CDANAM, and provides its type CDTYPE, vector word length, size ISIZE, in units of the vector word length, address JADRES and vulnerability level LEVVUL. If a character string array had been set up using MAKVEC with 20 strings of 10 character string length, then LENVEC would be returned with 10 and ISIZE with 20 a total length of 200 characters.

Note that unlike LOCDAT, this routine does NOT affect the vulnerability of a data area this is a pure inquiry routine.

#### 18.6.4.3. Renaming And Linking

##### 18.6.4.3.1. RENAM

          SUBROUTINE RENAM (COLDNM, CNEWNM, CERACT, CRESLT)
          CHARACTER*(*) COLDNM, CNEWNM, CERACT (input)
          CHARACTER*4 CRESLT (output)

The data area or directory COLDNM is given the new name CNEWNM. The subroutine will fail if CNEWNM already exists.

N.B. This routine was originally called RENAME. It has been renamed RENAM to avoid a clash with the UNIX system routine rename on some platforms.

##### 18.6.4.3.2. MAKLNK

          SUBROUTINE MAKLNK (COLDNM, CNEWNM, CERACT, CRESLT)
          CHARACTER*(*) COLDNM, CNEWNM, CERACT (input)
          CHARACTER*4 CRESLT (output)

The data area or directory COLDNM is linked to a new data area or directory CNEWNM, that is, it is given the additional name CNEWNM. If CNEWNM is subsequently deleted (using DELLNK), then COLDNM still survives under its original name. However, if instead COLDNM is subsequently deleted (using DELDAT or DELDIR) then CNEWNM is also deleted automatically, so be careful with links! It is important to be aware of what may happen to the target of a linked data area.

Note that if COLDNM is actually a link, rather than a data area or directory, then MAKLNK operates as if COLDNM were replaced by the name of the data area or directory to which it is linked. Thus, there is never a link to another link; there are only links to data areas or directories.

Note that, as far as changing directories is concerned, linked directories behave as UNIX hard links, as explained in CHGDIR.

##### 18.6.4.3.3. DELLNK

          SUBROUTINE DELLNK (CLNNAM, CERACT, CRESLT)
          CHARACTER*(*) CLNNAM, CERACT (input)
          CHARACTER*4 CRESLT (output)

The data area or directory CLNNAM is assumed to have been created by a call to MAKLNK (with CNEWNM=CLNNAM), and this call to DELLNK will delete that link.

#### 18.6.4.4. Copying

##### 18.6.4.4.1. COPDAT

          SUBROUTINE COPDAT (CDFROM, CDTO, CERACT, CRESLT, CZ, DZ, IZ, LZ, RZ)
          CHARACTER*(*) CDFROM, CDTO, CERACT (input)
          CHARACTER CZ(*) (input/output)
          DOUBLE PRECISION DZ(*) (input/output)
          INTEGER IZ(*) (input/output)
          LOGICAL LZ(*) (input/output)
          REAL RZ(*) (input/output)
          CHARACTER*4 CRESLT (output)

This subroutine copies one data area to another. CDFROM is the name of the original data area, and this must already exist. A new data area called CDTO is created, of the same size and type as CDFROM, and all data from CDFROM is copied to CDTO. If CDFROM is linked to another data area, then this is taken as the source for the data. The subroutine fails if CDTO already exists.

It is necessary to pass the global stacks CZ, DZ, IZ, LZ, RZ to this subroutine.

##### 18.6.4.4.2. COPDIR

          SUBROUTINE COPDIR (CDFROM, CDTO, CERACT, CRESLT, CZ, DZ, IZ, LZ, RZ)
          CHARACTER*(*) CDFROM, CDTO, CERACT (input)
          CHARACTER CZ(*) (input/output)
          DOUBLE PRECISION DZ(*) (input/output)
          INTEGER IZ(*) (input/output)
          LOGICAL LZ(*) (input/output)
          REAL RZ(*) (input/output)
          CHARACTER*4 CRESLT (output)

This subroutine copies a whole directory (CDFROM) and all its subdirectories to another, new, directory CDTO. The names of all subdirectories and data areas are recreated in the new directory. COPDIR will work if CDFROM is linked to another directory, but the subroutine will fail if CDTO already exists.

It is important to note that any data areas or subdirectories of CDFROM, which are links, will not be copied.

#### 18.6.4.5. Setting and Reading Individual Values

##### 18.6.4.5.1. POKECA

    SUBROUTINE POKECA (CDANAM, JADRES, CVALUE, CERACT, CRESLT, CZ)

##### 18.6.4.5.2. POKECS

    SUBROUTINE POKECS (CDANAM, CVALUE, CERACT, CRESLT, CZ)

##### 18.6.4.5.3. POKED

    SUBROUTINE POKED (CDANAM, JADRES, DVALUE, CERACT, CRESLT,DZ)

##### 18.6.4.5.4. POKEI

    SUBROUTINE POKEI (CDANAM, JADRES, IVALUE, CERACT, CRESLT,IZ)

##### 18.6.4.5.5. POKEL

    SUBROUTINE POKEL (CDANAM, JADRES, LVALUE, CERACT, CRESLT,LZ)

##### 18.6.4.5.6. POKER

          SUBROUTINE POKER (CDANAM, JADRES, RVALUE, CERACT, CRESLT, RZ)
          CHARACTER*(*) CDANAM, CERACT (input)
          CHARACTER*4 CRESLT (output)
          CHARACTER*(*) CVALUE (input)
          DOUBLE PRECISION DVALUE (input)
          INTEGER JADRES, IVALUE (input)
          LOGICAL LVALUE (input)
          REAL RVALUE (input)
          CHARACTER CZ(*) (output)
          DOUBLE PRECISION DZ(*) (output)
          INTEGER IZ(*) (output)
          LOGICAL LZ(*) (output)
          REAL RZ(*) (output)

These POKE subroutines are designed for setting a value at a single address, for a scalar or for one entry of an array, which is stored in the global stacks. This saves the programmer the job of locating the data area, and assigning a value. There is a separate subroutine for each Fortran variable type.

CDANAM is the name of the data area and JADRES is the position within the array (assuming CDANAM is an array) that is to be given a value. Note that if the data area CDANAM is a scalar, rather than an array, then JADRES is not used by the POKE subroutine.

CVALUE (or DVALUE and so on) is the actual value that is to be assigned.

The relevant stack is passed (CZ, DZ, and so on) as an argument, along with the usual error handling flags CERACT and CRESLT.

In the case of character strings there are two subroutines, POKECA for arrays and POKECS for scalar (single string) data areas. When using POKECA, it is important to have the correct length for the string CVALUE, as one element of the character array. As with the other POKE subroutines, JADRES is simply the location within the character array where the value CVALUE will be set. For example, for an array CHARACTER*2 CEXAMP(3) (total length 6 bytes), if you want to set the last entry CEXAMP(3) to be ‘AB,’ then you must set CDANAM to be CEXAMP, JADRES to be 3 and CVALUE to be ‘AB.’ If CVALUE is actually a local variable in the calling subroutine, then it must be declared as CHARACTER*2.

For string arrays created with MAKVEC, the string length is stored in the MMS and POKECA uses that information. In this case, the restrictions on CVALUE are reduced, it can be any length less than equal to the length of a string in the string array. If CVALUE is shorter than the string length of the array, then padding with blanks is used. If CVALUE has a length greater than the array string length, then POKECA fails. Note that INFDAT can be used to determine the array size and string length.

Clearly there is no need for the argument JADRES in the POKECS subroutine, because CDANAM will be a single character string. If CDANAM has length greater than CVALUE, then the string is completed with blanks, while if CVALUE has length greater than CDANAM, then the POKECS fails. Note that calling POKECS for a character array CDANAM will have the effect of filling most of the array with blanks, so caution should be exercised.

##### 18.6.4.5.7. PEEKCA

    SUBROUTINE PEEKCA (CDANAM, JADRES, CVALUE, CERACT, CRESLT, CZ)

##### 18.6.4.5.8. PEEKCS

    SUBROUTINE PEEKCS (CDANAM, CVALUE, CERACT, CRESLT, CZ)

##### 18.6.4.5.9. PEEKD

    SUBROUTINE PEEKD (CDANAM, JADRES, DVALUE, CERACT, CRESLT, DZ)

##### 18.6.4.5.10. PEEKI

    SUBROUTINE PEEKI (CDANAM, JADRES, IVALUE, CERACT, CRESLT, IZ)

##### 18.6.4.5.11. PEEKL

    SUBROUTINE PEEKL (CDANAM, JADRES, LVALUE, CERACT, CRESLT, LZ)

##### 18.6.4.5.12. PEEKR

          SUBROUTINE PEEKR (CDANAM, JADRES, RVALUE, CERACT, CRESLT, RZ)
          CHARACTER*(*) CDANAM, CERACT (input)
          CHARACTER*4 CRESLT (output)
          CHARACTER*(*) CVALUE (output)
          DOUBLE PRECISION DVALUE (output)
          INTEGER IVALUE (output)
          INTEGER JADRES (input)
          LOGICAL LVALUE (output)
          REAL RVALUE (output)
          CHARACTER CZ(*) (input)
          DOUBLE PRECISION DZ(*) (input)
          INTEGER IZ(*) (input)
          LOGICAL LZ(*) (input)
          REAL RZ(*) (input)

Corresponding to the POKE subroutines, there is this set of PEEK subroutines. These are designed for reading individual values from array data areas, or scalar data areas (that is, of length 1) from the global stacks. Again, there is a separate subroutine for each Fortran variable type, with two subroutines for characters. CDANAM is the name of the data area, with JADRES the array entry, hence, the actual value CVALUE (or DVALUE and so on) is to be obtained.

A programmer using PEEKCA must know the size of each string in the character array CDANAM, and must declare CVALUE to be of this length in the calling subroutine.

For string arrays created with MAKVEC, the string length is stored in the MMS and PEEKCA uses that information. In this case, the restrictions on CVALUE are reduced, it can be any length greater than equal to the length of a string in the string array. If CVALUE is longer than the string length of the array, then padding with blanks is used. If CVALUE has a length less than the array string length, then PEEKCA fails. Note that INFDAT can be used to determine the array size and string length.

When using PEEKCS the programmer may not necessarily know the length of CDANAM. In this case, CVALUE should be declared sufficiently large and LOCDAT must be used to obtain the actual length required for CVALUE. After the call to PEEKCS, CVALUE must be truncated to the correct length.

#### 18.6.4.6. Name lists

##### 18.6.4.6.1. NAMLST

          SUBROUTINE NAMLST (COM, CLIST, IENTRY, CVALUE, NCVAL, CERACT, RESLT, CZ, IZ)
          CHARACTER COM*(*) (input)
          CHARACTER CLIST*(*) (input)
          INTEGER IENTRY (input/output)
          CHARACTER CVALUE*(*) (input/output)
          INTEGER NCVAL (output)
          CHARACTER CERACT*(*) (input)
          CHARACTER CRESLT*(4) (output)
          CHARACTER CZ(*)*(1) (input/output)
          INTEGER IZ(*) (input/output)

A name list is simply a long character string consisting of a set of substrings. Each substring corresponds to a name and may be of arbitrary length. NAMLST enables you to treat the name list as if it were an array of strings, each string being of arbitrary length. The main advantage of using NAMLST is the potential for saving memory if the names in the list are of widely varying length. Note, however, that no space will be saved unless the mean length of a name is greater than 8 characters.

COM is a command string that takes the following possible values: COMPRESS, CREATE, DELETE, PEEK, POKE & SIZE. This string controls the operation of the routine in a, hopefully, self evident way.

CLIST is the name of the character data area to be used to hold the name list. Note that CLIST MUST be created using the CREATE command of NAMLST.

IENTRY is the array address to be used for COMPRESSing, PEEKing or POKEing an entry in the name list. In addition, IENTRY is used to set the maximum number of entries in the name list on creation and is returned with this number if the SIZE command is used.

CVALUE is used to hold string values for PEEKing and POKEing. For a PEEK CVALUE must be long enough to hold the entire entry. For a POKE, trailing spaces in CVALUE are ignored.

NCVAL is used to return the active length of CVALUE, which is the length after trailing spaces have been removed, when PEEKing.

If COM equals COMPRESS, then the IENTRY’th value in the list is removed and then the entries above have their entry number reduced by one; that is, entry IENTRY+n becomes IENTRY+n-1.

If COM equals CREATE, then a new name list, CLIST, is created with IENTRY possible entries.

If COM equals DELETE, then the name list, CLIST, is deleted.

If COM equals PEEK, then the IENTRY’th name in the list is returned in CVALUE(1:NCVAL) provided CVALUE is at least NCVAL characters long, where NCVAL is the active length in characters of the IENTRY’th name. If the IENTRY’th name has not yet been set, then CRESLT will be returned with NONE.

If COM equals POKE, then the IENTRY’th name in the list is overwritten with CVALUE(1:NACTIV), where NACTIV is the active length of CVALUE. Note that if the length of the new entry differs from the original, then CLIST has to be restructured incurring a CPU penalty. If an entire name list is to be filled, then the first entry should be POKEd in first, the second second, and so on, for maximum efficiency.

If COM equals SIZE then IENTRY is returned with the maximum possible number of entries for the name list.

Note that NAMLST uses the vertical bar character, "|", as a separator in the CLIST array and so no entry should contain this character.

#### 18.6.4.7. Memory Management Statistics

##### 18.6.4.7.1. GETMMS

          SUBROUTINE GETMMS (CTYPE, CERACT, LENINF, INFO, CRESLT)
          CHARACTER*(*) CTYPE, CERACT (input)
          CHARACTER*4 CRESLT (output)
          INTEGER LENINF (input)
          INTEGER INFO (output)

This subroutine is used to obtain memory management statistics. You should set LENINF to be at least 25, and provide a local array INFO in the calling subroutine, which has dimension at least LENINF.

The character CTYPE should be set as one of 'CLCK,' 'FILE,' 'SYS,' 'REAL,' 'INTR,' 'DBLE,' 'LOGL' or 'CHAR' and this determines the information that will be returned in the INFO array.

If CTYPE = ‘CLCK’ then information is returned on the total number of memory management system calls so far:

Number of calls = *

where I=INFO(1) and J=INFO(2).

If CTYPE = ‘FILE’ then information is returned on the number of memory management system files (data areas, directories, and so on):

INFO(1) is the number of data areas present now.

INFO(2) is the peak number of data areas used so far.

INFO(3) = I and INFO(4) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(5) is the number of directories present now.

INFO(6) is the peak number of directories used so far.

INFO(7) = I and INFO(8) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(9) is the number of link files present now.

INFO(10) is the peak number of link files used so far.

INFO(11) = I and INFO(12) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(13) is the total number of files (data areas + directories + link files) present now.

INFO(14) is the peak number of files used so far.

INFO(15) = I and INFO(16) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

If CTYPE = ‘SYS’ then information is returned on the system limit statistics:

INFO(1) is the maximum number of files permitted at any one time.

INFO(2) is the maximum number of free data areas permitted at any one time.

INFO(3) is the maximum permitted length of a filename in characters.

INFO(4) is the maximum number of directories allowed in a full pathname.

INFO(5) is the maximum vulnerability level allowed.

If CTYPE='CHAR,' 'DBLE,' 'INTR,' 'LOGL' or ' REAL' then statistics are returned just for data areas of that particular data type (namely character, double precision, integer, logical or real respectively):

INFO(1) is the number of data areas present now.

INFO(2) is the peak number of data areas used so far.

INFO(3) = I and INFO(4) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(5) is the address space used by data.

INFO(6) is the peak address space used so far.

INFO(7) = I and INFO(8) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(9) is the number of vulnerable data areas present now.

INFO(10) is the peak number of vulnerable data areas set so far.

INFO(11) = I and INFO(12) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(13) is the address space used by vulnerable data.

INFO(14) is the peak vulnerable address space set so far.

INFO(15) = I and INFO(16) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(17) is the number of free areas present now.

INFO(18) is the peak number of free areas created so far.

INFO(19) = I and INFO(20) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(21) is the free address space available now.

INFO(22) is the minimum amount of free address space available so far.

INFO(23) = I and INFO(24) = J, giving the number of memory management calls made when this peak usage occurred (using the * formula above).

INFO(25) is the number of vulnerable data areas deleted by the memory management system (to make space for new data) so far.

For all values of CTYPE, if MMSTAT is in an error condition no statistics are available, but if LENINF is at least 3, then the following will be returned:

INFO(1) = NUMERR, the error condition flag in MMSTAT.

INFO(2) = I and INFO(3) = J, giving the number of memory management calls made so far (using the * formula above).

##### 18.6.4.7.2. WSTAT

    SUBROUTINE WSTAT

This subroutine prints long memory management system statistics to standard output. These consist of all data available from subroutine GETMMS, arranged in tabular form where appropriate.

Release 18.2 - © ANSYS, Inc. All rights reserved.