jCL

Man Page Index

This section shows how to write and execute jCL  (jBASE Command Language) programs. It also discusses how jCL manipulates data in the various buffers and selects registers.

Most of the following text assumes that you will be using the functionally superior PQN variant of the jCL  language. The PQ and PQN Differences section discusses the differences between the two variants.

JCL PROGRAM  STRUCTURE

A jCL  program is stored as a text record in a file.

The first line of a jCL  program is PQ or PQN.

Note: On jBASE 3, a jCL program can be run as a UNIX executable script by replacing the first line with: #!usr/jbc/bin/jpq or #!usr/jbc/bin/jpqn. This functionality has been deprecated on jBASE 4 (and later) due to the fact that the thread model must run this as a new process, thus acquiring a new port number and license token.

Subsequent lines contain jCL  statements that can execute other programs, manipulate data in the buffers, and control the flow of program execution and so on.

jCL  program statements comprise a numeric label (optional), a command and any command arguments.

There are many facilities, which enable you to control program flow and to call (and return) or jump to other jCL  programs. You can also construct internal or external subroutines.

LABELS

Labels appear at the start of a line and are always numeric (1, 330, 1000, etc.). You should always put at least one space between the label and the statement.

GROUPING COMMANDS

You can place more than one command on a line by separating each command with a subvalue mark character (x"FC" - entered by typing <ctrl \>). The commands will be executed sequentially, left to right.

Some commands cannot be grouped on the same line because they require one or more dedicated lines in the program. These commands are:

( ), [ ], B, BO, F, F;

FB, F-CLEAR, F-FREE, F-KLOSE , F-OPEN , F-READ

F-UREAD, F-WRITE , GOSUB , H, IBH, IH

MVA, MVD, O, P, RI, RO

RSUB, RTN, U, X,

Lines, which are a continuation of a T or L command from a previous line, are also not suitable for grouping.

The M (Mark) command can be followed by other commands on the same line, but it must be the first command on a line. Commands following the M command, on the same line must be separated by a subvalue mark rather than a space (unlike numeric labels).

COMMENT LINES

Command line which start with a "C" or an "*" are treated as comments.

If you include a comment in a multiple command line, anything between the "C" or "*" and a following a subvalue mark (or the end of the line) will be ignored.

A label will remain active if the "C" or "*" is placed after it on the line.

EXECUTING JCL PROGRAMS

jCL  programs can be executed in several ways:

you can the enter the name of the program from jSHELL,
you can "jump to" another jCL  program of the same type by using the ( ) command,
you can "call" another jCL program of the same type, as a subroutine, by using the [ ] command,
you can use a PERFORM , EXECUTE or CHAIN  statement from a jBC  program, or
you can convert the program to a UNIX executable and call it from any shell. Change the first line to #!usr/jbc/bin/jpq and then use chmod to create an executable file.

Once you start a jCL  program, it will remain active until:

control is explicitly passed to another jCL  program

the jCL  program is explicitly exited

all of the lines of the jCL  program are exhausted

a fatal error is encountered.

Even when the jCL  program temporarily passes control to another process such as jED  or jBC , it will still remain in control (unless control is passed to a jBC program which then CHAINs or ENTERs another jCL program). Exiting from the called process will return control to the jCL program.

If you do not want to store the main body your jCL  program in the MD file, you can create a "pointer" jCL program in the MD. For example, to run a jCL program called DAILY which is held a file called REPORTS, create an MD entry like this:

DAILYYREPORT
001 PQN
002 (REPORTS DAILY)

This will chain to jCL  program DAILY in file REPORTS.

Note that the "pointer" program and the "pointed to" program can have the same name.

LOGIN  JCL PROGRAMS

You can create jCL  programs, which will be run automatically, each time a user logs in or logs in to a specific account. Simply create a jCL program with the same name as the account or user, and put "jshell -" on the last line of the login script (usually ".profile").

This feature can be used for example, to configure the jSHELL environment, implement a security system, or display an initial menu.

For example, let's assume that all users who login to an account called SALES must be offered an initial menu, which is a jBC  program, called MENU held in a file called PROGS. You would create a jCL  program in the MD of the SALES account and call it SALES like this:

SALES
001 PQN
002 HRUN PROGS MENU
003 P

Each time a user logs in to the SALES account, the system will search for a program called SALES in the MD of the account. The jCL  program will then run the MENU program from the PROGS file.

INTERNAL DATA STORAGE

jCL  programs use a series of buffers to store and manipulate data internally. jCL uses these buffers in much the same way as variables in a jBC  program.

The four main buffers are classed as "input" and "output", and sub-classed as "primary" and "secondary".

Nine file buffers are provided to allow data to be moved to and from file records. There is also a "fast" file buffer to give you quick access to records.

In addition to the main input/output and file buffers, there is a range of five "select" buffers, which are used to manipulate, lists (typically record keys).

You will need a thorough understanding of the way in which these buffers work if you want to write (or maintain) anything other than very simple jCL  programs.

The four jCL  main buffers are:

primary input buffer (PIB)

secondary input buffer (SIB)

primary output buffer (POB)

secondary output buffer (SOB)

Typically, the input buffers are used to receive and manipulate data, and the output buffers are used to issue shell commands to the system.

Most of the time you will use the primary buffers as the active buffers. The secondary buffers (particularly the secondary input buffer) are used by very few jCL  commands.

PRIMARY INPUT BUFFER

The primary input buffer is a work area. It can be used to collect terminal input or for temporary storage of control parameters.

Reference individual parameters within the PIB by preceding the parameter number with a percent sign (for example, %3)

When you start a jCL  program, the PIB will contain the jCL program name and any supplied arguments, exactly as they were entered.

When you execute a jCL  program from a jBC  CHAIN , EXECUTE/PERFORM  statement, the PIB will contain the CHAIN, EXECUTE or PERFORM command.

If you execute a jBC  program from jCL , you can access the contents of the PIB from jBC with the PROCREAD  and PROCWRITE  statements. Control returns to the jCL program when the jBC program ends - unless control is passed to a jBC program, which then CHAINs or ENTERs another jCL program.

SECONDARY INPUT BUFFER

The secondary input buffer has three main roles:

collection of input from the terminal when an IN command is used,
collection of error codes generated from executed programs and jQL  queries (see the IF E command), and
collection of spooler hold file numbers in the form Entry # n, where n is the hold file number.

Data in the SIB is overwritten each time you use one of these facilities.

When the primary input buffer is active, you can use the MS command to copy the entire contents of the secondary input buffer to the primary input buffer.

PRIMARY OUTPUT BUFFER

The primary output buffer is used to build shell commands, which are submitted for processing when the P command is executed. With the exception of other jCL  programs and the LOGTO command, you can construct and execute any shell command in this way.

You should always use a jCL  transfer function when invoking one jCL program from another.

A carriage return is automatically placed at the end of the command in the POB when it is executed by the P command.

SECONDARY OUTPUT BUFFER

The secondary output buffer is used to provide a "stack" of responses to be fed into interactive processes, such as jBC  or jED , when they request input.

The SOB becomes active when you use the STON (stack on) command. You can then place data in the SOB before you execute say, a jBC  program.

The stacked data is used to respond to INPUT requests, instead of taking input from the keyboard - rather like the DATA statement in a jBC  program.

Note that the same internal storage area is used for both the SOB and the jBC  DATA statement. If your jCL  program is called from a CHAIN , EXECUTE or PERFORM  statement in a jBC program, any data placed in the stack by a DATA statement will be used by jCL input statements.

If a jCL  program is executed directly from the shell, the SOB will be cleared before the program starts.

Terminate each line of data placed in the SOB using the H command by typing a less-than character (<) to represent a carriage return.

Older systems required you to use a line continuation symbol (two less - than characters "<<") if you wanted to put more than 140 characters into the buffer. Although this functionality is still supported, you do not need to use the line continuation symbol in jBASE.

ACTIVE INPUT BUFFER

Many commands access the currently active input buffer rather than referring specifically to the primary or secondary areas. These include the A and Ap forms of the A command, and the B, D (without parameter), F, IBH, IH, IP and Sp commands.

When an IN or IBN command is executed, when the SIB will become the active input buffer. The SIB will then remain active until an RI, S (n) or MV %n source command is executed.

Be careful when using these commands. Try to structure your programs in such a way as to minimise the possible confusion between which buffer is currently active. As a minimum, include as many comments as you can.

ACTIVE OUTPUT BUFFER

When a jCL  program is executed from the shell or you issue a STOFF (Stack Off) command, the POB becomes the active output buffer.

The SOB only becomes active when you use a STON (Stack On) command.

