View source for Manuals:NetBatch:NBEXEC/Starting NBexec

== STARTING NBEXEC ==

NBEXEC is invoked by TACL, or specified as a NetBatch EXECUTOR-PROGRAM as follows:
<div style="width: 80ch">
{{terminal|title=TACL|text=
>RUN NBEXEC/NAME [<pname>], IN <control file> &
          [,OUT <list file>]/[<command>,...]
}}
</div>

:or

<div style="width: 80ch">
{{terminal|title=TACL|text=
>BATCHCOM;SUBMIT <job-name>, IN <control file> [,OUT <list file>] &
            , EXECUTOR-PROGRAM NBEXEC &
           [, STARTUP "<command>,..." ]
}}
</div>
:where:

<control file> Is the control file that NBEXEC will execute. This file must be a TANDEM EDIT format file.
<list file>    Is a non disk device, process or disk file to which the output listing is directed.
<command>      Is a string containing one or more NBEXEC startup instructions. <command> is limited by NetBatch to a maximum of forty bytes.
If <list file> is a disk file, the following rules apply:
* If the file does not exist, an entry-sequenced file is created, with a logical record length of 132 characters and with primary and secondary extents set to 10.
* If the file already exists, it must be either entry-sequenced, relative, or unstructured.
* If it is entry-sequenced or relative, then the logical record length at creation will be used. This length need not be greater than 132.
* If unstructured, a logical record length of 132 characters will be presumed.
* The <list file> extent sizes must be chosen to suit the expected amount of output listing.
:If <list file> is left blank, the output is suppressed.
:If the whole OUT option is omitted, the normal defaults apply. For TACL this is usually the home terminal. For NetBatch, this is configured for your scheduler.

==NBEXEC Startup Commands==

