12. Troubleshooting (*)

Fatal errors are caught by most NEMO programs by calling the function error; it reports the name of the invoked program and some offending text that was the argument to the function, and then exits. If the $ERROR level is larger than 0, an error call can postpone the exit for the specified amount of times. If the $DEBUG level is positive, programs also produce a coredump, which can be further examined with local system utilities such as {it adb(1)} or {it dbx(1)}. Most of the error messages should be descriptive enough, but a list is being compiled for the somewhat less obvious ones.

Another annoying feature can be large amount of environment variables used by packages. NEMO is no exception. In Section~ref{s-envvar} below all of the environment variables used by NEMO are listed and their functionality. Sometimes they interfere if used in conjunction with other packages.

12.1. List of Run Time Errors

This section presents an alphabetical list of some of the fatal error messages, as generated by error(3NEMO) Although this list is not meant to be complete, it hopes to report on the most obscure errors found when using NEMO, and their possible cures. The ones not listed here should be descriptive enough to guide the user to a solution. Sometimes execution errors can be better understood when the DEBUG environment variable is set to a high(er) value, or the debug= system keyword is added to the command-line. See Appendix~ref{a:iface} on it’s use.

Now the list of error messages and their possible cures:

assertion failed: file f line n

The program was compiled with an active {it assert(2)} macro. An expression was expected to be true at this point in the program. Program exits when this was not the case. An infamous failed assertion is {tt file load.c line 91} or thereabouts, part of the hackcode1 N-body integrator. Two particles were too close (or on top of each other) such that space could not be subdivided within 32 levels of the oct tree. There is no good solution to this problem.

findstream:     No free slots

