Procedure

     LNKAN  ( LNK, allocate node )

     SUBROUTINE LNKAN ( POOL, NEW )

Abstract

     Allocate a node in a doubly linked list pool.

Required_Reading

     None.

Keywords

     LIST

Declarations

     IMPLICIT NONE

     INTEGER               LBPOOL
     PARAMETER           ( LBPOOL = -5 )

     INTEGER               POOL ( 2,  LBPOOL : * )
     INTEGER               NEW

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     POOL      I-O  A doubly linked list pool.
     NEW        O   Number of new node that was allocated.
     LBPOOL     P   Lower bound of pool column indices.

Detailed_Input

     POOL     is a doubly linked list pool.

Detailed_Output

     POOL     is the input pool, with the following
              modifications:

                 -- NEW is an allocated node: both the forward
                    and backward pointers of NEW are -NEW.

                 -- The node that was the successor of NEW on
                    input is the head of the free list on output.


     NEW      is the number of the newly allocated node.

Parameters

     LBPOOL   is the lower bound of the column indices of the POOL
              array. The columns indexed LBPOOL to 0 are reserved
              as a control area for the pool.

Exceptions

     1)  If no free nodes are available for allocation, the error
         SPICE(NOFREENODES) is signaled.

Files

     None.

Particulars

     In a doubly linked list pool, an `allocated node' is one that has
     been removed from the free list. An allocated node may be linked
     to other nodes or may be unlinked; in the latter case, both the
     forward and backward pointers of the node will be the negative of
     the node number.

     A node must be allocated before it can be linked to another
     node.

Examples

     1)  Let POOL be a doubly linked list pool. To build a new list
         of ten nodes, the code fragment below can be used:

            C
            C     We'll use LNKILA ( LNK, insert list after
            C     a specified node ) to add nodes to the tail of the
            C     list.
            C
                  PREV = 0

                  DO I = 1, 10

                     CALL LNKAN  ( POOL, NODE       )
                     CALL LNKILA ( PREV, NODE, POOL )
                     PREV = NODE

                  END DO


     2)  In this version of example (1), we check that a sufficient
         number of free nodes are available before building the list:

            C
            C     Make sure we have 10 free nodes available.
            C     Signal an error if not. Use LNKNFN to obtain
            C     the number of free nodes.
            C
                  IF ( LNKNFN(POOL) .LT. 10 ) THEN

                     CALL SETMSG ( 'Only # free nodes are available '//
                 .                 'but 10 are required.'            )
                     CALL ERRINT ( '#', LNKNFN(POOL)                 )
                     CALL SIGERR ( 'POOL_TOO_SMALL'                  )
                     RETURN

                  END IF

                     [ Build list ]
                           .
                           .
                           .

Restrictions

     1)  Linked list pools must be initialized via the routine
         LNKINI. Failure to initialize a linked list pool
         will almost certainly lead to confusing results.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 1.0.1, 24-NOV-2021 (JDR)

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.0.0, 19-DEC-1995 (NJB) (WLT)