!
! PMU0.HLP	Header file for Help on the Post Mortem Utility (PMU) package.
!		Frank J. Nagy, Fermilab Accelerator Controls	14-Nov-84
!
1 Post_Mortems
 The Port Mortem Utility routines (PMU) are designed to assist you in
 debugging the occasional failure of single-image detached processes and
 other instances for which the interactive debugger is not a practical
 solution to the problem.  See the subtopic "Why" for more information
 on how the PMU package can help you and why it was created.

 The PMU routines are found in the PMULIB object library in FERMI$LIB:.
 To use, you must include the following fragment on your LINK command or
 in your LINK options file:

		...,FERMI$LIB:PMULIB/LIBRARY,...

 You will have to write your own condition handler which calls the PMU
 routines or use the generic PMU condition handler by establishing the
 routine with entry point PMU_HANDLER.  The equivalent FORTRAN code is:

		EXTERNAL  PMU_HANDLER
		...
		CALL LIB$ESTABLISH( PMU_HANDLER)

 The parameters controlling the operation of the generic condition
 handler are setup with the PMU_SETUP routine.

2 Why
 The initial Fermilab efforts at debugging detached network servers lead
 to the creation of the LIB_BUGCHK_LOG routine which provided a condition
 handler to output a message to OPCOM when a detached process failed.
 This routine was replaced by the LIB_LOG_SIGNALS routine with a modest
 amount of additional capability.  At the same time, debugging work on the
 ACNET network processes created a condition handler which provided
 register, stack and impure memory dumps - invaluable tools in the face of
 occasional problems with detached processes (actually, there are no other
 tools!).  All this experience lead to the creation of the PMU package to
 replace the earlier LIB_ routines and generalize the functionality from
 the ACNET-specific post mortem dumps.

 The other major problem stumbled upon was the disturbing difference between
 the process permanent files (SYS$OUTPUT and SYS$ERROR) in interactive and
 batch processes and in single-image detached processes and subprocesses
 where the output and error files (/OUTPUT= for RUN command and output file
 parameter in the $CREPRC system service) are directed to disk files for
 logging purposes.  In the cases where the LOGINOUT image is not executed,
 used for the ACNET servers as DCL is totally unneeded in these detached
 processes, SYS$OUTPUT and SYS$ERROR are not setup as process permanent
 files.  This leads to a conflict between writing to these files with
 FORTRAN or LIB$PUT_OUTPUT and $PUTMSG.  If SYS$OUTPUT and SYS$ERROR are
 directed to a single file and if $PUTMSG does the first write, then the
 first FORTRAN write (or LIB$PUT_OUTPUT) will cause the process to fail
 with an attempt to write to a non-shareable file.  If the first output is
 from FORTRAN or LIB$PUT_OUTPUT, then $PUTMSG will never write anything
 and error messages and tracebacks are lost.  The solution to this was to
 create separate disk files for SYS$OUTPUT and SYS$ERROR (the local standard
 suggests a file type of .LOG for the SYS$OUTPUT file and of .ERR for the
 SYS$ERROR file).