NBEXEC startup commands are in the form:
:{{code|[ name [ value ] ] #, ...}}
:where name is an identifier consisting of one or more alphabetic characters, and value is some text associated with the identifier. Alphabetic values must be separated from the name by at least a single space.  Consecutive identifiers may be separated by commas {{button|,}}, or semicolons {{button|;}}.
{| class="wikitable"
|+ Commands may be abbreviated.
|-
! Command 
! Argument(s) 
! {{nowrap|Example}}
! Description
|-
| '''A'''{{small|PPEND}} ||  {{Cross}} || {{nowrap|{{kbd|A}}}}           || Specifies that output is to be appended to the current list file if it exists.  NBEXEC defaults to overwrite the <list file> if one exists.
|-
| '''B'''ACKUPCPU || <cpu> || {{nowrap|{{kbd|B 15}}}} ||  NBEXEC is able to function as a NonStop process. If the primary CPU running NBEXEC fails, a backup copy can takeover, determine what recovery the job may require, and resume execution from the appropriate place in the input control file. The number <cpu> must be the number of an available CPU, and must not be the CPU allocated to the EXECUTOR under which NBEXEC is started.  Use -1 to indicate that NBEXEC should start its backup process in the highest available CPU.
|-
| '''C'''{{small|LASS}}     || <cname> ||  {{nowrap|{{kbd|C&nbsp;payroll}}}} || Specifies <cname> of up to eight alphanumeric characters to appear on the <list file> header page and possibly the spooler REPORTNAME. See the SPOOLREP attribute for details.
|-
|  '''D{{small|PBUG}} || {{Na}} || D || Is used to force NBEXEC to call DEBUG.  This is only useful for debugging purposes when NBEXEC is run at a terminal rather than as a NetBatch job.
|-
| '''ID'''            ||  <id>   || {{nowrap|{{kbd|ID&nbsp;A2345678}}}} || Assigns a name of one alphabetic plus up to seven alpha numeric characters to a job to distinguish it among other jobs on the same <class>.  Lower case characters are upshifted.  This name appears on the job list file.
|-
| '''ID''' || T{{small|ERM}} || {{nowrap|{{kbd|ID&nbsp;T}}}} || An <id> of "TERM" or "T" will cause NBEXEC to emulate a physical terminal, rather than a process. Processes compiled using COBOL74 ACCEPT/DISPLAY verbs will run under control of NBEXEC if ID TERM is specified.  Before using ID TERM, users should be aware that many programs behave differently when they read commands from a terminal. For example, it is common for a program to request a continuation response when a full screen of output has been displayed.
|-
| '''L'''{{small|ABEL}} || <label> ||  {{nowrap|{{kbd|L WORK010}}}} || Causes NBEXEC processing to begin at the specified label in the control file.
|-
| '''L'''{{small|IMIT}} || <hh:mm> ||  {{nowrap|{{kbd|L 02:00}}}}   || Specifies a maximum time limit for the NBEXEC job. Must be between 00:00 and 99:59, with the default being 01:00 (one hour).
<br>
NBEXEC will abort the job once this limit is exceeded logging the fact to <list file>. Jobs will issue a warning message to both the job list file and the supervisor log 15 minutes before timing out.
|-
| '''N'''{{small|AME}} || <mname> ||  {{nowrap|{{kbd|N JOB45679}}}} || Specifies a name of up to eight alphanumeric characters to appear on the <list file> header page. It will be used by NBEXEC  when identifying itself in $MESSAGE commands (rather than the control file name) and it can be used when building a spooler REPORTNAME attribute for the <list file>. See the SPOOLREP attribute for details.
|-
| '''P'''{{small|RGE}} || {{na}} || {{nowrap|{{kbd|P}}}} || Specifies that the list file will be purged if the job terminates successfully. Therefore, if
<br>
::$IF #ERROR returned TRUE,
or 
::$IF NOT #ERROR returned FALSE, or processing errors occurred,

the list file would be created. If the list file is the spooler and the job terminates successfully, the spooler entry is not deleted.
|-
| '''S'''{{small|POOLREP}} || <c> || {{nowrap|{{kbd|S U}}}} || Controls the format of the REPORTNAME spooler attribute when <list file> is a spooler collector.

::{| class="wikitable"
! <c> !! REPORTNAME
|-
| '''C'''{{small|LASS<}} || <cname> grp usr
|-
| '''U'''{{small|SER}}    || GROUP   USER
|-
| '''J'''{{small|OBNAME}} || <mname> grp usr
|}

where <cname> defaults to <mname> which in turn defaults to the <control file> name. GROUP, grp,
and USER, usr correspond to the Guardian90 UserID name and number of the NBEXEC process owner.
|-
| '''SY'''{{small|NTAX}} || {{na}} || {{nowrap|{{kbd|SY}}}} || Is specified to perform syntax validation of control cfile only.

When NBEXEC begins processing a control file, it first scans the file to locate labels, and validate
that there are no obvious syntax errors. If errorsare detected, the job will terminate immediately.
If SYNTAX was specified, the job always terminates after the syntax check. SYNTAX would normally beused immediately after altering a control file to verify that no mistakes were made.
|-
| '''X'''{{small|PRI}}  || <xpri> || {{nowrap|{{kbd|X #}}}} ||
|-
| Example || Example || Example || Example
|}

==Examples==

The following example shows how to prevent NBEXEC from running more than two hours:
<div style="width: 80ch">
{{terminal|title=TACL|text=1> NBEXEC/NAME, IN X, OUT $S/L2:0}}
</div>
or via $ZBAT, the default NetBatch scheduler:

<div style="width: 80ch">
{{terminal|title=TACL|text=1> BATCHCOM; SUBMIT REPORT,IN REPORT,OUT $S, STARTUP "L E-O-M,L2:0"}}
</div>

{{kbd|L}} is an abbreviation of the command "LIMIT".  "LIMIT" is the command used to specify a time limit for a job, while "2:0" is the value accompanying "LIMIT".
{{kbd|L}} is also a valid abbreviation of the command "LABEL".

The following example shows how to make NBEXEC emulate a physical terminal for use by the processes created during the job:

<div style="width: 80ch">
{{terminal|title=TACL|text=2> NBEXEC/IN COMP/ID T}}
</div>
The following example shows how to make NBEXEC perform a syntax check on a single control file:
<div style="width: 80ch">
{{terminal|title=TACL|text=3> NBEXEC/IN CTRL/SY}}
</div>