13. 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 gdb(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.

13.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 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 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 #define``d in ``filesecret.h by the macro StrTabLen. Recompile the 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 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 filestruct(5NEMO) format. Apparently it was not, file may also have been in new filestruct format. Try programs like tsf, hd, hexdump, od.

gethdr:         bad magic: 0164

Input was attempted on a file assumed to be in filestruct(5NEMO) format. Apparently it was not. Try programs like tsf, hd, hexdump, od.

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. Cure: probably some hacking in loadobj.c.

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. For example in the case of 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 orbit(3NEMO) library. The standard UNIX utility 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 nm(1) to find out, or 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 program, 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 put_snap.c and body.h.

readparam:      No interactive input allowed

The keyword help= or the equivalent environment variable 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.

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\)

13.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.

  • BTRPATH List of directories where bodytrans(3NEMO) functions can be stored for retrieval. The default is /usr/nemo/obj/bodytrans. Normally set to ".:$NEMOOBJ/bodytrans"

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

  • EDITOR Editor used when helplevel 4 is included. The default is vi. See also 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 getparam(3NEMO). HELP is also used as system keyword, help=, 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 getparam(3NEMO)).

  • HOSTTYPE In case of multiCPU environment, this variable can be used to differentiate the environment.

  • MANPATH Used by UNIX to be able to address more than one area of manual pages. Normally set to $NEMO/man:/usr/man, though operating systems may have different ways to set multiple entries to the manpath.

  • NEMO The root directory for NEMO. Normally the only environment variable which a user has to define. No default.

  • NEMOBIN Directory where nemo’s binaries live, should be part of the ``$PATH`

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

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

  • NEMOLIB Directory where nemo’s libraries live.

  • 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.

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

  • PATH UNIX search-path for executables, normally set in your own shell startup file (.cshrc or .login).

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

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

See also the manual pages of files(1NEMO)