mxr(1)							      General Commands Manual							    mxr(1)

NAME

       mxr - DECmigrate: MIPS Translator Runtime Environment

SYNOPSIS

       [executable_name] [options...]

       /usr/bin/mxr -help

       /usr/bin/mxr -V

OPTIONS

       Display the mxr help message.  Display the mxr version number.

DESCRIPTION

       The  MIPS  Translator  Runtime Environment, mxr, supports binary executables produced by DECmigrate (mx).  When you execute the output exe-
       cutable on an Alpha system running Tru64 UNIX, mxr is automatically invoked either as a shared image or as a shared library.  The mxr envi-
       ronment provides the translated executable with any MIPS or ULTRIX resources it requires to run.

       In  cases  where  there	is no Tru64 UNIX translation for an ULTRIX operation, mxr supports the executable by emulating that operation.	In
       addition, mxr provides feedback, enabling mx to retranslate the executable, eliminate some or all instances of emulation, and improve  run-
       time performance.

RESTRICTIONS

       The  mxr environment does not support certain ULTRIX operations.  See the release notes for the unsupported ULTRIX operation. The mxr envi-
       ronment only supports executables that were translated by mx.

       The mxr environment only supports setuid or setgid programs or OMAGIC executions if the executable was translated using	the  -coff  option
       (the  default)  to  the	mx  command.  In addition, mxr only supports non-finite numbers if the executable was translated with the -full_fp
       option to the mx command.

DEBUGGING

       This section describes situations when the translated executable fails at runtime, runs but produces different results  than  the  original
       executable, or runs slowly.

       If  an  executable  runs  properly  on an ULTRIX system but fails when translated and run on a Tru64 UNIX system, check the following: File
       Names: Some executables read the name with which they were invoked to determine operating behavior.  To enable  these  executables  to  run
       properly  on a Tru64 UNIX system, ensure that the file names match the original names of the files on the ULTRIX system.  Restore filenames
       as necessary.  Missing Files: See if there are any files that need to be moved to the Tru64 UNIX system.  Some executables require  certain
       files  to  exist  at  specific  places  in  the	file system, and fail when that is not true.  For example, many X clients require files in
       /usr/lib/X11/app-defaults and /usr/lib/X11/uid. Translated MicroFocus COBOL programs attempt to access the file	/usr/lib/cobol/rts32,  and
       abort if that file is not present.

	      To see a list of the files that a program is trying to find, set the environment variable MXR_TRACE_VARIABLES to stat,open.

	      To  run  translated programs, copy the missing files to the Tru64 UNIX system and place them in directories that correspond to their
	      original directories.  For example, to run translated MicroFocus COBOL programs on a Tru64 UNIX system, do  the  following:  On  the
	      Tru64 UNIX system, create the /usr/lib/cobol directory.  Copy the /usr/lib/cobol/rts32 file from the ULTRIX system on which COBOL is
	      installed to the /usr/lib/cobol directory on the Tru64 UNIX system.  Invoke the translated executable.  Floating	Point  Exceptions:
	      Floating	point calculations involving non-finite numbers such as infinites, denormalized numbers, or Not-a-Numbers (NaNs), generate
	      exceptions on the Alpha architecture. These calculations are handled silently by the MIPS architecture.  If an executable  generates
	      SIGFPEs, an error message of the following form displays and the program terminates:

	      The  translated  program	attempted  a floating-point calculation with a denormalized number or NaN.  Retranslate using the -full_fp
	      option to mx.

	      To reproduce the MIPS system behavior, mxr must intercept these exceptions and perform the appropriate actions without signaling the
	      translated program. Retranslate program using the -full_fp option to mx, then run the new translated executable.	The results of the
	      calculations using or producing non-finite numbers are consistent with IEEE/ANSI 754-1985 and should produce the same results as the
	      original	program. See the user manual for more information.  If the executable still generates SIGFPEs, try translating with the mx
	      option -trapb. If you do this, please file an SPR including the results with Compaq so that -full_fp option can  be  enhanced.   You
	      can  still  use MXR_GENERATE_FEEDBACK, but -full_fp must be set each time you retranslate the executable.  See the FEEDBACK section.
	      Error message saying "Unaligned access on ldt" or "Unaligned access on stt:"  If you get a message of this form,	retranslate  using
	      the  -F  option to mx.  This causes mx to assume that all floating-point loads and stores are potentially unaligned, and to generate
	      code accordingly. Refer to the EXAMPLES section.	Error message saying "Stack not longword aligned:" This error message indicates  a
	      serious bug in your original program.

	      If  an  executable runs on the Tru64 UNIX system but does not produce the same output as the ULTRIX executable, check the following:
	      Some executables look at the stack and use the return address to examine the MIPS code stream.   These  executables  will  not  work
	      properly	when  translated.  These  executables  include: Ada executables that use exceptions PL/1 executables that use signals Some
	      classes of FORTRAN executables Some programs that use Compaq's VMS portability library (plib).  Some executables expect  non-finite,
	      floating	point  numbers,  such  as  infinities,	denormalized  numbers,	and Not-a-Numbers, to behave as specified in the IEEE/ANSI
	      754-1985 standard.  To support this, you must translate the executable with the -full_fp option.	 Otherwise,  the  results  of  the
	      translated  executable might be different from the original executable, or may abort with a floating-point exception.  Error message
	      saying "The program changes the rounding mode to -Infinity..." Retranslate the executable using the -fixround  option.  At  runtime,
	      code  checks the rounding mode, and changes each instance of floating point rounding to RM (minus infinity) to floating point round-
	      ing to RZ (zero).

	      This may cause a slight loss of precision, but might substantially improve the runtime performance of the translated  program.   The
	      /bin/time  file  created	by the executable shows large amounts of time being spent on system operations. Translate executable using
	      the -fixround option. At runtime, code checks the rounding mode, and changes each instance  of  floating	point  rounding  to  minus
	      infinity (RM) to floating point rounding to zero (RZ).

	      This may cause a slight loss of precision, but might substantially improve the runtime performance of the translated program.

	      If the translated executable runs, but slowly, see if the translation can be improved with feedback.  See the FEEDBACK section.

