=head1 NAME

gbatch_puttitle - change the title in a job structure

=head1 SYNOPSIS

B<int gbatch_puttitle(const int>
I<fd>B<, apiBtjob *>I<jobp>B<, const char *>I<title>B<)>

=head1 DESCRIPTION

The function B<gbatch_puttitle> is used to insert a new or replacement
title into the string table of a job structure, possibly automatically
inserting the current queue name as set by gbatch_setqueue(3).

I<fd> is a file descriptor which was previously returned by a
successful call to gbatch_open(3), or C<-1> to disregard any queue name
set by gbatch_setqueue(3).

I<jobp> is a pointer which contains the details of the job.

I<title> is the required new title or C<NULL> if the title is to be
deleted. If I<fd> is a valid API descriptor, then any queue name set
by gbatch_setqueue(3) will be added to it.

=head1 RETURN VALUES

The result will be no-zero if successful or zero if the string table
overflowed.  In the latter case the string table contents of the job
should not be relied upon.  The job structure should be saved first if
in doubt.

=head1 SEE ALSO

gbatch_delarg(3),
gbatch_delenv(3),
gbatch_delredir(3),
gbatch_getarg(3),
gbatch_getdirect(3),
gbatch_getenv(3),
gbatch_getenvlist(3),
gbatch_gethenv(3),
gbatch_getredir(3),
gbatch_gettitle(3),
gbatch_putarg(3),
gbatch_putarglist(3),
gbatch_putdirect(3),
gbatch_putenv(3),
gbatch_putenvlist(3),
gbatch_putredir(3),
gbatch_putredirlist(3),
gbatch_setqueue(3).

=head1 COPYRIGHT

Copyright (c) 2009 Free Software Foundation, Inc.
This is free software. You may redistribute copies of it under the
terms of the GNU General Public License
<http://www.gnu.org/licenses/gpl.html>.
There is NO WARRANTY, to the extent permitted by law.

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