You can refer to the parameters in the active output buffer by using a hash sign (#).

Some operations, such as COPY and EDIT, need two buffers and you will need to switch between the buffers when creating these commands. The Primary buffer holds the command (as it would be entered at the shell prompt) and the secondary buffer holds any further input required by the command. If you fail to specify any required input in the secondary buffer, it will be prompted for at run time

BUFFER DATA AND POINTERS

Data in the input and output buffers is held as a series of parameters separated by blanks (PQ) or field marks (PQN).

You can refer directly to a specific parameter by using the parameter's sequence number. For example, you might refer to the 10th parameter as %10.

Alternatively, you can refer to the data in terms of its column (or character) position. For example, you might refer to the 21st column (character) of the primary input buffer as S(21).

Four buffer pointers are used:

one for each of the active input buffers

one for each of the output buffers

In the examples which follow, the buffer pointers are indicated by an up arrow like this a.

Field marks (the parameter separators in PQN-style jCL  programs) are indicated by a carat like this ^.

The input buffer pointer points to a position in the active input buffer. You can move the pointer without affecting the data in the buffer by using the S, F and B commands. The S command positions the input buffer pointer to a specific location, while the F and B commands move the pointer forward or backward over the parameters.

Each output buffer has its own pointer. These pointers always indicate the end of the parameter data. If you move the pointer backwards and write data to the new position, the original data at the end of the buffer will be truncated.

The BO command is used to move the primary output buffer pointer back one parameter, or to clear the secondary output buffer.

FILE BUFFERS

jCL  provides nine file buffers, numbered from 1 to 9. The file buffers are used as the medium for transferring data from and to files - reading and writing.

You should always open file buffers before you use them for reading or writing. They can also be used as temporary data storage areas.

The data held in a file buffer (like a database record) is divided into fields, which are separated by field marks. If you refer to a field beyond the last field, the required number of additional fields (with null values) is created.

File buffer references are constructed by specifying an ampersand (&), followed by the file buffer number, a period (.) and then a numeric value (which might be an indirect reference) to define the field number you want.

For example, if file buffer 4 contains:

000 TEST1
001 ABC
002 DEF
003 GHI
004 JKL

&4.2 refers to the second field in file buffer 4 - in this case DEF, and &4.0 refers to the record key of the record in file buffer 4 - in this case TEST1.

The record key will be null until you perform a read operation or until you move data into field 0 of the file buffer.

The FB command provides a special "Fast  Buffer" facility. You can use FB to read a record from a file into the fast buffer without having to open the file first. There is only one fast buffer. The fields are referred to as &n, where n is the field number. Any existing data is overwritten each time you use the FB command.

SELECT  REGISTERS

Select registers are used to hold a list of record keys or other multi-valued fields, which have been generated by shell commands that produce lists. These include BSELECT, ESEARCH, FORM-LIST, GET-LIST, QSELECT, SEARCH, SELECT  and SSELECT . Having executed one of these commands, you should use the PQ-SELECT  and PQ-RESELECT  jCL  commands to load or reset the select registers.

Five select registers (numbered from 1 to 5) are provided. Each can contain a separate list.

The select registers are accessed to by using an exclamation mark (!) followed by the register number - for example !2. Each time a select register is accessed, the next field is taken from the top of the list.

You cannot manipulate the values in a select register. If you write to a select register, say with the MV command, the whole list will be replaced. If you want to use a value more than once, move it to another buffer for temporary storage.
For example, if the Select Register contains

KEY1^KEY2^KEY3^KEY4^...

The first access will retrieve KEY1, the second KEY2, the third KEY3 and so on.

BUFFER REFERENCES

Buffer reference symbols can be used to make direct or indirect references to the input and output buffers and the file buffers. You can only make direct references to the select registers.

Four special symbols are used:

% for the primary input buffer.
# for the active output buffer.
& for a file buffer or the "fast" buffer.
! for a select register.

Referencing the primary input buffer or the active output buffer will not reposition the pointer.

Use the appropriate symbol with a literal value to use direct reference. For example:

% 23 Refers to the 23rd parameter in the primary input buffer.

#4 Refers to the 4th parameter in the current output buffer.

&4.19 Refers to field 19 in file buffer 4.

!3 Refers to the next value in select register 3.

Use a combination of symbols and literal values to create an indirect reference. For example:

% %3 Refers to the %3th parameter in the primary input buffer. If say, %3 contained the value 10, this example would refer to the 10th parameter of the primary input buffer.
&4.%5 Refers to the field in file buffer 4 defined by %5.

Indirect references can only be made to the primary input buffer (%), the active output buffer (#) or a file buffer (&). If the resulting value is non-numeric, a zero is used. In the case of the file buffer (&), you may only use an indirect reference to the parameter, not the file buffer number - for example, &5.%3 is legal, &%3.5 is not.

Direct or indirect buffer references can be used with the following jCL  commands:

( ), F-OPEN , IBH, IFN, MVA
[ ], F-READ , IBP, IH, MVD
F;, F-UREAD, IF, IP, RI
F-FREE, FB, IF (multivalued), L, S
F-CLOSE, H, IF (mask), MV, T

BRANCHING

Wherever possible, avoid using the obsolete "M"ark command to control branching within the program. Using labels and the GO  command will help to preserve clarity and make program maintenance much easier.

GROUPING COMMANDS

You can put more than one jCL  command on the same line by using a subvalue mark. For example:

001 PQN
002 10T "Enter file name :",+
003 IBP %1
004 F-O 1 %1
005 T "Cannot open ", %1, "..."\ GO  10
006 T "File ", %1, " opened OK"

In this example, if the file cannot be opened by the F-O command, the line immediately following the command will be executed (see the F-O command for details). If the file is opened, the next but one line will be executed. By grouping an error message and a branch on the "error" line (005), you will avoid the necessity of creating a separate subroutine to handle the error condition.

Note that you cannot use grouping like this where a command relies on a particular line structure - the F-O command for example.

You can use a mark with the ctrl \> but it must be the first jCL  command on the line. For example, use:

M \ IBP:%1 \ IF # %1 X

not:

IBP %1 \ M \ IF # %1 X

READABILITY

To increase readability and make it easier to edit and debug your jCL  program, you can indent lines by using leading blanks.

The incorporation of useful comments, using the C or * commands, will help with the future maintenance of your programs.

TIME  AND DATE

The following commands provide a simple way of putting the current system time and date into the currently active input buffer:

S21
U147F
T

Puts the current time, in internal format (seconds since midnight), in the current input buffer (in this case, %21).

S10
U147F
D

Puts the current date, in internal format (days since 31 Dec 67), in the current input buffer (in this case, %10).

S8
U147F
T MTS

Puts the current time, in external format (MTS yields hh:mm:ss), in the current input buffer (in this case, %8).

S33
U147F
D D2/

Puts the current date, in external format (D2/ yields dd/mm/yy or mm/dd/yy - depending on your internationalization settings), in the current input buffer (in this case, %33).

VALIDATING DATE AND TIME

You can use pattern matching to input a valid date or time but it does not catch input like 10/32/94 or 25:25:25.

The example below checks for a valid date in D2/ format by converting it. This mechanism works because an invalid date converts to null.

001 PQN
002 10 T "Enter date (mm/dd/yy) :", +
003 IF # %1 XFinished
004 IBP %1
005 MV %2 "
006 IBH%1;D2/;
007 IF # %2 T B,"Oops!"\ GO  10
008 C Date OK

LONG STATEMENTS

To help with program clarity, you can construct long statements by using several H commands. Make sure there is a space at the end the first H command or before the second (and subsequent) commands. For example:

001 PQN
002 HGET-LIST listname
003 STON
004 P
005 HSORT filename WITH ...
006 H HEADING "..."
007 P

Older systems required you to use a line continuation symbol (two less- than characters "<<" the buffer. Although this functionality is still supported, you do not need to use the line continuation symbol in jBASE.

CONCATENATION

Use an asterisk (*) to concatenate (join) a series of values. For example:

001 PQN
002 MV %2 "string"
003 MV %1 "Text "*%2*" has been concatenated"
004 T %1

will display "Text string has been concatenated".

SPOOLER  HOLD FILE NUMBERS

If a hold file is generated while a jCL  program is executing, the hold file number is returned as an error message number in the secondary input buffer.

Hold file numbers are returned as Entry #n, where "n" is the hold file number, so that you can distinguish them from "real" error message numbers.

JCL COMMANDS

This section begins with a brief summary of the jCL  commands, organized by function. Each jCL command is then described, in alphabetical order.

INPUT BUFFER COMMANDS

OUTPUT BUFFER COMMANDS

DATA MOVEMENT COMMANDS

INPUT/OUTPUT BUFFER OPERATIONS

JUMP AND BRANCH OPERATIONS

CONDITIONAL OPERATIONS

FILE OPERATIONS

ARITHMETIC OPERATORS

PROCESSING

TERMINAL AND PRINTER  OUTPUT

DEBUGGING

EXITING

Terminates the current jCL  program and begins execution of (chains to) another jCL program.

COMMAND SYNTAX

({DICT} file-name{, data-section-name} {key}) {label}

SYNTAX ELEMENTS

DICT specifies the dictionary section of file-name, if required.

file-name is the name of the file that contains the jCL  program to be executed. Can be a literal, or a direct or indirect reference to a buffer or select register.

data-section-name specifies an alternative data section of the file. Can be a literal, or a direct or indirect reference to a buffer or select register.

key is the name of the jCL  program to be executed. Can be a literal, or a direct or indirect reference to a buffer or select register. If key is not specified, the current parameter in the active input buffer will be used.

label specifies a label in the target jCL  program from which to start execution.

NOTES

The ( ) command terminates the current jCL  program and begins execution of another jCL program, of the same type.

The input buffers, output buffers, and file buffers are all passed to the second program, and all open files stay open.

The ( ) command is often used in the MD to "point" to another jCL  program, which contains the main body of code. See example 1.

The ( ) command can also be used to divide large jCL  programs into smaller units, minimizing the search time for labels.

Using the ( ) command (or the [ ] command), will ensure that the contents of all buffers are available to the target program. If this is not a consideration, you can execute another jCL  program with the P command (see later).

EXAMPLE 1

MENU
001 PQN
002 (JCL MENU2)

Immediately executes another jCL  program called MENU2 in the file called JCL.

EXAMPLE 2

MENU
001 PQN
002 (JCLFILE)

When the word MENU is entered from the shell, it will be placed in parameter 1 of the primary input buffer - %1. The program will then unconditionally pass control to the MENU program in file JCLFILE.

EXAMPLE 3

DOIT
001 PQ
002 IP?
003 (JCL)

This example will prompt for the name of another jCL  program and continue execution with the named jCL program in the file called JCL.

EXAMPLE 4

MENU
001 PQN
002 (JCL MENU2) 300

Immediately executes another jCL  program called MENU2 in the file called JCL. Execution of MENU2 will begin at label 300.[ ]

Calls another jCL  program as an external subroutine.

COMMAND SYNTAX

[{DICT} file-name{, data-section-name} {key}] {label}

SYNTAX ELEMENTS

DICT specifies the dictionary level of file-name, if required.

file-name is the name of the file that contains the jCL  program subroutine. Can be a literal, or a direct or indirect reference to a buffer or select register.

data-section-name specifies an alternative data section of the file (default is the same name as the dictionary). Can be a literal, or a direct or indirect reference to a buffer or select register.

key is the name of the jCL  program to be executed. Can be a literal, or a direct or indirect reference to a buffer or select register. If key is not specified, the current parameter in the active input buffer will be used.

label specifies a label in the target jCL  program from which to start execution. Use of the label clause makes this command synonymous with the GOSUB  command.

NOTES

Input buffers, output buffers, and file buffers are all passed through to the called program, and all open files stay open.

External subroutines can call other subroutines. There is no limit to the number of calls that you can make but the jCL  programs must be of the same type.

When an RTN is encountered, control is returned to the calling jCL  program. If an RTN is not encountered, execution will terminate at the end of the called program.

EXAMPLE

001 PQN
002 [SUBS  SUB1]
003 ...

Calls the jCL  program SUB1 in the SUBS  file as an external subroutine.

+

Adds an integer value to the current parameter in the active input buffer.

COMMAND SYNTAX

+n

SYNTAX ELEMENTS

n is the integer to be added.

NOTES

If the number of characters in a parameter increases as a result of the + command, the other parameters will be moved to the right.

If a parameter is preceded by a + sign, the sign will be replaced by a zero.

If the buffer pointer is at the end of the buffer, a new parameter will be created.

If the referenced parameter is non-numeric, a zero is used.

EXAMPLE 1

Command PIB Before PIB After

+30 AAA^+20^333 AAA^050^333
a a

EXAMPLE 2

Command PIB Before PIB After

+100 BBB^AA^44 BBB^100^44
a a

EXAMPLE 3

Command PIB Before PIB After

+51 ABC^0000^55 ABC^0051^55
a a

COMMAND SYNTAX

-n

SYNTAX ELEMENTS

n is the integer to be subtracted.

NOTES

If the number of characters within a parameter decreases with a - command, the result is prefixed with zeros to maintain the same number of characters as the original value.

Parameters within the input buffer can be preceded by a minus sign. If the buffer pointer is at the end of the buffer, a new parameter will be created. If the referenced parameter is non-numeric, a zero is used.

EXAMPLE 1

Command PIB Before PIB After

-300 AAA^345^666 AAA^045^666
a a

EXAMPLE 2

Command PIB Before PIB After

-20 AAA^ABC^666 AAA^-20^666

a a

EXAMPLE 3

Command PIB Before PIB After

-50 AAA^-50^666 AAA^-100^666
a a

EXAMPLE 4

001 PQN
002 OEnter a number+
003 S5
004 IBP
005 +7
006 T %5
007 -3
008 T %5
009 RTN

This example receives input from the terminal and places it in the 5th parameter of the primary input buffer. It adds 7 to the value stored in the 5th parameter and displays the result. It then subtracts 3 from the result and displays the new value.

jCL  Statements

PARAGRAPHS

Paragraphs can only be invoked automatically via the jshell, jsh, when executing in jsh mode. The jshell, in jsh mode, will attempt to read the first parameter of an entered command from the MD/VOC file as previously specified by the JEDIFILENAME_MD environment variable . If the record is determined to be a paragraph record then the paragraph interpreter, para, is invoked. A logon paragraph record can also be invoked by the jshell via the dash option, alternatively the paragraph record can be invoked from the command line using the paragraph interpreter.

e.g. para ./VOC/PARAGRAPHX

Format
The first line of a paragraph record begins with PA e.g.
PARAGRAPHX
001 PA

This line can then be followed by any of the following :
Comment
Any Line preceded by an asterisk. e.g.:
* THIS IS A COMMENT LINE
Label
Any non-spaced text suffixed by a colon. e.g.:
Label:

Paragraph Prompt
A paragraph prompt to obtain values, e.g.:
<<I2,Second,1N>>

Load parameter two from the command line into PromptId Second. If parameter two on the command line is null then prompt for value for Second ensure validates to 1 numeric. The paragraph prompt is formatted as follows:

<<{Code,}PromptId{,Mask}>>

Code

PromptId   Identifier used to name prompt values.

Mask  Validate Input
Pattern Match
e.g. 0N - Match any numerics
7X - Match seven printable characters.
3A - Match three alpha characters.
text - Match text
(Conversion)
e.g. (D2/) - Match date dd/mm/yy or mm/dd/yy.

~~Mask means input should NOT  match mask.

Note: A Paragraph prompt not mixed with a command line or paragraph statement will attempt to execute the resultant value.

Paragraph Statement

One of the following syntax statements.

IF Expression THEN Statement

where:
Expression - Includes PromptId, operators and/or @variables

Operators include MATCHES, EQ, LE, LT, etc.

Command
Any executable command with or without paragraph prompts. e.g:

SSELECT <<I2,FILEX,10X>>

or

SELECT  FILEX

EXAMPLES

PARAGRAPHX
001 PA
002 IF <<C3,THIRD>> EQ THEN GO  CHK.SECOND
003 DISPLAY GOT 3 ARGUMENTS
004 GO END
004 CHK.SECOND:
005 IF <<C2,SECOND>> EQ THEN GO END
006 DISPLAY GOT 2 ARGUMENTS
007 END:

PARAGRAPHX
001 PA
002 * This is an example paragraph
003 IF<<C2,COMMAND>> NE THEN GO  DO.CMD
004 DISPLAY ENTER
005 CLEARPROMPTS
006 DO.CMD:
007 DISPLAY ENTER

PQ AND PQN  DIFFERENCES

The first line of a jCL  program defines the program as one of two basic types, a PQ or a PQN style program.

Wherever possible, you should use the PQN style.

There are several differences between the two styles, as outlined in the following topics.

DELIMITERS

PQ-style programs usually use a blank as the delimiter between parameters in the buffers. PQN-style programs usually use a field mark.

PQN allows parameters to be null or contain blanks and more closely mirrors the native record structure.

PQ commands are still supported for compatibility but you should use the functionally superior PQN commands in new or revised jCL  programs.

When pointers are moved, PQ commands will generally leave the pointer at the first character of a parameter. PQN commands will generally leave the pointer at a field mark.

Commands affected by this difference are A, B, BO, F, H, IH and IP.

BUFFERS

Buffer referencing, file buffers and select registers are only available with PQN commands.

COMMANDS

These commands are only used in PQN-style jCL  programs:

F;, F-KLOSE , F-WRITE , L, MVD F-CLEAR, F-OPEN , FB, MS,
F-DELETE, F-READ , IBH, MV,
F-FREE, F-UREAD, IBP, MVA,

These commands are functionally equivalent in both PQ and PQN-style programs:

( ), G, IF E, RSUB, U
[], GO  B, IFN, RTN, X
+, GO F, M, S,
-, GOSUB , P, STOFF,
C, IF, RI, STON,

JCL PQ-SELECT

Executed from a jCL  program, loads a list of keys into a select register.

COMMAND SYNTAX

PQ-SELECT  register-number

SYNTAX ELEMENTS

register number is the number of the select register (1 to 5) in which the keys are to be placed.

NOTES

To use PQ-SELECT  you must first construct a list by using one of the list processing commands such as SELECT, SSELECT , QSELECT, BSELECT, GET-LIST, FORM-LIST, SEARCH or ESEARCH. Put the PQ-SELECT  command in the stack so that it will be processed as part of the external job stream when the required list is active.

Retrieve the list elements one at a time, using a "!n" direct or an indirect reference.

You cannot execute PQ-SELECT  directly from the shell.

EXAMPLE

001 PQN
002 HSSELECT SALES
003 STON
004 HPQ-SELECT  1
005 P
006 10 MV %1 !1
007 IF # %1 X Done
008 T %1
009 GO  10

This example selects all the records in the SALES file, loads the record-list into select register 1 and displays the keys one at a time.

JCL PQ-RESELECT

Executed from a jCL  program, resets the pointer of a specified select register to the beginning of the list of record keys.

COMMAND SYNTAX

PQ-RESELECT  register-number

SYNTAX ELEMENTS

register-number is the number (1 to 5) of the select register to be reset.

NOTES

This command is executed from the primary output buffer to reset the pointer of a specified select register back to the beginning of the list.

Each time you use the "!" reference to retrieve a value from the list, the value is not destroyed. The pointer is simply advanced to the next parameter in the list. PQ-RESELECT  resets the pointer back to the beginning of the list so that you can perform another pass.

You cannot execute PQ-RESELECT  directly from the shell.

EXAMPLE

HSELECT SALES
STON
HPQ-SELECT  1
PH
MV %1 !1
IF # %1 XNo records selected
HPQ-RESELECT 1
PH
10 MV %1 !1
IF # %1 XFinished
...
GO  10

jCL  Commands

JCL A

Copies a parameter from the active input buffer to the active output buffer.

COMMAND SYNTAX

A{c|\}{p}
A{c|\}{p}({n},m)

SYNTAX ELEMENTS

Notes

Used on its own, the A command will copy the parameter pointed to from the active input buffer to the active output buffer.

The A command can also be used with the IF command.

If the active input buffer pointer is at the end of the buffer, the A command will have no effect.

The c option is often used when you need to surround keys with single quotes, or values with double quotes.

If you include an n or m specification, the PIB will be selected. If the destination is the SOB (stack is "on"), c will be ignored.

If the stack is "off" (the POB is active), the A command will put the data in the output buffer as a separate parameter. The buffer pointers in the primary output buffer will be positioned at the field mark at the end of the copied parameter.

If the stack is "on" (the SOB is active), the A command will concatenate the value to the previous parameter in the output buffer. It will continue to copy until a field mark is encountered. When complete, the buffer pointers will be positioned at the end of the secondary output buffer.

EXAMPLE 1

Note the position of the buffer pointer after you issue the A command.

EXAMPLE 2

Issuing an A"3 command would have achieved the same result, except that the starting position of the PIB pointer would have been immaterial.

EXAMPLE 3

EXAMPLE 4

The command attempts to copy the second parameter from the PIB, starting with the second character, up to and including, the penultimate character, to the current output buffer.

JCL B

Moves the active input buffer pointer back to the previous parameter.

COMMAND SYNTAX

B

NOTES

The input buffer pointer is moved backwards to the preceding field mark or to the beginning of the input buffer. If the pointer is on the first character of a parameter (or a field marker), the pointer will be moved back to the field mark of the previous parameter.

EXAMPLE 1

EXAMPLE 2

JCL BO

Moves the active output buffer pointer back by one parameter.

COMMAND SYNTAX

BO

NOTES

The buffer pointer will move backward until it finds a field mark or the start of the buffer.

To completely clear the buffer, use the RO command. To clear specific parameters, use the MV #n command

EXAMPLE 1

EXAMPLE 2

JCL D

Displays the current parameter of the active input buffer or specific parameters from the PIB.

COMMAND SYNTAX

D{n}{+}

SYNTAX ELEMENTS

n specifies the number of the PIB parameter to be displayed. If n is set to 0 (zero), all parameters in the primary input buffer will be displayed.

+ inhibits a NEWLINE at the end of output.

NOTES

D with no other qualifiers will display the current parameter of the active input buffer.

The pointer position will not be changed.

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

JCL D

Displays the current parameter of the active input buffer or specific parameters from the PIB.

COMMAND SYNTAX

D{n}{+}

SYNTAX ELEMENTS

n specifies the number of the PIB parameter to be displayed. If n is set to 0 (zero), all parameters in the primary input buffer will be displayed.

+ inhibits a NEWLINE at the end of output.

NOTES

D with no other qualifiers will display the current parameter of the active input buffer.

The pointer position will not be changed.

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

JCL DE

Displays the current value of LastError.

COMMAND SYNTAX

DE

NOTES

The DE command is mainly used when debugging your jCL  programs.

EXAMPLE

If LastError contains 404]61^QLNUMSEL, the DE command will display:

404]61^QLNUMSEL

JCL DEBUG

Turns debug function on or off.

COMMAND SYNTAX

DEBUG [ON|OFF]

NOTES

When the DEBUG function is turned on, your jCL  program will be suspended before each command (line) is executed. You will see the program name and the next command to be executed, and you will be prompted to enter one of the following commands:

After each input, the program name and the next line to be executed will be redisplayed, together with any additional information requested (for example, the content of the input buffers).

JCL F

Moves the active input buffer pointer forward to the next parameter.

COMMAND SYNTAX

F

NOTES

The input buffer pointer is moved forward to the next field mark, or to the end of the buffer.

EXAMPLE 1

EXAMPLE 2

JCL.F ;

Provides a range of arithmetic functions.

COMMAND SYNTAX

F;element{;element}...;?[P|r]

SYNTAX ELEMENTS

OPERATORS

OPERANDS

NOTES

The F; command uses a stack processor similar to, the one used by the F; function in jQL .

Commands are processed from left to right.

Each operand pushes a value on to the top of the push-down/pop-up stack.

The result of a calculation can be copied into any buffer with the question mark (?) operator.

EXAMPLE

%2 pushes a value of 8 (the 2nd parameter of the PIB) onto the stack.

-subtracts last entry from penultimate entry, and replaces last entry 1 with the result of 92.

?%3 then copies the result to the 3rd parameter of the PIB, replacing the old value.

JCL F -CLEAR

Clears the specified file buffer.

COMMAND SYNTAX

F-CLEAR file-buffer
F-C file-buffer

SYNTAX ELEMENTS

file-buffer is the number (1 to 9) of the file buffer to be cleared.

NOTES

This command is equivalent to using the MV file-buffer.0 ",_ command

EXAMPLE

001 PQN
002 F-C 1
003 MV &1.0 "Key", "Field 1"

Clear file buffer 1. Set the record key to "Key" and the first field to "Field 1". Functionally equivalent to MV &1.0 "Key", " Field1",_. (Note the use of the underscore character as the last character of the command.)

JCL F -DELETE

Deletes a record from a file.

COMMAND SYNTAX

F-DELETE file-buffer
F-D file-buffer

SYNTAX ELEMENTS

file-buffer is the number (1 to 9) of the file buffer, which is associated with the file containing the record to be deleted.

NOTES

The record specified in field zero (&f.0) of the file buffer will be deleted. If the record does not exist, the command will have no effect.

The content of the file buffer is not altered.

An outstanding record lock will be released.

The file must have been opened with an F-OPEN  command.

EXAMPLE

001 PQN
002 10 T "File name :",+
003 IBP %1
004 F-O 1 %1
005 T "File ", %1, " does not exist!"\ GO  10
006 MV &1.0 "Key"
007 F-D 1

If the file cannot be opened by the F-O command, the line immediately following the command will be executed (see the F-O command). If the file is opened, "Key" is moved into field 0 of file buffer 1. F-D 1 then attempts to delete record "Key" from the file.

JCL F -FREE

Releases a record lock set by the F-UREAD command.

COMMAND SYNTAX

F-FREE {file-buffer {key}}
F-F {file-buffer {key}}

SYNTAX ELEMENTS

file-buffer specifies a file buffer (1 to 9) assigned by an F-OPEN  command.

key is the key of the record to be unlocked. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register.

NOTES

If file-buffer is not specified, all record locks set by the jCL  program on the current port, within the current context level will be released.

If key is not specified, any outstanding locks for the current file will be released.

Record locks are also released by F-WRITE  or F-DELETE commands, and at the end of the jCL  program. Use the LIST-LOCKS command to see which records are currently locked.

EXAMPLE 1

F-FREE

Unlocks all records previously locked by this jCL  program.

EXAMPLE 2

F-FREE 1

Unlocks the record specified by the key in field zero of file buffer 1.

EXAMPLE 3

F-F 1 Key

Unlocks the record "Key" in the file associated with file buffer 1.

JCL F -KLOSE

Closes a specified file buffer.

COMMAND SYNTAX

F-KLOSE  file-buffer
F-K file-buffer

SYNTAX ELEMENTS

file-buffer is the number (1 to 9) of the file buffer to be closed.

NOTES

F-KLOSE  is normally only used when you have finished working with a remote file and need to close it.

EXAMPLE

F-K 1

Closes file buffer 1.

JCL F -OPEN

Clears a file buffer and opens a file for reading and writing.

COMMAND SYNTAX

F-OPEN  file-buffer {DICT} file-name{,data-section-name}
error-cmd-line

F-O file-buffer {DICT} file-name{,data-section-name}
error-cmd-line

SYNTAX ELEMENTS

file-buffer is the number (1 to 9) of the file buffer with which the file is to be associated.

DICT specifies the dictionary section of file-name, if required.

file-name is the name of the file to be opened. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register.

data-section-name specifies an alternative data section of file-name.

error-cmd-line is the line immediately after the F-OPEN  command. Only executed if the specified file cannot be opened.

NOTES

If the file cannot be opened, the line immediately after the F-OPEN  command will be executed. If the file is opened successfully, this line will be ignored.

File buffers are maintained when control is transferred between jCL  programs.

The file will remain open until closed (see the F-KLOSE  command) or until the end of the program.

EXAMPLE

001 PQN
002 F-OPEN  1 SALES
003 X ERROR: Can’t find the Sales File!
004 T C, (5,10), "Welcome to...",+
.
.If the SALES file is opened, execution continues with line 004. Otherwise, the program terminates with an appropriate error message.

JCL F -READ

Reads a record from an open file into a file buffer.

COMMAND SYNTAX

F-READ  file-buffer key
error-cmd-line

F-R file-buffer key
error-cmd-line

SYNTAX ELEMENTS

file-buffer is the number (1 to 9) of the file buffer with which the file is associated.

key is the key of the record to be read. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register.

error-cmd-line is the line immediately after the F-READ  command. Only executed if the specified record cannot be read.

NOTES

If an associated file has not been opened (see the F-OPEN  command), the program will terminate with an error message.

If the specified record is not on file, the line immediately following the F-READ  command will be executed. If the read is successful, this line will be ignored.

EXAMPLE

001 PQN
002 F-OPEN  1 SALES
003 X ERROR: Can’t find the Sales File!
004 T C, (5, 10), "Welcome to...",+
...
015 F-READ  1 ABC
016 X ERROR: Record ABC not found!
017 T "Record ABC found"

Attempts to read record ABC from the SALES file into file buffer 1. If record ABC is not found, the program terminates with an appropriate error message. If the record is found, the message on line 17 is displayed and execution continues.

JCL F -UREAD

Reads and locks a record from an open file into a file buffer.

COMMAND SYNTAX

F-UREAD file-buffer key
error-cmd-line

F-UR file-buffer key
error-cmd-line

SYNTAX ELEMENTS

file-buffer is the number (1 to 9) of the file buffer with which the file is associated.

key is the key of the record to be read and locked. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register.

error-cmd-line is the line immediately after the F-UREAD command. Only executed if the specified record cannot be read.

NOTES

The F-UREAD command is identical to the F-READ  command, except that it also locks the record against access by another process, thus eliminating simultaneous updates.

If you attempt to F-UREAD a record, which is already locked, execution will be suspended until the other process unlocks the record.

Record locks are released by F-DELETE, F-WRITE  or F-FREE commands, or when the program terminates.

It is good practice to F-UREAD a record before you create it. This will reserve the key in the file and avoid double updates. Remember though that the command line immediately following the F-UREAD command will be executed because the record does not exist.

JCL F -WRITE

Writes the contents of a file buffer as a record.

COMMAND SYNTAX

F-WRITE  file-buffer
F-W file-buffer

SYNTAX ELEMENTS

file-buffer is the number (1 to 9) of the file buffer with which the target file is associated.

NOTES

The key of the record is contained in field zero of the file buffer. If this field is null, the record will not be written.

F-WRITE  will not alter the contents of the file buffer.

You should not normally attempt to write a record unless you have first locked it with an F-UREAD command. The lock will be released when the F-WRITE  is complete.

If the file has not been opened (see the F-OPEN  command), the program will terminate with an error message.

EXAMPLE

001 PQN
002 F-OPEN  1 SALES
003 X ERROR: Can’t find the Sales File!
004 T C, (5, 10), "Welcome to...",+
.
015 F-UREAD 1 ABC
016 F-F 1 \ G 1002
017 T "Record ABC found"
018 MV &1.2 "Field 2"
019 F-WRITE  1
.

Line 15 reads and locks record ABC in file SALES. If the record does not exist, the lock is released on line 16 and control is transferred to label 1002. If the record is read successfully, field 2 is overwritten on line 18. The record is then written back to the file on line 19 and unlocked.

JCL FB

Reads a record from a file into the special "fast" buffer without having to open the file first.

COMMAND SYNTAX

FB {DICT} file-name{,data-section-name} {key} error-cmd-line
FB ({DICT} file-name{,data-section-name} {key}) error-cmd-line

SYNTAX ELEMENTS

DICT specifies the dictionary section of file-name, if required.

file-name is the name of the file to be opened. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register.

data-section-name specifies an alternative data section of file-name.

key is the key of the record to be read. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register. If key is not specified, the value at the active input buffer
pointer is used to supply the key.

error-cmd-line is the line immediately after the FB command. Only executed if the specified file cannot be opened or the record read.

NOTES

Each time you use the FB command, the previous contents of the buffer will be overwritten.

The FB command is useful if you are only reading one record from a file. Otherwise, you should use the F-OPEN  and F-READ  commands.

If the specified record is not on file, or if the file does not exist, the line immediately following the FB command will be executed. If the read is successful, this line will be ignored.

Subsequent references to the fast buffer use a special syntax. For example, to refer to the second field of a record in the fast buffer, you would use &2.

EXAMPLE 1

001 PQN
002 FB SALES ABC
003 T "ABC not on file" / G 1001
004 MV %3 &2
.

The FB command on line 2 attempts to read record ABC from file SALES. If the record cannot be found for any reason, a message is output and control transferred to label 1001 by line 3. If the record is read successfully, execution continues at line 004, which moves field 2 of the record into parameter 3 of the PIB.

EXAMPLE 2

001 PQN
002 T C, (5, 10), "Name :",+
003 IP %2
004 FB SALES %2
005 T "New record"
006 T "Area :",+
007 IP %3

Here the user is prompted for a name (the record key) and the fast buffer is used to read the record from the SALES file. If the record does not exist, a message is output but processing continues.

JCL GO  B

Transfers control to the statement following the most recent M (mark) command executed.

COMMAND SYNTAX

G B
GO  B
GOTO B

NOTES

GO  B goes back to the last executed M, no matter where it is located in the program.

If a "mark" has not previously been executed, the program will terminate with an error message:

Can't find mark at line n in programname

EXAMPLE 1

001 PQN
.
010 MV #1 "SSELECT  SALES BY MONTH"
011 STON
012 MV #1 "PQ-SELECT  1"
013 P
014 M
015 MV %1 !1
016 IF # %1 GO  F
017 C Process the record
.
025 GO B
026 M

Lines 10 to 13 create a sorted list of the records in the SALES file. After each record is processed, the GO  B command on line 25 returns control to the M command on line 14. When the end of the list is reached, the IF command on line 16 transfers control to the M command on line 26.

EXAMPLE 2

001 PQN
.
009 MV %1 ","
010 M
011 IF # %1 GO  30
012 M
013 IF # %2 GO 40
014 GO 50
015 30 MV %1 "ABC"
016 GO B
017 40 MV %2 "DEF"
018 GO B
019 50 ....

This example simply serves to demonstrate how the GO  B command will remember the last M command rather than search backwards for it. First, the values in %1 and %2 are set to null in line 9 and the M at line 10 is recorded. When control reaches line 11, %1 is tested and control is transferred to label 30 on line 15. The intervening M command (at line 12) is not recorded. Line 15 assigns a value of ABC to %1 and line 16 transfers control back to the M on line 10. %1 does have a value now, so control moves on to line 12 and the M on this line is recorded. Next, %2 is tested at line 13 and control is transferred to label 40 on line 17. When the GO B is processed on line 18, control is transferred back to line 12.

JCL GO  F

Transfers control to the statement containing the next M (mark) command.

COMMAND SYNTAX

G F
GO  F
GOTO F

NOTES

The program is scanned forward from the current line, until the next M command is found. Program execution then jumps to that line.

If an M command cannot be found, the jCL  program will terminate with an error message:

Can't find mark at line n in programname

EXAMPLE

001 PQN
.
005 GO  F
006 10 MV %1 "ABC"
007 MV %6 "DEF"
008 MV %10 "HIJ"
009 M
.

The GO  F command on line 5 causes the program to be scanned from line 6, looking for the next M command. In this case, control will be transferred to line 9.

JCL GOSUB

Transfers control to a specific subroutine.

COMMAND SYNTAX

GOSUB  label
GOSUB label] label... (Multivalued form)

