# jCL

Updated: 10/19/2020, 10:24:56 AM
Created: 10/19/2020, 10:24:56 AM
Last Updated By: Daniel Klein
Read Time: 10 minute(s)

Introduction Introduction to the jBASE command language.
PQ/PQN Differences Functionality differences between PQ and PQN procs.
A Copies a parameter from the active input buffer to the active output buffer.
B Moves the active input buffer pointer back to the previous parameter.
BO Moves the active output buffer pointer back by one parameter.
C Defines a comment.
D Displays parameters from the active input buffer.
DE Displays the current value of LastError.
DEBUG Turns the jCL debug function on or off.
F Moves the active input buffer pointer forward to the next parameter.
F; Provides a range of arithmetic functions.
F-CLEAR Clears the specified buffer.
F-DELETE Deletes a record from a file.
F-FREE Releases a record lock.
F-KLOSE Closes a specified file buffer.
F-OPEN Opens a file for reading and writing.
F-READ Reads a record from an open file into a file buffer.
F-UREAD Reads and locks a record from an open file into a file buffer.
F-WRITE Writes the contents of a file buffer as a record.
FB Reads a record from a file into the special "fast" buffer without having to open the file first.
G/GO/GOTO Transfers control unconditionally to another location in the program.
GO B Transfers control to the statement following the most recent mark command executed.
GO F Transfers control to the statement containing the next mark command.
GOSUB Transfers control to a specific subroutine.
H Places a text string in the active output buffer.
IBH Places text in the active input buffer whilst retaining embedded spaces.
IBN Prompts for input and places the entered data in the secondary input buffer.
IBP Prompts for input from the terminal.
IF Allows conditional execution of jCL commands based on the evaluation of an expression.
IF E Conditionally executes a command depending on the presence or absence of an error message.
IF S Conditionally executes a command depending on the presence or absence of an active select list.
IFN Allows conditional execution of commands depending on the result of numeric comparisons.
IH Places a text string in the active input buffer.
IN Prompts for input and places it in the secondary input buffer.
IP Prompts for input and places it into the active input buffer or a nominated buffer.
IT Reads a tape record into the primary input buffer.
L Formats printed output.
M Marks a destination for a GO F or GO B command
MS Move the entire content of the secondary input buffer to the primary input buffer.
MV Copies data between buffers or between buffers and select registers.
MVA Copies a value from the source to the destination buffer and stores it as a multivalue.
MVD Deletes a value from a multivalued parameter in the target buffer.
O Outputs a text string to the terminal.
P Submits the shell command created in the primary output buffer for execution.
PQ-RESELECT Executed from a jCL program, resets the pointer of a select register to the beginning of the list of keys.
PQ-SELECT Executed from a jCL program, loads a list of keys into a select register
RI Resets (clears) the primary and secondary input buffers.
RO Resets (clears) the active output buffer.
RSUB Terminates execution of a local subroutine.
RTN Terminates execution of an external subroutine.
S Positions the primary input buffer pointer to a specified parameter or column.
STOFF Selects the primary output buffer as the active output buffer.
STON Selects the secondary output buffer as the active output buffer.
T Produces formatted terminal output.
TR Traces jCL program execution and displays each command before it is executed.
U Executes a user exit from a jCL program.
X Halts execution of the program and returns control to the shell.
PARAGRAPHS Paragraph support in jBASE.

# Overview

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. More information on JCL Commands can be found here.

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

or

#!usr/jbc/bin/jpqn
1

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  control of program flow and to call (and return) or jump to other jCL  programs. Internal and external subroutines are also possible .

# 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 &gt;). 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).

An example is as:

...
10T "Enter file name :",+
IBP %1
F-O 1 %1
T "Cannot open ", %1, "..."\ GO  10
T "File ", %1, " opened OK"
1
2
3
4
5
6

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 &gt; but it must be the first jCL  command on the line. For example, use:

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

not:

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

More information on JCL commands can be found here.

# Comment Lines

Command line which start with a "C" or an "*" are treated as comments. If a comment spans multiple lines, 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.

# Readability

To increase readability and make it easier to edit and debug a jCL  program, 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.

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

PQN
HGET-LIST listname
STON
P
HSORT filename WITH ...
H HEADING "..."
P
1
2
3
4
5
6
7

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:

PQN
MV %2 "string"
MV %1 "Text "*%2*" has been concatenated"
T %1
1
2
3
4

will display "Text string has been concatenated".

# Processing command results

When a command is executed the resulting return codes are returned in the secondary input buffer. To work these you need to move then to the primary input buffer

PQN
HCOUNT MD WITH *A1 = "PQ]"
PH
MS
OI found +
D2+
O procs in the MD.
1
2
3
4
5
6
7

will display "I found {resulting count} procs in the MD".

Detecting if a command resulted in an active select.

PQN
HSELECT MD WITH *A1 = "PQ]"
PH
IF #S GO 99
OI found +
D2+
O procs in the MD.
HCLEARSELECT
PH
X
99 OI was expecting to find some procs...oh well
X
1
2
3
4
5
6
7
8
9
10
11
12

will display "I found {resulting count} procs in the MD" or "I was expecting to find some procs...oh well" (if there weren't any).

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

# Conditional branching

There are two methods of branching (...) and [...]. The (....) method is non returning whereas the [...] method will continue on to the next logical statement.

PQN
HCOUNT MD WITH *A1 = "PQ]"
PH
MS
C If we find some PQ{N} items then run the MD_REPORT proc (which is not provided with jBASE)
C and start at label "20"
IF A2 > 0 (MD MD_REPORT) 20
ONothing to see here...
1
2
3
4
5
6
7
8

will either branch off to MD MD_REPORT starting at label 20 or display "Nothing to see here...".

Back to Reference Guides