Too many open files. Either the program didn’t cleanup (close) its files after usage, or your current application really needs more than the default 16 which is {tt #define}d in {tt filesecret.h} by the macro {tt StrTabLen}. Recompile the {tt filesecret.c} and the appropriate application tasks.

get_tes:        set=A tes=B

This points to a programming error or error in the logic during {it filestruct(3NEMO)} I/O. During program execution a hierarchical set A was requested to be closed, but the program was still within set B (set B had not been closed yet).

gethdr:         ItemFlag = 0164

Input was attempted on a file assumed to be in old {it filestruct(5NEMO)} format. Apparently it was not, file may also have been in new filestruct format. {bf Hints:} Try {it tsf(1NEMO)}, {it hd(1NEMO)}, {it od(1)} and as last resort {it more(1)}.

gethdr:         bad magic: 0164

Input was attempted on a file assumed to be in {it filestruct(5NEMO)} format. Apparently it was not. {bf Hints:} Try {it tsf(1NEMO)}, {it hd(1NEMO)}, {it od(1)} and as last resort {it more(1)}.

loadobj:        file must be in .o format

It is possible that the non-portable dynamic object loader (loadobj.c) indeed proves to be non-portable here. Either you requested a wrong file, which is not in object format, or this UNIX version has a different object file structure. {bf Cure:} a lot of hacking in loadobj.c, assuming no pilot error.

loadobj:        undefined symbol _XXXX

There are three possible causes. It might be that you have just supplied a ‘new’ object file to a program, which happens to call a function which was not linked in by the calling program. Find out in which filestructure ‘group’ (Nbody, Orbit, Image) your invoked program falls, and add appropriate dummy code to the library function. {it E.g.} in the case of {it potential(5NEMO)} data files, you might have to add a specific math function to $NEMO/inc/mathlinker.h, or add some coding to the end of $NEMO/src/orbit/potential/potential.c and rebuild the appropriate {it orbit(1/3NEMO)} library/commands. The standard UNIX utility {it nm(1)} help finding all undefined symbols in an object file. Cross check this with the executable.

The second possibility is that the executable was stripped, i.e. it had no symbol table. Try {tt nm(1)} to find out, or use {tt file(1)}.

The last cause is much more serious: the non-portable dynamic object loader (loadobj.c) indeed seems to be non-portable here. This might mean serious hacking in loadobj.c, we cannot give any advice on this right now.

loadobj:        word relocation not supported

It is possible that the non-portable dynamic object loader (loadobj.c) indeed proves to be non-portable here. This might mean serious hacking in loadobj.c.

makecell:       need more than XX cells; increase fcells=

This is actually sort of a pilot error, but may sound a bit obscure to a beginning user. Space for cells used in the hackcode force calculation is allocated dynamically, as well as for the particles. ‘fcells’ is the ratio of allocated cells to particles and is a parameter to most programs who use the hackcode force calculation. For small N-body systems (less then about 100) this ratio may have to be increased, 2 usually is enough. Note that in the regime where fcells is required larger, the hackcode force calculation is usually not the most efficient method to compute forces anyhow.

mysymbols:      file must be executable

It is possible that the non-portable dynamic object loader (loadobj.c) indeed proves to be non-portable. The program which you just executed does not have the executable format the dynamic object loader thinks it should have.

No man entry for XXX.Y

No manual entry for XXX

No online manual page for this, although perhaps the MANPATH environment variable has not been properly set, or your UNIX version does not support multiple man-root directories, in which case consult the manual page of man(1).

put_snap_XXX:   not implemented

Here ‘XXX’ may be ‘key’ or ‘aux’ or something else. You have an old version of the code, while the datastructure of the snapshot has an ‘XXX’ (You may confirm this with tsf. Recompile the program with a more recent version of $langle$snapshot/put_snap.c$rangle$ and possibly $langle$snapshot/body.h$rangle$.

readparam:      No interactive input allowed

The keyword {bf help=} or the equivalent environment variable {bf HELP} has been assigned a digit to request interactive input. In addition you requested some file I/O through either redirection or piping. Get rid of at least one of them.

rsh:            could not execute rsh

Program could not execute itself on a remote machine. It may have various reasons for failing. The {tt rsh} program may not exist on your host, in which case the {it getparam(3NEMO)} might as well have been compiled without the {bf REMOTE} flag. The other possibility is that the {tt .rhosts} file on your system does not contain an entry for the machine you wanted to rsh to. In interactive usage it will then ask for a password, executed through {it execvp(3)} normally fails. A third possibility is that the remote machine did not have the executable present.

Badly placed ()'s

bash: syntax error near unexpected token (

You tried to pass an expression with parentheses, but since the UNIX shell gives them special meaning, you need to escape them from the shell, e.g.

% snapplot in=snap001 xvar=r yvar=log(aux)

you need to type any of:

% snapplot in=snap001 xvar=r 'yvar=log(aux)'
% snapplot in=snap001 xvar=r yvar=log\(aux\)

12.2. Environment Variables used by NEMO

Occasionally NEMO’s environment can interfere with those of other packages. The following list of environment variables have some meaning to NEMO. A default is usually activated when the environment variable is absent.

  • BELL If BELL is set (1), a number of user-interface routines become noisy. The default is 0.

  • BTRPATH List of directories where {it bodytrans(3NEMO)} functions can be stored for retrieval. The default is {tt /usr/nemo/obj/bodytrans}. Normally set to {tt “.:$NEMOOBJ/bodytrans”} in {tt NEMORC}.

  • DEBUG Debug level, must be between 0 and 9. The higher the number, the more debug output appear on {it stderr}. The default is 0. See {it getparam(3NEMO)}. DEBUG is also used as system keyword, in which case the environment variable is ignored.

  • EDITOR Editor used when helplevel 4 is included. The default is {tt vi} (see {it vi(1)}). See also {it getparam(3NEMO)}.

  • ERROR Error level for irrecoverable errors. If this environment variable is present, and its numeric value is positive, this is the number of times that such fatal error calls are bypassed; after that the the program really stops. See also {it getparam(3NEMO)}.

  • HELP Help level, can be any combination of numerically adding 0, 1, 2, and 4, and any combination of ‘?’, ‘a’, ‘h’, ‘p’, ‘d’, ‘q’, ‘t’ and ‘n’. See {it getparam(3NEMO)}. HELP is also used as system keyword, in which case the environment variable is ignored. The numeric part of the help string should come first.

  • HISTORY Setting it to 0 causes history data NOT to be written, the default is 1 (see {it getparam(3NEMO)}). A few old programs may use the keyword {tt amnesia=} for this.

  • HOSTTYPE In case of multiCPU environment, which has to be served from the same {tt NEMORC} and/or {tt .cshrc} file, this variable will have the CPU type in it, {it e.g.} {tt sun3} or {tt sun4}, which are used to break up the {tt bin}, {tt lib} and {tt obj} directories. It is also used in some Makefiles.

  • MANPATH Used by UNIX to be able to address more than one area of manual pages. Normally set to {tt $NEMO/man:/usr/man} by the {tt NEMORC} file. Does not work in Ultrix 3.0, but perhaps the {tt -P} switch may be used.

  • NEMO The root directory for NEMO. Normally the only environment variable which a user has to define himself, in his {tt .cshrc} startup file. No default.

  • NEMOBIN Directory where nemo’s binaries live, defined in {tt NEMORC}. No default.

  • NEMODOC Directory where the *.doc files for mirtool and miriad shell should be looked for. The system default is $NEMO/man/doc, set by NEMORC. No default.

  • NEMODEF Directory where keyword files from {tt mirtool/miriad } are stored/retrieved. The default is the current directory.

  • NEMOLIB Directory where nemo’s libraries live. Normally set by NEMO. No default.

  • NEMOLOG Filename used as logfile for tasks submitted through nemotool.

  • NEMOOBJ Directory were (binary) object files live. They are used by a variety of nemo programs, and generally do not concern the user. Usually set by NEMORC.

  • NEMOPATH Same as NEMO, but kept for historical reasons. It is normally defined in the NEMORC file. –deprecated–

  • NEMOSITE The site name, which is also an alias used in case the import/export features with the central site are to be maintained.

  • PATH UNIX search-path for executables, normally set in your own shell startup file (.cshrc or .login). Should contain NEMOBIN early in the path definition, before /usr/bin and /bin to redefine the cc and make programs. See Appendix~ref{a:setup}

  • POTPATH List of directories where potential(5NEMO) functions can be stored. The default is /usr/nemo/obj/potential.

  • REVIEW If this variable is set, the REVIEW section is entered before the program is run. [default: not set or 0]

  • YAPP Yapp graphics output device. Usage depends which {it yapp(3NEMO)} the program was linked with. See also {it getparam(3NEMO)} and {it yapp(5NEMO)}. YAPP is also used as system keyword, in which case the environment variable is ignored.

See also the manual pages of {it files(1NEMO)}.