SYNTAX ELEMENTS

label specifies the label, which marks the required subroutine.

NOTES

When an RSUB statement is encountered, control is transferred back to the line immediately following the calling GOSUB .

See also "[ ] {n}" command.

MULTIVALUED  FORM

To use the multivalued form of the GOSUB  command, you must specify one label for each result of a multiple comparison. For example:

IF %2 = A]B]C]D GOSUB  1000]2000]3000]4000

Separate the test values and the destination labels with value marks (ctrl ]).

Note that this is a special case of the GOSUB  command. If you need to mix command types in the resulting actions, you should not use this form of the GOSUB command. You can still achieve the same effect but each result must contain a separate command. For example:

IF %2 = A]B]" GOSUB  1000]GOSUB 2000]XFinished

In this case, if the result of the test for null is true the program will terminate with a suitable message.

EXAMPLE

010 GOSUB  1000
011 T "Returned from GOSUB"
.
031 1000 T "In subroutine"
032 IP %1
033 RSUB

The GOSUB  command on line 10 transfers control to label 1000 on line 31. When the RSUB on line 33 is processed, control returns to line 11.

JCL G / GO  / GOTO

Transfers control unconditionally to another location in the program.

COMMAND SYNTAX

G label
GO  label
GOTO label
GO label] label...  (Multivalued form used with multivalued IF command)