FEEDBACK

       If  you set the MXR_GENERATE_FEEDBACK environment variable and the executable creates or extends a file when executing, this means mxr dis-
       covered new entry points while executing the executable. Retranslating the executable allows mx to access the entry points and improve  the
       speed  of  the  executable.   Do the following: Delete or remove the translated executable.  You do not need it to create the next version.
       Copy only the file to the system and directory containing both mx and the original input executable.  Be sure the name of the file is  exe-
       cutable.hif, where executable is the file name of the input executable.	Retranslate the original input executable using mx.

	      The  mx  translator  reads the file and uses the information in it to improve the translation.  Run the retranslated executable with
	      the MXR_GENERATE_FEEDBACK environment variable set.  If the retranslated executable discovers more entry points, it appends  entries
	      to the file, extending the file.	Repeat steps 1, 2, 3, and 4 until no new entries are created during execution.

ERROR MESSAGES

       Error messages are described in the DECmigrate User's Guide.

       The  severity  levels  are as follows: Informational message.  Not displayed unless MXR_VERBOSE is set.	Warning message.  Warning messages
       are displayed unless MXR_QUIET is set.  A warning usually results in the specified operation, such as syscall, returning an  error  status,
       but  the  translated  program continues to run.	Fatal error message.  Always displayed if an error occurs.  Error messages cause immediate
       termination of the translated program.

ENVIRONMENT VARIABLES

       The mxr environment modifies its behavior if any of the following environment variables are set when you execute a  translated  executable:
       Generate  a  file to use as feedback for a subsequent retranslation. This is overridden by the -nohifs option in mx.  See the FEEDBACK sec-
       tion.  Redirect mxr input/output through an xterm window.  This is useful for separating mxr diagnostic messages.  Print all debugging out-
       put  in	detailed  form.   Prints  program header information and "unrecognized error tag" messages.  Prints program load/execute progress.
       Prints program exit details and homing map.  Prints signal details.  Prints ioctl() details.  Prints brk() details.  Prints computed branch
       details.   Suppress  all  mxr  output  except for fatal errors.	Note: You may be suppressing nonfatal error messages that indicate you are
       using an unsupported feature. The executable still runs, but its function is unpredictable.  Trace all system calls.  If  no  system  calls
       are  specified,	all system calls are traced.  If any system calls are specified or if the word "all" appears in the list, only those calls
       are traced.  Preceding a system call name with a hyphen (-) forces it not to be traced. The list is  scanned  left-to-right.  Separate  the
       system call names with commas (,).  For example:

	      MXR_TRACE_SYSCALLS open, close, read, write

	      Traces the calls specified.

	      MXR_TRACE_SYSCALLS all, -read, -write

	      Traces all syscalls except read and write. If you are using either the ksh or sh shell, the format is:

	      MXR_TRACE_SYSCALLS=xxx,xxx  export  MXR_TRACE_SYSCALLS  Display runtime statistics when the executable exits.  Trace all signals and
	      signal system calls.

EXAMPLES

       The following is an excerpt from the terminal output of an executable that needs to be retranslated by mx with the -F option.  The  opcodes
       stt (type=stt) and ldt (type=ldt) are the ones in error.

       [963]  piston:person>  dxpsview	quilt.ps  Unaligned  access  pid=419 <mxr> va=10041624 reg=4 type=stt pc=58cbd8 ra=58c8f0 Unaligned access
       pid=419 <mxr> va=1004161c reg=2 type=ldt pc=58cbd8 ra=58c8f0

FILES

       The run-time support for executables translated using the -coff option to the mx command.  Resides on the Tru64 UNIX system, and called	in
       as  a  shared  library  by  the translated executable.  The runtime support for executables translated using the -script option in mx.  The
       default name of the translated output file.

SEE ALSO

       DECmigrate User's Guide

																	    mxr(1)