shpclmove.tex

\apisummary{
    Extends  a symmetric heap block or copies the contents of the block into a
    larger block.
}

\begin{apidefinition}

\begin{Fsynopsis}
POINTER (addr, A(1))
INTEGER length, status, abort
CALL SHPCLMOVE (addr, length, status, abort)
\end{Fsynopsis}

\begin{apiarguments}
    \apiargument{INOUT}{addr}{On  entry, first word address of the block to
    change; on exit, the new address of the block if it was moved.}
    \apiargument{IN}{length}{Requested new total length in words. One word is
    \CONST{32} bits.}
    \apiargument{OUT}{status}{Status is \CONST{0} if the block was extended in
    place, \CONST{1} if it was moved, and a negative integer for the type of
    error detected.}
    \apiargument{IN}{abort}{Abort code.  Nonzero requests abort on error;
    \CONST{0} requests an error code.}
\end{apiarguments}
 
\apidescription{     
    The \FUNC{SHPCLMOVE} routine either extends a symmetric heap block if the block
    is followed by a large enough free block or copies the contents of the existing
    block to a larger block and returns a status code indicating that the block was
    moved.  This routine also can reduce the size of a block if the new length is
    less than  the old length.  All \acp{PE}  in a program must call
    \FUNC{SHPCLMOVE} with the same value of \VAR{addr} to maintain symmetric heap
    consistency; if any \acp{PE} are missing, the program hangs.
}

\apireturnvalues{}
    \apitablerow{Error Code}{Condition}
    \apitablerow{\CONST{-1} }{Length is not an integer greater than \CONST{0}}
    \apitablerow{\CONST{-2}}{ No more memory is available from the system
    (checked  if the  request  cannot  be satisfied from the available blocks on
    the symmetric heap).}
    \apitablerow{\CONST{-3}}{Address is outside the bounds of the symmetric heap.}
    \apitablerow{\CONST{-4}}{Block is already free.}
    \apitablerow{\CONST{-5}}{Address is not at the beginning of a block.}

\apinotes{
    None.
}

\end{apidefinition}