SYNTAX ELEMENTS

label specifies the location from which execution is to continue.

NOTES

If the label has not already been encountered in the program, GOTO will search for the label, from the current position. The target label must be found at the beginning of a command line, separated from the command by at least one space.

If the label cannot be found, or is defined more than once, the program will terminate with an error message.

MULTIVALUED  FORM

To use the multivalued form of the GO  command, you must specify one label for each result of a multiple comparison. For example:

IF %2 = A]B]C]D GO  10]20]30]40

Separate the test values and the destination labels with value marks (ctrl ]).

Note that this is a special case of the GO  command. If you need to mix command types in the resulting actions, you should not use this form of the GO command. You can still achieve the same effect but each value must contain a separate command. For example:

IF %2 = A]B]C]" GO  10]GO 20]GO 30]XFinished

In this case, if the result of the test for null is true the program will terminate with a suitable message.

EXAMPLE 1

001 PQN
002 F-OPEN  1 SALES
003 G 1001
004 T C, (5, 10), "Welcome to...",+
.
087 1001 T "ERROR: Can"t find the Sales File!"
088 IP %99
089 RTN
.

If the SALES file is opened, execution continues with line 004. Otherwise, control is transferred to label 1001 on line 87.

EXAMPLE 2

022 5 T "Option :",+
023 IP %1
024 IF %1 = A]B]C GO  10]20]30
025 GOTO 5
.

