gbatch_jobadd - create a new job

# NAME

gbatch_jobadd - create a new job

# SYNOPSIS

#include <gbatch.h>

FILE *gbatch_jobadd(const int fd, apiBtjob *jobd)

int gbatch_jobres(const int fd, jobno_t *jobno)

int gbatch_jobadd(const int fd, const int infile, int(*fn)(int,void*,unsigned), apiBtjob *jobd)

# DESCRIPTION

The function gbatch_jobadd, is used to create a new GNUbatch job.

There are two forms of gbatch_jobadd. The first form, together with gbatch_jobres, is used to create jobs using the Unix or Linux version of the API.

The second form is used under Windows as there is no acceptable substitute for the `pipe(2)` system call.

In both forms of the call, fd is a file descriptor which was previously returned by a successful call to gbatch_open(3).

jobd is a pointer to a structure containing the attributes of the job to be created apart from the job script.

The difference between the two versions of gbatch_jobadd is in the method of passing the job script.

## Unix and Linux

The Unix and Linux API version returns a stdio file descriptor which may be used with the standard I/O functions fputs(3), `fprintf(3)` etc to write the job script. When complete, the job script should be closed using fclose(3). The result of the job submission is then collected using the gbatch_jobres routine, which assigns the job number to the contents of the jobno parameter and returns zero as its result. The job number is also placed into the `bj_job` field in the job structure.

For reasons of correctly synchronising socket messages, be sure to call gbatch_jobres immediately after the call to fclose(3), even if you do not require the answer.

If there is any kind of error, then depending upon at what point the error is detected, either gbatch_jobadd will return `NULL`, leaving the error code in the external variable gbatch_dataerror, or gbatch_jobres will return the error as its result rather than zero.

## Windows

In the case of the Windows version, the specified function fn is invoked with parameters similar to read to read data to pass across as the job script, the argument infile being passed as a file handle as the first argument to fn.

fn may very well be read. The reason for the routine not invoking read itself is partly flexibility but mostly because some versions of Windows DLLs do not allow read to be invoked directly from within it.

N.B. This routine is particularly susceptible to peculiar effects due to assignment of insufficient stack space.

The return value is zero for success, in which case the job number will be assigned to the `bj_job` field of jobd, or an error code. The error code is also assigned to the external variable `gbatch_dataerror` for consistency with the Unix version.

# RETURN VALUES

The Unix version of gbatch_jobadd returns `NULL` if unsuccessful, placing the error code in the external variable `gbatch_dataerror`.

The Windows version of gbatch_jobadd and the xb_jobres under Unix return zero if successful, otherwise an error code.

The error codes which may be returned are defined in the include file \fBgbatch.h\fR.

# EXAMPLE

This example creates a job from standard input:

     int fd, ret, ch;
     FILE *outf;
     jobno_t jn;
     apiBtjob outj;

     fd = gbatch_open("myhost", (char *) 0);
     if (fd < 0) { /* error handling */
         . . .
     }

     /* always clear the structure first */
     memset((void *)&outj, '\0', sizeof(outj));

     /* only the following parameters are compulsory */

     outj.h.bj_pri = 150;
     outj.h.bj_ll = 1000;
     outj.h.bj_mode.u_flags = JALLMODES;
     outj.h.bj_exits.elower = 1;
     outj.h.bj_eupper = 255;
     outj.h.bj_ulimit = 0x10000;
     strcpy(outj.h.bj_cmdinterp, "sh"); /* NB assumes sh defined */
     gbatch_putdirec(&outj, "~/work");

     /* set progress code to zero */
     outj.h.bj_progress = BJP_CANCELLED;

     /* set up a time constraint */
     outj.h.bj_times.tc_istime = 1;
     outj.h.bj_times.tc_nexttime = time(long *)0) + 300;
     outj.h.bj_times.tc_repeat = TC_MINUTES;
     outj.h.bj_times.tc_rate = 10;
     outj.h.bj_times.tc_nposs = TC_SKIP;

     gbatch_puttitle(&outj, "MyTitle");

     outf = gbatch_jobadd(fd, &outj);
     if  (!outf)  {  /* error in gbatch_dataerror */
        . . .
     }

     while ((ch = getchar()) != EOF)
         putc(ch, outf);
     fclose(outf);
     ret = gbatch_jobres(fd, &jn);
     if (ret < 0) {  /* error in ret */
         . . .
     }
     else
         printf("job number is %ld\n", jn);

     gbatch_close(fd);

# SEE ALSO

gbatch_ciread(3), gbatch_delarg(3), gbatch_delenv(3), gbatch_delredir(3), gbatch_getarg(3), gbatch_getdirect(3), gbatch_getenv(3), gbatch_getenvlist(3), gbatch_getredir(3), gbatch_gettitle(3), gbatch_jobchgrp(3), gbatch_jobchmod(3), gbatch_jobchown(3), gbatch_jobdata(3), gbatch_jobdel(3), gbatch_jobfind(3), gbatch_joblist(3), gbatch_jobmon(3), gbatch_jobop(3), gbatch_jobread(3), gbatch_jobupd(3), gbatch_putarg(3), gbatch_putarglist(3), gbatch_putdirect(3), gbatch_putenv(3), gbatch_putenvlist(3), gbatch_putredir(3), gbatch_putredirlist(3), gbatch_puttitle(3), gbatch_setqueue(3), gbatch_varlist(3), gbatch_varread(3).

# 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.

# AUTHOR

John M Collins, Xi Software Ltd.