Format Change in the ^mtemp and ^ERRORS Globals

Format Change in the ^mtemp and ^ERRORS Globals

InterSystems has several routines, methods and utilities that can create stack dumps.  Stack dumps are created in the ^mtemp(index) global by the %SYS.ProcessQuery:ExamStackByPid(...) classmethod as well as by some undocumented legacy entry points of the ^%STACK utility.  Stack dumps can also be created in the ^ERRORS(date,index) global by the ^%ETN trap routine, including additional entry points BACK^%ETN, LOG^%ETN, ^%ET and the Log() method of exception objects.   These stack dumps can also include the values of active local variables.  There are routines which can examine the ^mtemp and ^ERRORS globals and then display the stack dump and variable values.  InterSystems is improving this capability by saving new information about about active objects along with the stack dump and local variables.  This will cause a change in the format of some of the data saved in ^mtemp and ^ERRORS.

The changes to stack dumps in the ^mtemp and ^ERRORS globals might effect customer written routines that examine stack dumps without using the legacy entry points in ^%STACK.  InterSystems would like comments from any users who have written their own routines that examine ^mtemp and ^ERRORS.

The 'DO ^%STACK' command interactively dumps the current stack and then prompts the user for commands to display this information.  There is also a JOBEXAM feature which can interactively display information about an active job with a different PID number.  These commands place the stack dump in the ^mtemp(index) global.  They will be using the new format dump to provide new capabilities.  They usually delete the information in ^mtemp(index) when they are finished. Other existing InterSystems routines that examine stack dumps, like ^%ERN, will support the new format dumps.  New capabilities include those that will display information about active class objects.

Current user documentation of the ^mtemp format can be found in Class Reference web page for the ExamStackByPid classmethod in the %SYS.ProcessQuery class.  That documentation says the following:

The data is returned in these nodes of the ^mtemp(index) global:
("*STACK") = the number of stack levels
("*STACK",0,"V",SpecialVar) = the values of special variables such as $S and $ZE
("*STACK",level,"L") = the text line for this level, as displayed by %STACK or JOBEXAM
("*STACK",level,"S") = the source line for this level, with a tilde inserted in front of the current command
("*STACK",level,"I") = the internal data for this level

If variables are requested:
("*LEVEL",level,variable) = the base level of a variable that is visible at this level
("*NAMES",variable,base,level) - this is the same information as *LEVEL in a different format
("*STACK",base,"V",variable) = the value of the variable at its base level

These ^mtemp(index) entries can also be found under the ^ERRORS(date,index) globals.  There exist additional formatted dump entries that are not described above.  Of the entries documented above, current plans only call for modifying the ("*STACK",base,"V",variable) entries along with entries subscripted under these entries.  There will be new "*OREF" entries indexed by oref number describing each active object.  There will be new "*CLASS" entries that map class names into their corresponding oref numbers.