This example transfers control to label 10 if "A" is entered, to label 20 if "B" is entered and to label 30 if "C" is entered. If the response is not recognized, control transfers back to label 5.

JCL H

Places a text string in the active output buffer.

COMMAND SYNTAX

Htext-string

SYNTAX ELEMENTS

text-string is the text to be placed in the active output buffer. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register.

NOTES

The H command is used to place a text string in the currently active output buffer. Use the POB, to create a shell command. Use the SOB to create secondary commands (such as PQ-SELECT ) or to "stack" a series of inputs required by the active process.

The string is moved into the buffer starting at the current location of the buffer pointer. At the end of the operation, the buffer pointer will be positioned immediately after the last character in the string.

If quotes are used to delimit the string everything within quotes will be treated as a single field and the string will be moved into the buffer as a single parameter.

If quotes are not used, each group of one or more spaces in the string will be replaced by a field mark as the text is moved into the buffer. Include a leading space if you want to add a new parameter. If you want to concatenate the string to the current buffer parameter, do not use a leading space.

The P command is used to process the contents of the POB and SOB.

USING H WITH THE PRIMARY OUTPUT BUFFER

When the shell command is issued, field marks will be replaced by spaces and a carriage return will be appended automatically.

USING H WITH THE SECONDARY OUTPUT BUFFER

