Places ZSHOW <code> output into a file and returns the absolute file name. The format for the $ZJOBEXAM function is:
$ZJOBEXAM([expr1][,expr2])
The optional first expression is the output specification. It can be a file directory or a file name. $ZJOBEXAM() pre-processes the first expression to create a file specification as the target for the ZSHOW command output. The preprocessing is equivalent to $ZPARSE(), as illustrated by the following M code:
GTM>set cntr=1,deffn="GTM_JOBEXAM.ZSHOW_DMP_"_$JOB_"_"_cntr GTM>w $zparse(deffn) /path/to/GTM_JOBEXAM.ZSHOW_DMP_49878_1 GTM>w $zjobexam() /path/to/GTM_JOBEXAM.ZSHOW_DMP_49878_1 GTM>
The optional second expression evaluates to a string containing a list of one or more ZSHOW information codes that determine the type of information. If the second expression is missing or empty, GT.M operates as it was a "*" and produces all context. Note that using an explicit list may be useful in limiting the exposure of sensitive information. For more information, refer to to “ZSHOW Information Codes”.
The return value serves as a way to save, to notify others of the exact location of the output or to open the file for further processing. GT.M logs the JOBEXAMDONE message to the operator log for each $ZJOBEXAM() which includes the full file specification.
The $ZJOBEXAM()does not trigger error processing except when there is a problem storing its return value, so no error is reported to the process until after any dump is complete. In the event of any error encountered during the $ZJOBEXAM(), GT.M sends an appropriate message to operator log facility and returns control to the caller. Note that this special error handling applies only to the $ZJOBEXAM(), and is not a property of the $ZINTERRUPT interrupt handler, which uses $ZJOBEXAM() by default.
$ZJOBEXAM() dump files contain the context of a process at the time the function executes. Placement and management of these files should consider their potential size and security implications.
Example:
GTM>set x=$zjobexam()
GTM>write x
/tmp/GTM_JOBEXAM.ZSHOW_DMP_383974_1
GTM>set x=$zjobexam("jobexam.out")
GTM>write x
/tmp/jobexam.out
GTM>set x=$zjobexam("jobexam_ISV.out","I")
GTM>write x
/tmp/jobexam_ISV.out
GTM>
In the first two examples, the output file contains zshow "*" information. The 3rd example saves zshow "I" (ISVs only) information in the output file.