Manuals/Nbexdoc/ControlFileCommands

NBEXEC Control File Commands

An NBEXEC job is executed by NetBatch when the job is in a READY state and a NetBatch EXECUTOR becomes available.

NBEXEC first validates the control file, and, if it is free from syntax errors, processes it. This processing is designed to simulate the action/reaction of an interactive user at a terminal as closely as possible.

Each command line from the control file is examined to determine the NBEXEC command type.

The first non space character on a command line (the command identifier) identifies the type of command. Only one command may appear in a command line.

The valid command identifiers are:

The valid command identifiers are:
Name	Identifier	Description
Dollar sign	$	Command directives to the NBEXEC process.
Colon	:	Commands that test or alter the job state.
Asterisk	*	user data to be passed to server programs. The * is not passed as part of the data.
Period	.	denotes labels within the control file. Labels are used to control command execution within control file.
Exclamation	!	denotes comments in the control file.

CONSIDERATIONS

A validation pass is made on the control file to detect syntax errors, and undefined labels. Errors detected during this pass result in error message output to the list file and abnormal job termination.
If the NBEXEC Process detects errors during processing of the control file, the job is aborted with a message being output to the control file, unless $ALLOW ERRORS is in effect.

The remainder of this chapter discusses in detail the variables and commands used within the control file.

Control File Execution Defaults

System, Volume and Subvolume

The default system, volume and subvolume are those that were current when the control file was submitted for execution.

This can be changed by use of a :VOLUME or :SYSTEM command within the control file.

A :LOGON command executed in a control file will set the current defaults to the users logon defaults in the same way an interactive LOGON does.

For example:

NBEXEC

:VOLUME $DATA.XYZ
:BATCHCOM;SUBMIT JOB1,IN JOB1

Will run the control file JOB1 with the volume and subvolume defaults of $DATA.XYZ.

Execution Priorities

The default execution priority for processes run from an NBEXEC control file, is calculated as NBEXEC's execution priority minus 1.

Home Terminal

The default home terminal for processes started from an NBEXEC job is the NBEXEC Process itself. This enables programs that write to the home terminal to have this data captured on the list file.

Prompts or reads made to the home terminal are supplied data from the control file, if available. Normally, NBEXEC will be seen as a process by other processes attempting I/O.

Processes built using the COBOL74 ACCEPT or DISPLAY verbs will not communicate with a process. The ID TERM startup command instructs NBEXEC to emulate a non block mode terminal device. This allows programs using the ACCEPT, or DISPLAY statements of COBOL74 to be run under control of NBEXEC.

The home terminal may be specified in the TERM parameter of the control file :RUN command.

:RUN PROG/TERM $TERM30/

CONSIDERATIONS

The default home terminal is logged in the list file as "Self".

PARAMs, ASSIGNs, and DEFINEs

All PARAMs, ASSIGNs and DEFINEs that were current when NBEXEC is submitted, can be passed to processes initiated by that job. The only exceptions to this are PARAMs specifically set up to initialize control file variables (see Job Attachment Sets in the NetBatch Users Guide, and control file variables described later in this section).

PARAMs, ASSIGNs, and DEFINEs may be set in the control file if required.

A maximum of 100 ASSIGNs are allowed. In addition, 1024 bytes of PARAM information can be set up. Each PARAM uses 2 bytes plus the length of the PARAM name in characters plus the length of the PARAM value in characters, where the PARAM value length cannot be more than 255 characters.

Example

To pass the print file ASSIGNment to processes started by the control file CONTROL:

JCF Control

:ASSIGN PRINT-FILE,MYFILE,EXT 16,OUTPUT
:PARAM DEPARTMENT .ACCOUNTS.
:BATCHCOM;SUBMIT CTL,IN CONTROL,J-A-S #C

User

The default user for an executing control file is the user who submitted the file. This may be changed by including a :LOGON command in the control file.

Control File Variables

There are two types of user control file variables - logical variables and string variables.

Control file variables are either user variables or NBEXEC system variables. User variables may be set before queuing a control file by using the command interpreter (TACL) PARAM command. The NBEXEC Process also allows user variables to be defined and modified during control file execution using the $SETL or $SETS commands.

NBEXEC system variables are predefined by NBEXEC and are used to determine process error states and return predefined strings.

A user variable is identified by the first thirty-one characters of its name. The name may be of any length but must contain only alphanumeric characters, up arrows ^ or hyphens -. Names are stored in uppercase. (Note: MIS-Batch only considers the first twelve characters of an identifier).

System control file variables have names beginning with a number sign #.

There are two types of user control file variables - logical variables and string variables. Logical variables may be replaced by a string variable of the same name. The TRUE/FALSE state of a string variable is represented by a "T" or "F" character as the string value. String variables may contain from 0 to 255 characters. A logical and string variable may share a common name. If a logical variable is used as a string, it is assumed to contain the text "TRUE" if TRUE, or "FALSE" if false.

User Control File Variables

LOGICAL VARIABLES

There is a storage limit of limit of 12K bytes for string and logical identifiers and their value. This allows approximately 128 control variables, with an average name length of 14 bytes.

A logical variable can only have the values TRUE or FALSE.

Logical variables are used to control the NBEXEC Process execution path through an NBEXEC control file (see the $IF command for a description of conditional branching).

STRING VARIABLES

There is a storage limit of limit of 12K bytes for string and logical identifiers and their values. This allows approximately 128 strings, with an average name length of 20 bytes and value length of 60 bytes.

A string variable contains a string of 0 to 255 characters.

String variables are used for substitution of variable text into control file commands or user data.

Invoking Variables

A variable identifier appearing between apostrophes ' on any line in a NBEXEC control file defines a substitution to be made before the line is executed by NBEXEC. For substitution to occur, spaces must not occur between the apostrophes.

A variable identifier appearing in the body of a $IF statement, without apostrophes ' is expanded internally by NBEXEC to evaluate the conditional expression.

The form of a variable invocation is

' variable-name [ @ edit-start ] [ : edit-length ] '

where

variable-name: is the name of a system or user defined variable.

edit-start: specifies where, in the data corresponding to variable-name, text extraction should begin. If omitted, the start of data is assumed.
edit-start : is a numeric column address, or a text pattern. If a text pattern is supplied, NBEXEC scans the data searching for the specified pattern. If the pattern is found, text extraction begins after and not including the first occurrence found. If no match is found, then no data is returned.
edit-length: specifies how much data from edit-start is to be extracted. If omitted, the remaining data of variable-name is assumed.

edit-length is a numeric character length, or a text pattern. If a text pattern is supplied, NBEXEC scans the data starting at edit-start searching for the specified pattern. If the pattern is found, text extraction ends just before the first occurrence found. If no match is found, the remaining data is transferred.

Example

!The following commands transfer control to label EOF-LABEL

NBEXEC

$SETS XYZ "FILE: $SYSTEM.ZBAT.JOB, ERROR: 11"
$IF XYZ@"ERROR: " = "11" $GOTO EOF-LABEL
...
.EOF-LABEL
$SETS WINE Moselle
:EDIT $DATA.SUPPLIER.WINELIST;L/'WINE'/;L*+1/*+23;E

After substitution the line above becomes:

:EDIT $DATA.SUPPLIER.WINELIST;L/Moselle/;L*+1/*+23;E