A carriage return is not appended automatically to output from the SOB. Terminate each line with a less than character (<) to represent a carriage return.

EXAMPLE 1

001 PQN
002 HSLEEP 10
003 P

Forces the process to sleep for 10 seconds.

EXAMPLE 2

Note how COPY and SALES have become separate parameters but ABC and -DEF have been concatenated.

EXAMPLE 3

001 PQN
002 HGET-LIST LISTA
003 STON
004 HCOPY SALES<
005 H(SALES.HOLD
006 P

JCL IBH

Places text in the active input buffer whilst retaining embedded spaces and applying any required input/output conversions.

COMMAND SYNTAX

IBHtext
IBHreference;input-conversion;
IBHreference:output-conversion:

SYNTAX ELEMENTS

text is the text to be placed in the active input buffer. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register.

reference is a direct or indirect reference to a buffer or select register.

input-conversion is a jQL  input conversion to be applied to the string before putting it in the buffer.

output-conversion is a jQL  output conversion to be applied to the string before putting it in the buffer.

NOTES

The IBH command works in the same way as the IH command except that the string is moved as a single parameter and all spaces are maintained.

Depending on the position of the buffer pointer, IBH will either replace an existing parameter or adds a new parameter to the end of the input buffer. The rules are as follows:

If the buffer pointer is at the beginning of an existing parameter, that parameter will be replaced with the new string.

If the buffer pointer is within an existing parameter, IBH will concatenate the new string (without inserting a field mark), starting at the current location of the buffer pointer.

If the buffer pointer is at the end of the input buffer, a new parameter will be created and the buffer pointer will be left pointing to the field mark preceding the new parameter.

In all cases, the position of the buffer pointer will remain unchanged.

Conversions containing colons or semicolons will not work (for example IBH;G1;1;).

EXAMPLE 1

 EXAMPLE 2

EXAMPLE 3

File buffer 1 contains:
000 Key
001 11350

JCL IBN

Prompts for input, places the entered data in the secondary input buffer as a single parameter and maintains embedded spaces. The secondary input buffer becomes as the active input buffer.

COMMAND SYNTAX

IBN{c}

SYNTAX ELEMENTS

c is an optional prompt character, which, once used, remains in effect until a new IBN, IBP, IN or IP command is issued. If c is not specified, the prompt character will default to the last prompt character used, or to a colon (:).

NOTES

The IBN command is similar to the IN command except that the input string is placed in the buffer as a single parameter and all spaces are maintained.

The new data replaces the content of the secondary input buffer, and the secondary input buffer will remain active until an RI, S(n) or MV %n source command is used.

If the user responds with ENTER only, a null parameter will be created.

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

JCL IBP

Prompts for input from the terminal. Input data is kept as a single parameter and embedded spaces are retained.

COMMAND SYNTAX

IBP{c{r}}

SYNTAX ELEMENTS

c is an optional prompt character, which, once used, remains in effect until a new IBN, IBP, IN or IP command is issued. If c is not specified, the prompt character will default to the last prompt character used, or to a colon (:).

r is a direct or indirect reference to a buffer or select register which is to receive the data. If you use a reference, the prompt character c must be specified.

NOTES

The IBP command is similar to the IP command except that the input is placed in the buffer as a single parameter and embedded spaces are maintained.

If you do not specify a buffer reference, the active input buffer will be used.

The new data will always replace the parameter pointed to by the buffer pointer but the position of the pointer will not be changed.

If the user responds with RETURN  only, a null parameter will be created.

EXAMPLE 1

Command    PIB Before   Input    PIB After
IBP?       AAA^BBB      CCC      AAA^BBB^CCC
                  ^                     ^

EXAMPLE 2

Command   PIB Before    Input    PIB After
IBP?      AA^BB^CC      XX X     AA^XX X^CC
             ^                      ^

EXAMPLE 3

Command   PIB Before    Input    PIB After
IBP?      ABC^DEF^GHI   <RETURN > ABC^^GHI
             ^                      ^

EXAMPLE 4

Command    File Buffer 2    Input    File Buffer 2
           Before                     After
IBP:&2.2   000 Key          BBB       000 Key
           001 AAA                    001 AAA
           002 XXX                    002 BBB
           003 CCC                    003 CCC

EXAMPLE 5

Command    File Buffer 2    Input    File Buffer 2
           Before                     After
IBP:&2.2   000 Key           <RETURN > 000 Key
           001 AAA                    001 AAA
           002 XXX                    002
           003 CCC                    003 CCC

JCL IF  E

Conditionally executes a command depending on the presence or absence of an error message after running a shell command.

COMMAND SYNTAX

IF {#} E command
IF E operator msg-key command

SYNTAX ELEMENTS

# tests for the absence of an error message.

operator performs a value comparison. Operators are:
=   Equal to
#   Not equal to.

msg-key is the key of a system message from the error file.

command is a valid jCL  command.

NOTES

Any system messages generated as a result of running a shell command (see the P command) will cause the system message number to be placed in the SIB, in multivalue format. The value tested is the first multivalue (the STOP  code) of the error text returned from the last command.

The IF E command is most often used to test for an error condition but can be used to detect any resulting system message. IF # E command tests for the absence of a system message.

Some jCL  commands, particularly those that operate on the PIB, will destroy the contents of the secondary input buffer. You should therefore use the IF E command as soon as control returns from the shell command.

EXAMPLE

021 HCOUNT SALES WITH VALUE > "1000"
022 PH
023 IF E = 401 G 100

If the SALES file does not contain any records, which match the criteria, the system will generate the message "No records counted". Using the PH command will stop the message being output on the terminal but the message key 401 will still be placed in the SIB where it can be detected by line 23.

JCL IF

Allows conditional execution of jCL  commands based on the evaluation of an expression, or the presence (or absence) of a reference.

COMMAND SYNTAX

IF{#} reference command

or

IF reference operator expression command

SYNTAX ELEMENTS

# tests for the absence of a value.

reference can be a direct or indirect reference to a buffer or select register, or an A command without a surround character. Using an A command will not move a value but simply provides a reference to the parameter to be tested.

operator performs a value comparison. Operators are:

expression follows the operator and can be one of the following:

A direct or indirect reference to a buffer or select register.

A string. If the string contains embedded spaces or the first character is an exclamation mark (!), percent sign (%) or ampersand (&), enclose the string in single or double quotes.

A pattern format string. Refer to the IF (with Mask) command.

command is any valid jCL  command.

NOTES

If the test result is true, the command at the end of the statement is executed. If the test yields false, command is ignored and processing continues with the next line.

Buffer pointers will not be moved if you use a direct or indirect reference to a buffer or select register.

Comparative tests are performed on a character-by-character, left-to- right basis. For example, AAB is greater than AAAB and 20 is greater than 100. Use the IFN command if you want to perform numeric comparisons. You can use also perform multiple conditional tests in a single statement. For example:

IF %1 > A IF %1 < D T %1  is B or C

EXAMPLE 1

021 IF %1 T "%1 is not null"
022 IF # %1 T "%1 is null"
023 ...

Line 21 tests for a value in the 1st parameter of the PIB and outputs a message if the parameter is not null. Line 22 tests for opposite case.

EXAMPLE 2

021 IF &1.1 = ABC GO  10
022 MV %3 &1.1
023 10 ...

If &1.1 contains ABC execution will branch to line 23. Otherwise, the value in &1.1 will be moved into %3.

EXAMPLE 3

010 T "Continue (Y/n) :",+
011 IP %1
012 S1
013 IF # A G 10
014 IF A(1,1) = Y G 10
015 IF A(1,1) = y G 10
016 XFinished
017 10 ...

If the user enters Y, y or <ENTER> to the prompt on line 11, execution will continue at label 10 on line 17. Otherwise, the program will terminate.

IF (MULTIVALUED )

Compares an expression with one of several different expressions or values, and conditionally executes one of several commands.

COMMAND SYNTAX

IF reference = expression{]expression}... command{]command]}...
IF reference # expression{]expression}... command.

