function trace ( $str='trace', $cod=1 )
        {
#-k     debug   trace
#-      trace the code path.
#-      Each time the function is invoked, it appends a record onto a global array '$trace' indexed by $cod.
#-      Multiple traces can run concurrently.
#-      Lines look like ... 123 @ thisFunction - descriptor string
#-
#-      $str    - opt   - append as a descriptor
#-      $cod    - opt   - <0 flush the array for that $cod (i.e., '-2' will flush the array for '2'
#-                      - =0 flush the whole array
#-                      - >0 append $str to index $cod's records
#-      $trace  - req'd as a global
#-
        $bound[0]['l'] = "&rarrb;";     $bound[0]['r'] = "&larrb;";
        $bound[1]['l'] = "&uhblk;";     $bound[1]['r'] = "&lhblk;";
        $bound[2]['l'] = "&rtrif;";     $bound[2]['r'] = "&ltrif;";
        global $trace;
        global $logfcb;

        if ($cod == 0)
                {
                unset ( $trace );
                }
        elseif ($cod < 0)
                {
                unset ( $trace[-$cod] );
                }
        elseif (isset($logfcb['log']['file']))
                {       # if logfile is open, assume we're putting it out there
                $ax = callingVars(1);
                if (!isset($trace[$cod])) $trace[$cod] = "Code trace: $cod<br>\n";
                $trace[$cod] .= ' ... ' . stackPlace(0) . ' ' . $ax[0]['name'] . ' [' .$str . "]\n";
                }
        else
                {       # else we're putting it to the screen
                $ax = callingVars(1);
                if (!isset($trace[$cod])) $trace[$cod] = "Code trace: $cod<br>\n";
                $trace[$cod] .= ' ... <b>' . stackPlace(0) . '</b>' .
                                ' <span style="color:blue;">' . $ax[0]['name'] . '</span>'.
                                ' &marker;<span style="color:red;">' .$str . "</span>&marker;\n";
                }

        return;
        }

?>