'\" t
.\"     Title: globus-fork-starter
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 12/01/2009
.\"    Manual: University of Chicago
.\"    Source: University of Chicago
.\"  Language: English
.\"
.TH "GLOBUS\-FORK\-STARTE" "8" "12/01/2009" "University of Chicago" "University of Chicago"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
globus-fork-starter \- Start and monitor a fork job
.SH "SYNOPSIS"
.HP \w'\fBglobus\-fork\-starter\fR\ 'u
\fBglobus\-fork\-starter\fR
.SH "DESCRIPTION"
.PP
The
\fBglobus\-fork\-starter\fR
program is executes jobs specified on its standard input stream, recording the job state changes to a file defined in the
\fB$GLOBUS_LOCATION\fR/etc/globus\-fork\&.conf
configuration file\&. It runs until its standard input stream is closed and all jobs it is managing have terminated\&. The log generated by this program can be used by the SEG to provide job state changes and exit codes to the GRAM service\&. The
\fBglobus\-fork\-starter\fR
program is typically started by the fork GRAM module\&.
.PP
The
\fBglobus\-fork\-starter\fR
program expects its input to be a series of task definitions, separated by the newline character, each representing a separate job\&. Each task definition contains a number of fields, separated by the colon character\&. The first field is always the literal string
100
indicating the message format, the second field is a unique job tag that will be distinguish the reply from this program when multiple jobs are submitted\&. The rest of fields contain attribute bindings\&. The supported attributes are:
.PP
directory
.RS 4
Working directory of the job
.RE
.PP
environment
.RS 4
Comma\-separated list of strings defining environment variables\&. The form of these strings is
var=value
.RE
.PP
count
.RS 4
Number of processes to start
.RE
.PP
executable
.RS 4
Full path to the executable to run
.RE
.PP
arguments
.RS 4
Comma\-separated list of command\-line arguments for the job
.RE
.PP
stdin
.RS 4
Full path to a file containing the input of the job
.RE
.PP
stdout
.RS 4
Full path to a file to write the output of the job to
.RE
.PP
stderr
.RS 4
Full path to a file to write the error stream of the job
.RE
.PP
Within each field, the following characters may be escaped by preceding them with the backslash character:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
backslash (\e)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
semicolor (;)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
comma (,)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
equal (=)
.RE
.sp
.RE
Additionally, newline can be represented within a field by using the escape sequence \en\&.
.PP
For each job the
\fBglobus\-fork\-starter\fR
processes, it replies by writing a single line to standard output\&. The replies again consist of a number of fields separated by the semicolon character\&.
.PP
For a successful job start, the first field of the reply is the literal
101, the second field is the tag from the input, and the third field is a comma\-separated list of SEG job identifiers which consist the concatenation of a UUID and a process id\&. The
\fBglobus\-fork\-starter\fR
program will write state changes to the SEG log using these job identifiers\&.
.PP
For a failure, the first field of the reply is the literal
102, the second field is the tag from the input, the third field is the integer representation of a GRAM erorr code, and the fourth field is an string explaining the error\&.
.SH "ENVIRONMENT"
.PP
If the following variables affect the execution of
\fBglobus\-fork\-starter\fR
.PP
GLOBUS_LOCATION
.RS 4
Path to Globus Toolkit installation\&. This is used to locate the
globus\-fork\&.conf
configuration file\&.
.RE
.SH "FILES"
.PP
.PP
\fB$GLOBUS_LOCATION\fR/etc/globus\-fork\&.conf
.RS 4
Path to fork SEG configuration file\&.
.RE