SYNTAX ELEMENTS

reference can be a direct or indirect reference to a buffer or select register, or an A command without a surround character. Using an A command will not move a value but simply provides a reference to the parameter to be tested.

expression follows the operator and can be one of the following:

A direct or indirect reference to a buffer or select register.

A string. If the string contains embedded spaces or the first character is an exclamation mark (!), percent sign (%) or ampersand (&), enclose the string in single or double quotes.

A pattern format string. Refer to the IF (with Mask) command.

] represents a value mark (Ctrl ])

command is any valid jCL  command.

NOTES

The multivalues feature of the IF command enables one IF statement to be used instead of a series.

Do not use O or X commands unless they are the last in the series. Commands after an O or X will be ignored.

The equal (=) operator, will perform a logical OR on the expressions. If the reference is equal to any expression, the condition is true. If more than one expression is true, the command corresponding to the first true expression is executed. If there are more expressions than commands, and the true expression does not have a corresponding command, the last command in the series will be executed. If there are more commands than expressions, remaining commands are ignored.

If you use the not equal (#) operator, a logical AND is performed on the expressions. The reference must not equal any expression in the series for the condition to be true. In this case, the first command specified is executed. Subsequent commands are ignored.

If a direct or indirect reference to a buffer or select register identifies a multivalued parameter, the same jCL  statement is executed regardless of which of the multivalues is true. This means that each value will not access a different command - as it would have if you had specified it directly in the IF statement. For example:

MV %1 A]B]C]D
IF %1 = X]Y]Z]C GO  10]20]30]40

will cause program execution to continue from label 40.

GO  AND GOSUB  COMMANDS

To use the special multivalued forms of the GO  and GOSUB  commands, you must specify one label for each result of a multiple comparison. For example:

IF %2 = A]B]C]D GO  10]20]30]40

Note that this is a special case of the GO  and GOSUB  commands. If you need to mix command types in the resulting actions, you should not use this form of the GO and GOSUB commands. You can still achieve the same effect but each result must contain a separate command. For example:

IF %2 = A]B]C]" GO  10]GO 20]GO 30]XFinished

In this case, if the result of the test for null is true the program will terminate with a suitable message.

EXAMPLE 1

IF %1 = A]B]C G 10

If %1 is equal to A, B or C, control is transferred to label 10.

EXAMPLE 2

IF %2 # "AA"]&1.1](2N)]" GOSUB  1001

If %2 is not equal to AA, the content of &1.1, two numerics or null, control is transferred to subroutine 1001.

EXAMPLE 3

