Create a job instance

Inputs:  Parm1 = owner folder name
         Parm2 = jobtype folder name if applicable
         [Parm3 = job instance number (>0)for CreateNumInstance]

Outputs: Parm1 = full path to instance UJP

Returns: Instance number or <0 for error
         -1 = Owner spec needed, but missing
         -2 = Owner spec not needed, but supplied
         -3 = Job type needed, but missing
         -4 = Job type not needed, but supplied
         -5 = Neither owner nor job type properties found
         -6 = No owner/job directory found and cannot create
         -7 = Instance made from NEXTJOB already exists
         -8 = Cannot get an instance number from NEXTJOB
         -9 = Cannot write UJP file
         -10 = Cannot write JST file
         -11 = Cannot write TXT file
         -12 = Cannot write SUM file
         -13 = Cannot write JCF file
         -14 = Folder missing for owner
         -15 = OWNER.UJP missing in owner folder
         -16 = Folder missing for jobtype
         -17 = JOBTYPE.UJP missing in jobtype folder
         -18 = Cannot read SYSTEM.UJP
         -19 = Pathname too long
         -20 = Error parsing $job_tosend_set
         -21 = Priority value or variable not in tosend set for instance
         -22 = OWNER.UJP open in JOBADMIN
         -23 = JOBTYPE.UJP open in JOBADMIN

This function creates a job instance, either with the next available instance number or with a specific instance number. The principal output is the job properties (UJP) file, but files are also written for status (JST), standard job report (TXT), summary statistics and history (SUM), and a file control file which will later contain FS numbers for the launched job items (JCF).

The job instance number can either be passed as an input to the function, or will be generated from the NEXTJOB file.  Currently only the use of a system-wide NEXTJOB file is supported.

The job instance is created from the hierarchy SYSTEM.UJP, OWNER.UJP and JOBTYPE.UJP (the last may be absent).  When the instance UJP file is processed, most commands are handled by ignoring all but the first encountered of duplicated commands: the three constituent files are therefore simply concatenated in sequence JOBTYPE, OWNER, SYSTEM, and a $job_instance command is added. There are three exceptions to this:

$var_defthese commands are extracted from the constituent files and are placed at the top of the job instance UJP in the sequence SYSTEM, OWNER, JOBTYPE.  If the same variable name is defined in more than one file, the proper hierarchical sequence is thus preserved.
$job_optionsthese commands are extracted from the constituent files and are merged into a single $job_options command which is placed into the job instance UJP.
$listfilethese commands are modified to set the OMIT flag on all of them.

Before the job instance UJP is written, a job status file (JST) is written and set to status 10 (new job).  Empty files are written with TXT and JCF extensions.  A SUM file is written with zero total fields and the creation of the job is recorded in the job history.

If the parm1 parameter is empty on return from the function, then no files will have been written.  Otherwise the caller should assume that one or more files might be present and can delete the job, if required, using Job Action 101. If the error value is -7 (instance already exists) the caller is responsible for establishing that it is safe to delete the job.

The function actions are modified if the instance to be created is numbered zero.  This value is reserved for internal use by the CopiaFacts client software.

Job Status:

On successful creation of the job instance, job status is set to 10 (new job).