'\" t
.\"     Title: pegasus-exitcode
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/09/2018
.\"    Manual: Pegasus Manual
.\"    Source: Pegasus 4.4.0
.\"  Language: English
.\"
.TH "PEGASUS\-EXITCODE" "1" "11/09/2018" "Pegasus 4\&.4\&.0" "Pegasus Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pegasus-exitcode \- Checks the stdout/stderr files of a workflow job for any indication that an error occurred in the job\&. This script is intended to be invoked automatically by DAGMan as the POST script of a job\&.
.SH "SYNOPSIS"
.sp
.nf
\fBpegasus\-exitcode\fR [\fB\-h\fR][\fB\-r\fR \fIrv\fR][\fB\-n\fR][\fB\-s\fR \fImsg\fR][\fB\-f\fR \fImsg\fR] \fIjob\&.out\fR
.fi
.SH "DESCRIPTION"
.sp
\fBpegasus\-exitcode\fR is a utility that examines the STDOUT of a job to determine if the job failed, and renames the STDOUT and STDERR files of a job to preserve them in case the job is retried\&.
.sp
Pegasus uses \fBpegasus\-exitcode\fR as the DAGMan postscript for jobs submitted via Globus GRAM\&. This tool exists as a workaround to a known problem with Globus and Condor\-G where the exitcodes of GRAM jobs are not returned\&. This is a problem because Pegasus uses the exitcode of a job to determine if the job failed or not\&.
.sp
In order to get around the exitcode problem, Pegasus can wrap GRAM jobs with Kickstart, which records the exitcode of the job in an XML invocation record, which it writes to the job\(cqs STDOUT\&. The STDOUT is transferred from the execution host back to the submit host when the job terminates\&. After the job terminates, DAGMan runs the job\(cqs postscript, which Pegasus sets to be \fBpegasus\-exitcode\fR\&. \fBpegasus\-exitcode\fR looks at the invocation record generated by kickstart to see if the job succeeded or failed\&. If the invocation record indicates a failure, then \fBpegasus\-exitcode\fR returns a non\-zero result, which indicates to DAGMan that the job has failed\&. If the invocation record indicates that the job succeeded, then \fBpegasus\-exitcode\fR returns 0, which tells DAGMan that the job succeeded\&.
.sp
In addition, clustered jobs executed with \fBpegasus\-cluster\fR or \fBpegasus\-mpi\-cluster\fR will have a [cluster\-summary] record in their STDOUT\&. \fBpegasus\-exitcode\fR can examine these records to determine if any of the tasks in the clustered job failed\&.
.sp
\fBpegasus\-exitcode\fR performs several checks (some optional) to determine whether a job failed or not\&. These checks include:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Is the Condor exitcode non\-zero? If so, then the job failed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Is STDOUT empty? If it is empty, then the job failed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Are there any failure messages in the STDOUT or STDERR? If so, the job failed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
Are all of the success messages in the STDOUT or STDERR? If not, then the job failed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
Does the
[cluster\-summary]
record indicate that the job was successful\&. If not, then the job failed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
Are there any
<status>
tags with a non\-zero value? If there are, then the job failed\&. Note that, if this is a clustered job, there could be multiple
<status>
tags, one for each task\&. If any of them are non\-zero, then the job failed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  7." 4.2
.\}
Is there at least one
<status>
tag with a zero value? There must be at least one successful invocation or the job has failed\&.
.RE
.sp
In addition, \fBpegasus\-exitcode\fR allows the caller to specify the exitcode returned by Condor using the \fB\-\-return\fR argument\&. This can be passed to \fBpegasus\-exitcode\fR in a DAGMan post script by using the $RETURN variable\&. If this value is non\-zero, then \fBpegasus\-exitcode\fR returns a non\-zero result before performing any other checks\&. For GRAM jobs, the value of $RETURN will always be 0 regardless of whether the job failed or not\&.
.sp
In addition to checking the success/failure of a job, \fBpegasus\-exitcode\fR also renames the STDOUT and STDERR files of the job so that if the job is retried, the STDOUT and STDERR of the previous run are not lost\&. It does this by appending a sequence number to the end of the files\&. For example, if the STDOUT file is called "job\&.out", then the first time the job is run \fBpegasus\-exitcode\fR will rename the file "job\&.out\&.000"\&. If the job is run again, then \fBpegasus\-exitcode\fR sees that "job\&.out\&.000" already exists and renames the file "job\&.out\&.001"\&. It will continue to rename the file by incrementing the sequence number every time the job is executed\&.
.SH "OPTIONS"
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Prints a usage summary with all the available command\-line options\&.
.RE
.PP
\fB\-r\fR \fIrv\fR, \fB\-\-return\fR \fIrv\fR
.RS 4
Return value reported by DAGMan\&. This can be specified in the DAG using the $RETURN variable\&. If this is non\-zero, then
\fBpegasus\-exitcode\fR
immediately fails with a non\-zero return value itself\&. If it is zero, then just rotate the file and don\(cqt check for proper kickstart output\&. This option can be used in cases where kickstart cannot be used (such as pegasus\-create\-dir) to enable file rotation\&.
.RE
.PP
\fB\-n\fR, \fB\-\-no\-rename\fR
.RS 4
Don\(cqt rename
\fIjob\&.out\fR
and
\fIjob\&.err\fR
to
\fI\&.out\&.XXX\fR
and
\fI\&.err\&.XXX\fR\&. This option is used primarily for testing\&.
.RE
.PP
\fB\-f\fR \fImsg\fR, \fB\-\-failure\-message\fR \fImsg\fR
.RS 4
Failure message to find in job stdout/stderr\&. If this message exists in the stdout/stderr of the job, then the job will be considered a failure no matter what other output exists\&. If multiple failure messages are provided, then none of them can exist in the output or the job is considered a failure\&.
.RE
.PP
\fB\-s\fR \fImsg\fR, \fB\-\-success\-message\fR \fImsg\fR
.RS 4
Success message to find in job stdout/stderr\&. If this message does not exist in the stdout/stderr of the job, then the job will be considered a failure no matter what other output exists\&. If multiple success messages are provided, then they must all exist in the output or the job is considered a failure\&.
.RE
.SH "AUTHORS"
.sp
Gideon Juve <juve@usc\&.edu>
.sp
Pegasus Team \m[blue]\fBhttp://pegasus\&.isi\&.edu\fR\m[]