IF %3 = (#0N)]($ON) GO  10]MV #4 "DOLLARS"

If %3 equals a pound sign (#) followed by any (or no) numerics, control transfers to the statement with label 10.
If %3 equals a dollar sign ($) followed by any (or no) numerics, the string "DOLLARS" is moved into the output buffer.

IF (WITH MASK)

Conditionally executes commands based on a comparison with a specified pattern.

COMMAND SYNTAX

IF reference operator (pattern) command

SYNTAX ELEMENTS

reference can be a direct or indirect reference to a buffer or select register, or an A command without a surround character. Using an A command will not move a value but simply provides a reference to the parameter to be tested.

operator performs a value comparison. Operators are:

=   Equal to.
#   Not equal to.

(pattern) is a format string enclosed in parentheses that tests for a specified numeric, alphanumeric or alphabetic string. A pattern format string can consist of any combination of the following:

For example, the pattern (2N"-"3A"-"2N) specifies a format of two numeric characters, a hyphen, three alphabetic characters, another hyphen and then two numeric characters.

command is a valid jCL  command.

NOTES

0X can only be used as the last specification in a pattern.

A null value will match any of the defined patterns such as (0A), (0N), or (0X).

If you want to test for spaces in the pattern, use double quotes, for example:
IF %n = (2A" "3N" "0X)

Ambiguous literal strings must be enclosed in quotes.

EXAMPLE 1

IF %3 = (3N1A) GO  10

If %3 matches three numerics followed by one alphabetic character, branch to label 10.

EXAMPLE 2

IF &1.2 # (2N"AAA") GOSUB  1001

If &1.2 does not equal two numerics followed by AAA, control will be transferred to subroutine 1001.

EXAMPLE 3

IF %1 # (2N*2A*0N) MV %1 "99*AA*1234"

If %1 does not equal two numerics, an asterisk, two alphabetics, an asterisk, and a number (or no numerics), move a string that does into %1.

EXAMPLE 4

IF &1.1 = ("(6X)") GO  100

If &1.1 contains "(ABC123)", control will be transferred to label 100.

EXAMPLE 5

IF &1.1 = ("("0X")") GO  100

If &1.1 contains "(ABC123)", control will not be transferred to label 100.

EXAMPLE 6

IF &1.1 = ("("0X) GO  100

If &1.1 contains "(ABC123)", control will be transferred to label 100.

JCL IF  S

Conditionally executes a command depending on the presence or absence of an active select list.

COMMAND SYNTAX

IF {#} S command

SYNTAX ELEMENTS

# tests for the absence of an active select list.

command is a valid jCL  command.

NOTES

IF S  will execute command if there is an active select list. IF # S will execute command if there is not an active select list.

EXAMPLE

021 HSELECT SALES WITH VALUE > "1000"
022 PH
023 IF S  G 100

If the SELECT  command generates an active select list, control will be transferred to label 100.

JCL IFN

Allows conditional execution of commands depending on the result of numeric comparisons.

COMMAND SYNTAX

IFN reference operator expression command

SYNTAX ELEMENTS

reference can be a direct or indirect reference to a buffer or select register, or an A command without a surround character. Using an A command will not move a value but simply provides a reference to the parameter to be tested.

operator performs a value comparison. Operators are:

expression can be one of the following:

A direct or indirect reference to a buffer or select register.

A string. If the string contains embedded spaces or the first character is an exclamation mark (!), percent sign (%) or ampersand (&), enclose the string in single or double quotes.

command is a valid jCL  command.

NOTES

IFN tests numbers by value, rather than their ASCII  sequence of characters.

Leading zeros are ignored, as are trailing decimal zeros. For example, if %1 contains 00123.000, IFN %1 = 123 will be true.

If a submitted value equates to null or is non-numeric, zero will be used. Leading plus or minus signs are allowed.

EXAMPLE 1

IFN %1 > 50 G 100

If %1 is greater than 50, control will be transferred to label 100.

EXAMPLE 2

IFN %1 [ 0 G 100

If %1 is less than or equal to 0, control will be transferred to label 100.

EXAMPLE 3

IFN A < %3 G 100

If the current parameter is less than %3, control will be transferred to label 100.

JCL IH

Places a text string in the active input buffer, clears an existing parameter, or creates new null parameters.

COMMAND SYNTAX

IHtext

IHreference;input-conversion;

IHreference:output-conversion:

IH\

IH \

SYNTAX ELEMENTS

text is the text to be placed in the active input buffer. Can be a literal (not enclosed in quotes), or a direct or indirect reference to a buffer or select register. The text must not contain subvalue marks.

reference is a direct or indirect reference to a buffer or select register.

input-conversion is a jQL  input conversion to be applied to the string before putting it in the buffer.

output-conversion is a jQL  output conversion to be applied to the string before putting it in the buffer.

\ (backslash). If there is no preceding space, the current parameter in the active input buffer will be nulled. If there is a preceding space, a new null parameter will be created at the current buffer pointer position. A backslash in any other position will be treated as part of the literal text.

NOTES

Each group of one or more spaces in the text will be replaced with a single field mark, thereby creating new, separate parameters to replace the current single parameter. Leading and trailing spaces within text are ignored.

Use the IBH command if you want to insert text into the active input buffer as a single parameter with all blanks intact.

If the buffer pointer is at the beginning of an existing parameter, that parameter will be replaced by the new text.

If the buffer pointer is in the middle of a parameter, that parameter will be truncated from the current location and the new parameter (without a leading field mark) will be concatenated.

If the buffer pointer is at the end of the input buffer, one or more new parameters will be created.

The position of the buffer pointer will not be changed.

CREATING NULL  PARAMETERS

If the buffer pointer is at the start of a parameter, IH\ will null the parameter. The characters between the field marks are deleted but the field marks are retained.

If the buffer pointer is in the middle of a parameter, IH\ removes the remaining characters, from that point to the end of the parameter.

If the buffer pointer is at the end of the buffer, IH\ creates a new null parameter.

IH \ creates a new null parameter at the position pointed to by the input buffer pointer. Note the space between the H and the backslash character.

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

%3 contains 9873

EXAMPLE 4

This example demonstrates how, in effect, you can replace a space with a field mark within a parameter. The 4th parameter of the PIB is copied back into the same location but the space is replaced by a field mark.

EXAMPLE 5

EXAMPLE 6

This example demonstrates how to truncate a parameter.

EXAMPLE 7

EXAMPLE 8

JCL IN

Prompts for input and places it in the secondary input buffer. Selects the secondary input buffer as the active buffer input.

COMMAND SYNTAX

IN{c}

SYNTAX ELEMENTS

c is an optional prompt character, which, once used, remains in effect until a new IBN, IBP, IN or IP command is issued. If c is not specified, the prompt character will default to the last prompt character used, or to a colon (:).

NOTES

The new data replaces the content of the SIB, and the SIB will remain active until an RI, S(n) or MV %n source command is used.

Leading and trailing spaces are removed and groups of one or more embedded spaces are replaced by a single field mark. Use the IBN command if you want to maintain embedded spaces.

If the user responds with ENTER only, a null parameter will be created.

When the command has been completed, the buffer pointer will be positioned at the beginning of the buffer.

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

JCL IP

Prompts for input and places it into the active input buffer or a nominated buffer.

COMMAND SYNTAX

IP{c{r}}

SYNTAX ELEMENTS

c is an optional prompt character, which, once used, remains in effect until a new IBN, IBP, IN or IP command is issued. If c is not specified, the prompt character will default to the last prompt character used, or to a colon (:).

r is a direct or indirect reference to a buffer or select register which is to receive the data. If you use a reference, the prompt character c must be specified.

NOTES

If you do not specify a buffer reference, the active input buffer will be used.

The new data will replace the parameter at the current buffer pointer position but the pointer will not be moved.

Leading and trailing spaces will be removed and groups of one or more embedded spaces will be replaced by a single field mark. By replacing a parameter with data that contains spaces, you can insert several new parameters.

When you place data containing embedded spaces into a file buffer, the new parameters will replace successive fields in the buffer. For example, if the response to an IP?&2.1 command is:

<SPACE >AA<SPACE><SPACE>BB<SPACE>CC"

fields one, two, and three, of file buffer 2 will be replaced with "AA", "BB", and "CC".

If the user responds with RETURN  only, a null parameter will be created.

If you want to keep the input data exactly as entered, use the IBP command.

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

EXAMPLE 4

EXAMPLE 5

JCL IT

Reads a tape record into the primary input buffer.

COMMAND SYNTAX

IT{C}{A}

SYNTAX ELEMENTS

C performs an EBCDIC to ASCII  conversion before the data is put into the buffer.

A masks 8-bit ASCII  characters to 7 bits (resets the most significant bit to a 0).

NOTES

The IT command will read a tape record into the primary input buffer.

The new data will be placed at the beginning of the buffer and will replace all existing buffer data.

EXAMPLE

JCL L

Formats printed output.

COMMAND SYNTAX

L element{, element}...

SYNTAX ELEMENTS

element can be any of the following:

NOTES

Output from the L command creates (or adds to) a print file.

The print file will remain open until a shell command is issued by using the P command. If the shell command also generates print output, this will be added to the same print file. You can close the print file and avoid any unnecessary output by choosing any shell command, which does not generate print output, or by using the L C command. Alternatively, you can hold the print file open indefinitely by using the O option of the SP-ASSIGN command.

Create continuation lines (which do not start with an L) by terminating each preceding line with a comma (,).

A + specified as the last element the command will cause the output from the next L command to be appended.

If you specify a heading statement (HDR), which contains direct or indirect references, these will be evaluated (and included in the heading) as the command is processed. Subsequent changes to the source values will have no effect on the heading.

EXAMPLE

MV %1 "Quarter 4"
L HDR,"PAGE  ",P,(10),T
L 5,"Sales Report for ",%1

Output:

PAGE  1 10:25:17 10 OCT 1999

Sales Report for Quarter 4

JCL M

Marks a destination for a GO  F or GO B command.

COMMAND SYNTAX

M

NOTES

The M command is used with the GO  B and GO F branch commands to mark the destination of the jump.

As a jCL  program is executed it "remembers" the location of the last M command it passes through. When a GO  B command is encountered, the program can then branch straight back to the remembered location. Remember that an M command must be executed for it to be remembered.

GO  F scans forward from the current location until it finds an M command and then resumes execution from there.

If commands are grouped on a line, the M command must be the first command on the line.

EXAMPLES

See the GO  B and GO F commands for examples of usage.

JCL MS

Move the entire content of the secondary input buffer to the primary input buffer.

COMMAND SYNTAX

MS

NOTES

MS copies the entire content of the secondary input buffer and inserts the parameters before the parameter currently pointed to in the primary input buffer. The primary input buffer must be active when MS is executed. After the move, the secondary input buffer will be empty.

Hold file numbers are returned as Entry #n, where "n" is the hold file number.

EXAMPLE

001 PQN
002 HSP-ASSIGN HS
003 P
004 HCOPY SALES ABC (P
005 P
006 S10
008 MS
...

The COPY command on line 4 creates a print file and the hold file number is written to the SIB. The S10 command on line 6 positions the PIB buffer pointer to parameter 10. The MS command on line 8 moves the contents of the SIB into the PIB starting at the 10th parameter of the PIB.

JCL MV

Copies data between buffers or between buffers and select registers.

COMMAND SYNTAX

MV destination source{,source}...{,*{n}}{,_}

or

MV destination source{*source}...

SYNTAX ELEMENTS

NOTES

If the source is a literal string containing just two double quotes, the destination will be nulled.

If the input buffer (%n) is specified as the destination, it will be selected as the active input buffer and the buffer pointer will left at the beginning of any copied data.

If the field or parameter number in destination is larger than the current number of fields or parameters, intervening null values will be created automatically.

Specify an asterisk (*) as the last character in the source element if you want to copy all the following source buffer parameters. For example:

MV &2.2 %1,*

will copy the 1st parameter of the PIB to field 2 of file buffer 2. Parameter 2 of the PIB will be copied to field 3 and so on.

If you want to copy a series of parameters, specify the number of additional parameters to be copied after the asterisk. For example:

MV &2.2 %1,*3

will copy the 1st, 2nd, 3rd and 4th parameters of the PIB into fields 2, 3, 4 and 5 of file buffer 2. The remainder of file buffer 2 will not be changed.

If you specify a series of values as the source, each value will copied to successive locations in the destination. For example:

MV %2 "ABC"*&2.1*!1

will copy ABC into PIB parameter 2, field 1 of file buffer 2 into PIB parameter 3, and the next value from select register 1 into PIB parameter 4.

Two or more source values separated with an asterisk (*), will be concatenated into a single parameter in the destination. For example:

MV %2 "ABC",&2.1,!1

will concatenate ABC, field 1 of file buffer 2 and the next value from select register 1, and place the result into PIB parameter 2.

Using commas as placeholders in the source can preserve intervening parameters in the destination. For example:

MV %1 "ABC",,,"DEF"

would copy ABC into PIB parameter 1 and DEF into PIB parameter 4. PIB parameters 2 and 3 would not be affected.

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

PIB contains: QTR^ABC^DEF

EXAMPLE 4

EXAMPLE 5

File buffer 2 contains:

000 Key
001 111
002 AAA
003 BBB

EXAMPLE 6

PIB contains: ABC^DEF^GHI^JKL^MNO

JCL MVA

Copies a value from the source to the destination buffer and stores it as a multivalue.

COMMAND SYNTAX

MVA destination source

SYNTAX ELEMENTS

destination is a direct or indirect reference to a buffer or select register which is to receive the data.

source is the data to be copied. The source can be a direct or indirect reference to a buffer or select register, or a literal string.

NOTES

New values will be copies to the destination in ascending ASCII  sequence.

If a new value already exists in the destination buffer, it will not be copied.

If the source data is multivalued, it will be copied to the destination without modification. This might create duplicate values and invalidate the ascending sequence.

If the destination is the input buffer, the buffer pointer will be left at the beginning of the destination parameter.

EXAMPLE 1

PIB contains: ABC^DEF^GHI